abstracttui 0.6.0

//! Screen-text selection + clipboard copy (backlog 0270, tiers 2+3).
//!
//! Terminals in mouse-capture mode route drags to the APPLICATION, so
//! native text selection stops working the moment an app enables wheel
//! scrolling. This module ships the engine-side answers:
//!
//! - **Tier 2 — [`mouse_capture`]**: a cloneable handle that suspends and
//!   resumes mouse reporting at runtime (`set_mouse_reporting(bool)`
//!   shape). While suspended the terminal owns the pointer again — native
//!   drag-select works at native quality; keys still arrive, so apps
//!   typically resume on the next keypress.
//! - **Tier 3 — [`selection`]**: an opt-in engine selection layer. While
//!   enabled, a left-button drag paints a selection highlight (theme
//!   `selection_fg`/`selection_bg`) over the RENDERED screen; releasing
//!   the button — or pressing Enter / `c` / Ctrl+C mid-drag — copies the
//!   selected text to the system clipboard via OSC 52 through the
//!   presenter's byte custody. EVERY copy ends the gesture (backlog
//!   0290): the region clears with the copy, so the app's next
//!   Enter/`c` keystrokes route normally — a retained region used to
//!   silently eat them (the composer footgun). Esc cancels without
//!   copying; a fresh click re-anchors. Wheel scrolling is untouched.
//!
//! ## Click-through (backlog 0285)
//!
//! The layer owns the gesture only once it becomes a DRAG — a plain
//! click belongs to the widgets:
//!
//! - **Left Down with no visible region**: the anchor arms silently and
//!   the event PASSES — the widget under the pointer arms its own
//!   pressed state in parallel (a Button in select mode stays
//!   clickable; consuming every Down made every Button dead by mouse).
//! - **Left Down with a visible region**: the click DISMISSES the
//!   selection — clear and CONSUME (Esc parity: the user was clearing a
//!   highlight, not aiming at the widget beneath), and its paired Up is
//!   consumed too (a gesture is all-or-nothing to the tree).
//! - **First Drag that leaves the anchor cell**: the layer CLAIMS the
//!   gesture — from here Drag and the final Up are the layer's. The
//!   driver resolves the press the tree already saw (a release outside
//!   every rect through the pointer-capture routing), so the pressed
//!   widget un-presses WITHOUT firing and the capture drops. Drags that
//!   stay on the anchor cell remain potential clicks (terminal cell
//!   quantization is the drag slop) and keep passing.
//! - **Up with no drag (a plain click)**: passes — the widget fires.
//! - **[`copy_to_clipboard`]**: the app-reachable clipboard verb (backlog
//!   0150's clipboard leg) — queue any text for OSC 52 emission through
//!   the same custody path, from any component handler.
//!
//! ## Stand-down over drag owners (first-app/1335)
//!
//! Click-through is not enough for a widget that owns DRAGS rather than
//! clicks. A scrollbar thumb arms its grab on the passed-through Down,
//! and the layer's claim one drag later cancelled that press — so the
//! thumb went dead and the user got a highlight instead of a scroll.
//! Every drag surface in the engine had the same defect (the two
//! `Scroll` bars, the `List`/`Table`/`FilePicker` internal bars, the
//! `Viewport3D` orbit).
//!
//! So the anchor asks first. An element declares the sub-rect that owns
//! drags with [`Element::drag_zone`](crate::ui::Element::drag_zone);
//! [`UiTree::press_probe_at`](crate::ui::UiTree::press_probe_at) answers
//! it at Down, and a press inside a zone arms NO anchor. With nothing
//! armed, the later Drag and Up take the existing "not ours" branches
//! and the whole gesture stays with the widget — no claim, no cancelled
//! capture. The ANCHOR decides: a drag that starts in content and
//! crosses a strip keeps selecting.
//!
//! ## A live selection freezes follow-tail (first-app/1300)
//!
//! The region is SCREEN space, so content that keeps scrolling under it
//! turns the copy into a lie: the highlight covers the rows the user
//! aimed at, and the release copies whatever those cells hold by then.
//! While a region is visible the layer therefore calls
//! [`widgets::scroll::freeze_follow_tail`](crate::widgets::scroll::freeze_follow_tail)
//! — every pinned `Scroll` holds its rows still, appends grow below the
//! viewport, and clearing the region (release-copy, Esc, a dismissing
//! click) re-pins to the live tail. Streaming apps need no wiring: what
//! you highlight is what you get, mid-run or idle.
//!
//! ## Honesty: this is SCREEN-text extraction
//!
//! The copied text is what the composed frame shows — glyphs from the
//! flattened cell grid, wide glyphs never split, trailing whitespace
//! trimmed per row, rows joined with `\n`. It is NOT logical widget
//! content: soft-wrapped lines copy as separate rows, and content
//! scrolled out of view cannot be selected. The logical text↔cells
//! mapping is backlog 0160's remaining scope.
//!
//! ## Selection semantics (v1)
//!
//! LINEAR row-flow over the rendered screen, like a terminal's own
//! selection: the first row runs from the anchor to the pane's right
//! edge, middle rows span the pane, the last row runs from the pane's
//! left edge to the head cell (inclusive). Both endpoints clamp to the
//! PANE under the drag anchor — the content box of the nearest clipping
//! or padded ancestor of the deepest view hit at mouse-down (a `Scroll`
//! viewport, a bordered `Block`), else the whole tree — so unrelated
//! panes and border glyphs never leak into a copy.
//!
//! ## Rendering: a post-flatten frame patch
//!
//! The highlight honors the damage contract without a dedicated layer:
//! when the region changes, the old and new row rects are damaged on the
//! root layer BEFORE compositing (the compositor recomposes truth there,
//! full z-stack), and the selection inks are patched into the composed
//! frame AFTER — glyphs kept, colors replaced — so the diff emits only
//! cells that actually changed. Zero idle cost: with no active selection
//! the per-frame hook is one borrow and two empty checks, and the event
//! hook is one `enabled` test.

use std::cell::RefCell;
use std::rc::Rc;

use crate::base::{Point, Rect, Rgba};
use crate::input::{Event, KeyCode, KeyEventKind, Mods, MouseButton, MouseKind};
use crate::reactive::request_frame;
use crate::render::{Cell, Surface};
use crate::ui::PressProbe;

// ---------------------------------------------------------------------------
// Thread-local stores (house pattern: app::theme / app::viewport — the app
// runs on one thread; handles are cheap Rc clones of the same state).
// ---------------------------------------------------------------------------

thread_local! {
    static SELECTION: Rc<RefCell<SelectionState>> =
        Rc::new(RefCell::new(SelectionState::default()));
    static CAPTURE: Rc<RefCell<CaptureState>> =
        Rc::new(RefCell::new(CaptureState::default()));
}

/// The app-thread [`Selection`] handle (same state the driver renders).
pub fn selection() -> Selection {
    Selection {
        state: SELECTION.with(Rc::clone),
    }
}

/// The app-thread [`MouseCapture`] handle (tier-2 suspend verb).
pub fn mouse_capture() -> MouseCapture {
    MouseCapture {
        state: CAPTURE.with(Rc::clone),
    }
}

/// Queue `text` for an OSC 52 clipboard write through the presenter's
/// byte custody — reachable from any component handler (backlog 0150's
/// clipboard leg). The driver emits it with the next frame. Empty or
/// all-whitespace text is refused (an empty OSC 52 payload CLEARS the
/// clipboard — a surprise, never a copy). Capability honesty: terminals
/// that do not advertise OSC 52 get the bytes anyway (harmless — they
/// ignore the frame) plus a one-time labeled startup notice.
pub fn copy_to_clipboard(text: impl Into<String>) {
    let text = text.into();
    if text.trim().is_empty() {
        return;
    }
    SELECTION.with(|s| s.borrow_mut().pending_copies.push(text));
    request_frame();
}

// ---------------------------------------------------------------------------
// Selection (tier 3)
// ---------------------------------------------------------------------------

/// Publish the region's liveness DOWN to the widgets layer (1300): a
/// visible region freezes every follow-tail `Scroll`, so a streaming
/// transcript holds still for the length of the drag. Screen-space
/// selection over auto-scrolling content is otherwise a copy of
/// whatever landed on those cells at release — the highlight says one
/// thing and the clipboard gets another. Called from EVERY state
/// transition that can change `region.is_some()`; the setter is
/// idempotent (`set_if_changed`), so the steady state costs nothing.
fn publish_freeze(st: &SelectionState) {
    crate::widgets::scroll::freeze_follow_tail(st.region.is_some());
}

/// One selection region: anchor + head (screen cells, both inclusive),
/// row-flowed within `clamp` (the pane rect resolved at drag start).
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub(crate) struct Region {
    anchor: Point,
    head: Point,
    clamp: Rect,
}

impl Region {
    /// Endpoints in reading order (by row, then column).
    fn ordered(&self) -> (Point, Point) {
        if (self.anchor.y, self.anchor.x) <= (self.head.y, self.head.x) {
            (self.anchor, self.head)
        } else {
            (self.head, self.anchor)
        }
    }

    /// Per-row screen rects of the linear flow: first row start→pane
    /// right, middle rows the full pane span, last row pane left→end
    /// (end cell inclusive). A single-row region spans min..=max.
    pub(crate) fn row_spans(&self, out: &mut Vec<Rect>) {
        let (s, e) = self.ordered();
        for y in s.y..=e.y {
            let x0 = if y == s.y { s.x } else { self.clamp.x };
            let x1 = if y == e.y {
                e.x + 1
            } else {
                self.clamp.right()
            };
            let rect = Rect::new(x0, y, x1 - x0, 1).intersect(self.clamp);
            if !rect.is_empty() {
                out.push(rect);
            }
        }
    }
}

/// What the driver should do with an intercepted event.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub(crate) enum SelectionAct {
    /// Not ours: route normally.
    Pass,
    /// Consumed by the selection layer (state may have changed).
    Consumed,
    /// Consumed — and this drag just CLAIMED a gesture whose Down had
    /// passed through to the widgets (click-through, backlog 0285). The
    /// driver must resolve the trees' pointer state: deliver a release
    /// outside every rect so the pressed widget un-presses WITHOUT
    /// firing (release-inside-decides) and the pointer capture drops —
    /// otherwise the capture would wedge and route the NEXT click
    /// anywhere to the stale captured widget.
    Claim,
    /// Consumed; copy this region's screen text. The act CARRIES the
    /// region because a copy ENDS the gesture (backlog 0290): the layer
    /// cleared its own state before answering, so no region lingers to
    /// swallow the app's next Enter/`c` keystrokes.
    Copy(Region),
}

/// An armed left press: the anchor cell + the pane clamp resolved at
/// Down, and whether the Down PASSED through to the widget trees
/// (click-through, 0285). A dismissal click's Down was consumed, so its
/// whole gesture stays consumed — all-or-nothing to the tree — and a
/// claim over it releases nothing (nothing was pressed).
#[derive(Copy, Clone, Debug)]
struct DragArm {
    anchor: Point,
    clamp: Rect,
    press_routed: bool,
}

#[derive(Default)]
struct SelectionState {
    enabled: bool,
    /// Left button is down (anchor armed). No region until a drag
    /// leaves the anchor cell — a plain click never paints.
    drag: Option<DragArm>,
    region: Option<Region>,
    /// Row rects patched into the last composed frame (the repair-damage
    /// source when the region changes or clears).
    painted: Vec<Rect>,
    /// Region changed since the last paint: pre-flatten damage owed.
    dirty: bool,
    /// App-queued clipboard texts ([`copy_to_clipboard`]), drained by the
    /// driver into presenter-custody OSC 52 emission.
    pending_copies: Vec<String>,
}

/// Cloneable handle to the engine selection layer. Enabling is the
/// opt-in: apps bind a key to [`Selection::toggle`] for a "select mode",
/// or call [`Selection::set_enabled`] once for always-on drag select.
/// While enabled the layer owns left DRAGS (and the gesture-ending Up);
/// plain clicks pass through to the widgets (click-through, 0285), so
/// buttons and other clickables keep working with select mode on.
#[derive(Clone)]
pub struct Selection {
    state: Rc<RefCell<SelectionState>>,
}

impl Selection {
    /// Turn select mode on or off. Disabling clears any visible
    /// selection (its cells repaint from truth on the next frame).
    pub fn set_enabled(&self, on: bool) {
        let mut st = self.state.borrow_mut();
        if st.enabled == on {
            return;
        }
        st.enabled = on;
        if !on {
            Self::clear_locked(&mut st);
        }
    }

    /// Whether select mode is on.
    pub fn enabled(&self) -> bool {
        self.state.borrow().enabled
    }

    /// Flip select mode; returns the new state.
    pub fn toggle(&self) -> bool {
        let on = !self.enabled();
        self.set_enabled(on);
        on
    }

    /// Whether a selection region is currently visible. Since every
    /// copy ends the gesture (0290), this is true only mid-drag (and
    /// only once the drag actually painted a region — a plain click
    /// never does).
    pub fn is_active(&self) -> bool {
        self.state.borrow().region.is_some()
    }

    /// Clear the visible selection (keeps select mode on).
    pub fn clear(&self) {
        Self::clear_locked(&mut self.state.borrow_mut());
    }

    fn clear_locked(st: &mut SelectionState) {
        st.drag = None;
        if st.region.take().is_some() || !st.painted.is_empty() {
            st.dirty = true;
            request_frame();
        }
        publish_freeze(st);
    }

    // ---- driver plumbing (crate-internal) --------------------------------

    /// Route one kernel event through the selection layer. `probe_at`
    /// resolves the press target under a fresh drag anchor — the pane
    /// rect that clamps it, and whether a widget there already owns
    /// drags (called at most once, on left-down). See the module docs
    /// for the claim rules — wheel, motion, and non-left buttons always
    /// pass.
    pub(crate) fn on_input(
        &self,
        ev: &Event,
        probe_at: &mut dyn FnMut(Point) -> PressProbe,
    ) -> SelectionAct {
        let mut st = self.state.borrow_mut();
        match ev {
            Event::Mouse(m) => {
                if !st.enabled {
                    return SelectionAct::Pass;
                }
                match (m.kind, m.button) {
                    (MouseKind::Down, MouseButton::Left) => {
                        // A fresh press REPLACES any armed gesture, always.
                        // This used to fall out of the unconditional
                        // `st.drag = Some(..)` below; the drag-owner and
                        // no-pane early returns (first-app/1335) skip that
                        // assignment, so a stale arm would survive them.
                        // An arm outlives its gesture whenever the Up is
                        // lost — released outside the terminal, or
                        // `mouse_capture().suspend()` spanning the release
                        // — and a stale arm with `press_routed` set turns
                        // the NEXT widget's drag into a claim, cancelling
                        // the very capture 1335 exists to protect.
                        st.drag = None;
                        let dismissed = st.region.take().is_some();
                        if dismissed {
                            st.dirty = true;
                            request_frame();
                            publish_freeze(&st); // dismissal thaws the tail
                        }
                        let probe = probe_at(m.pos);
                        if probe.drag_owner {
                            // The press landed where a widget already owns
                            // drags (first-app/1335): a scrollbar strip, an
                            // orbit surface. Arm NOTHING — with no anchor
                            // the later Drag/Up take the "not ours"
                            // branches, so the gesture reaches the widget
                            // whole and its pointer capture is never
                            // cancelled. A visible region still dismissed
                            // above (the user cleared it), but the Down
                            // itself PASSES: the widget must see the press
                            // that takes hold of its thumb.
                            return SelectionAct::Pass;
                        }
                        // No pane means the press missed every tree —
                        // there is nothing to clamp a region to, so there
                        // is nothing to select. (`selection_anchor` falls
                        // back to the viewport for a live tree, so this is
                        // the empty-app case.)
                        let Some(clamp) = probe.pane else {
                            return SelectionAct::Pass;
                        };
                        st.drag = Some(DragArm {
                            anchor: clamp_point(m.pos, clamp),
                            clamp,
                            press_routed: !dismissed,
                        });
                        if dismissed {
                            // A click on a VISIBLE selection dismisses it
                            // (Esc parity: the user was clearing the
                            // highlight, not aiming at the widget
                            // beneath): clear + CONSUME. The fresh anchor
                            // still arms — dragging from here selects.
                            SelectionAct::Consumed
                        } else {
                            // Click-through (0285): a plain click belongs
                            // to the widgets — the anchor arms silently
                            // and the Down routes on, so the widget under
                            // the pointer arms its own pressed state. The
                            // layer claims only if a drag follows.
                            SelectionAct::Pass
                        }
                    }
                    (MouseKind::Drag, MouseButton::Left) => {
                        let Some(arm) = st.drag else {
                            // Drag whose Down predates select mode: not ours.
                            return SelectionAct::Pass;
                        };
                        let head = clamp_point(m.pos, arm.clamp);
                        if st.region.is_none() && head == arm.anchor {
                            // Sub-cell wiggle: the pointer never left the
                            // anchor cell, so this is still a potential
                            // click (cell quantization is the drag slop).
                            // The gesture keeps following its Down.
                            return if arm.press_routed {
                                SelectionAct::Pass
                            } else {
                                SelectionAct::Consumed
                            };
                        }
                        let claiming = st.region.is_none();
                        let next = Region {
                            anchor: arm.anchor,
                            head,
                            clamp: arm.clamp,
                        };
                        if st.region != Some(next) {
                            st.region = Some(next);
                            st.dirty = true;
                            request_frame();
                            // The first drag off the anchor cell is the
                            // edge that freezes the tail (1300).
                            publish_freeze(&st);
                        }
                        if claiming && arm.press_routed {
                            // First drag off the anchor cell: the layer
                            // claims a gesture the tree already saw the
                            // Down of — the driver must resolve that
                            // press without a click (see `Claim`).
                            SelectionAct::Claim
                        } else {
                            SelectionAct::Consumed
                        }
                    }
                    (MouseKind::Up, MouseButton::Left) => {
                        let Some(arm) = st.drag.take() else {
                            return SelectionAct::Pass; // orphan release
                        };
                        match st.region.take() {
                            // Release copies AND ends the gesture (0290):
                            // a retained region's only remaining power
                            // was eating the app's next Enter/`c` — the
                            // copy already happened, so nothing of value
                            // is lost by clearing here. The highlight
                            // cells recompose from truth next frame.
                            Some(region) => {
                                Self::clear_locked(&mut st);
                                SelectionAct::Copy(region)
                            }
                            // A drag-less click: the gesture follows its
                            // Down — pass (the widget fires, 0285) when
                            // the Down passed; stay consumed for a
                            // dismissal click's paired release.
                            None => {
                                if arm.press_routed {
                                    SelectionAct::Pass
                                } else {
                                    SelectionAct::Consumed
                                }
                            }
                        }
                    }
                    _ => SelectionAct::Pass, // wheel / motion / other buttons
                }
            }
            Event::Key(k) => {
                // Copy/clear keys exist only while a selection is VISIBLE
                // — i.e. mid-drag now that every copy clears (Ctrl+C
                // stays the default quit otherwise).
                let Some(region) = st.region else {
                    return SelectionAct::Pass;
                };
                if k.kind == KeyEventKind::Release {
                    return SelectionAct::Pass;
                }
                let mods = k.mods.without_locks();
                match k.code {
                    KeyCode::Esc if mods == Mods::NONE => {
                        Self::clear_locked(&mut st);
                        SelectionAct::Consumed
                    }
                    // Key-copy is one-shot (0290): copy AND clear — the
                    // deliberate second act ends the gesture exactly
                    // like the release-copy does.
                    KeyCode::Enter if mods == Mods::NONE => {
                        Self::clear_locked(&mut st);
                        SelectionAct::Copy(region)
                    }
                    KeyCode::Char('c') if mods == Mods::NONE || mods == Mods::CTRL => {
                        Self::clear_locked(&mut st);
                        SelectionAct::Copy(region)
                    }
                    _ => SelectionAct::Pass,
                }
            }
            _ => SelectionAct::Pass,
        }
    }

    /// Pre-flatten hook: when the region changed since the last paint,
    /// damage the OLD painted rects (their cells must recompose from
    /// truth) and the NEW row spans (fresh truth to patch over) on the
    /// root layer surface. Root layer origin is `Point::ZERO`, so screen
    /// and layer-local coordinates coincide.
    pub(crate) fn add_flatten_damage(&self, root: &mut Surface) {
        let mut st = self.state.borrow_mut();
        if !st.dirty {
            return;
        }
        st.dirty = false;
        for &r in &st.painted {
            root.add_damage(r);
        }
        let mut spans = Vec::new();
        if let Some(region) = st.region {
            region.row_spans(&mut spans);
        }
        for r in spans {
            root.add_damage(r);
        }
    }

    /// Post-flatten hook: patch the selection inks over the composed
    /// frame — glyphs kept, `fg`/`bg` replaced — and record what was
    /// painted. Runs every rendered frame while a selection is visible;
    /// cells the compositor did not touch receive byte-identical
    /// rewrites, so the diff emits nothing for them.
    pub(crate) fn paint_into(&self, frame: &mut Surface, fg: Rgba, bg: Rgba) {
        let mut st = self.state.borrow_mut();
        let Some(region) = st.region else {
            st.painted.clear();
            return;
        };
        st.painted.clear();
        let mut spans = Vec::new();
        region.row_spans(&mut spans);
        for span in spans {
            let Some((x0, x1)) = expand_to_glyphs(frame, span) else {
                continue;
            };
            for x in x0..x1 {
                let Some(&cell) = frame.get(x, span.y) else {
                    continue;
                };
                if cell.is_continuation() {
                    continue; // the leader's inks mirror over (pair repair)
                }
                frame.put_composed(x, span.y, Cell { fg, bg, ..cell });
            }
            frame.repair_wide_pairs(span.y, x0, x1);
            st.painted.push(Rect::new(x0, span.y, x1 - x0, 1));
        }
    }

    /// App-queued clipboard texts (drained once per turn by the driver).
    pub(crate) fn take_pending_copies(&self) -> Vec<String> {
        std::mem::take(&mut self.state.borrow_mut().pending_copies)
    }

    /// Fresh-driver reset: a new session starts with no visible
    /// selection and no paint bookkeeping (the new frame is blank), but
    /// the app's mode choice (`enabled`) survives.
    pub(crate) fn reset_session(&self) {
        let mut st = self.state.borrow_mut();
        st.drag = None;
        st.region = None;
        st.painted.clear();
        st.dirty = false;
        publish_freeze(&st);
    }

    /// Resize invalidates screen-space geometry wholesale: clear the
    /// selection (the driver's prev-poison repaints everything anyway).
    pub(crate) fn on_resize(&self) {
        let mut st = self.state.borrow_mut();
        st.drag = None;
        st.region = None;
        st.painted.clear();
        st.dirty = false;
        publish_freeze(&st);
    }
}

/// Clamp `p` into `rect` (inclusive cell coordinates). An empty rect
/// clamps to its origin — callers never produce one (pane rects come
/// from solved layout, the viewport fallback is never empty).
fn clamp_point(p: Point, rect: Rect) -> Point {
    Point::new(
        p.x.clamp(rect.x, (rect.right() - 1).max(rect.x)),
        p.y.clamp(rect.y, (rect.bottom() - 1).max(rect.y)),
    )
}

/// Snap a row span outward so it never splits a wide glyph: a span
/// starting ON a continuation pulls in its leader; a span whose first
/// excluded cell is a continuation pulls it in (its leader is inside).
/// Returns the clamped `x0..x1` walk range, `None` when off-surface.
fn expand_to_glyphs(frame: &Surface, span: Rect) -> Option<(i32, i32)> {
    if span.y < 0 || span.y >= frame.height() {
        return None;
    }
    let mut x0 = span.x.max(0);
    let mut x1 = span.right().min(frame.width());
    if x1 <= x0 {
        return None;
    }
    if frame.get(x0, span.y).is_some_and(Cell::is_continuation) {
        x0 = (x0 - 1).max(0);
    }
    if x1 < frame.width() && frame.get(x1, span.y).is_some_and(Cell::is_continuation) {
        x1 += 1;
    }
    Some((x0, x1))
}

/// What-you-see text of `region` over the composed frame: glyphs resolve
/// through the frame's pool, wide glyphs render once (leader), never
/// split; blank cells read as spaces; trailing whitespace trims per row;
/// rows join with `\n`. Colors are irrelevant — the selection patch only
/// recolors, so extraction after painting reads the same glyphs.
pub(crate) fn extract_text(frame: &Surface, region: &Region) -> String {
    let mut spans = Vec::new();
    region.row_spans(&mut spans);
    let mut out = String::new();
    for (i, span) in spans.iter().enumerate() {
        if i > 0 {
            out.push('\n');
        }
        let row_start = out.len();
        let Some((x0, x1)) = expand_to_glyphs(frame, *span) else {
            continue;
        };
        for x in x0..x1 {
            let Some(cell) = frame.get(x, span.y) else {
                continue;
            };
            if cell.is_continuation() {
                continue; // the leader already rendered both columns
            }
            let g = frame.glyph_str(cell);
            out.push_str(if g.is_empty() { " " } else { g });
        }
        let kept = out[row_start..].trim_end().len();
        out.truncate(row_start + kept);
    }
    out
}

/// Resolve the selection PANE under a fresh drag anchor: the topmost
/// visible overlay TREE layer containing the point answers with its own
/// pane (layer-local walk, mapped back to screen) — mirrors input
/// routing, so dragging over a modal clamps to the modal — else the root
/// tree answers, else the viewport. Always clipped to the viewport;
/// degenerate (empty) panes fall back to the viewport rather than
/// producing an unselectable region.
/// Solve every tree the anchor probe may walk, so
/// [`selection_anchor`] reads rects that exist.
///
/// `UiTree::press_probe_at` is a pure read of solved geometry — it
/// cannot lay out, because the probe runs inside a closure that
/// `Selection::on_input` calls while holding its state borrow, and
/// `layout()` delivers pending autofocus (user handlers, which may
/// re-enter the selection layer). So the driver establishes the
/// precondition instead, exactly as `UiTree::dispatch` does for its own
/// hit test.
///
/// Cheap by construction: `layout()` returns immediately unless the tree
/// is dirty, and the driver calls this only on a left Down.
pub(super) fn layout_for_anchor(app: &mut super::App, overlays: &super::overlays::Overlays) {
    use super::overlays::{OverlayContent, ROOT_LAYER_ID};
    app.tree().layout();
    // Handles are collected BEFORE any solve: `layout()` runs user code,
    // which may open or close a layer, and the store must not be
    // borrowed across that.
    let mut trees: Vec<crate::ui::UiTree> = {
        let store = overlays.store().borrow();
        store
            .meta
            .iter()
            .zip(&store.layers)
            .filter(|(m, l)| m.id != ROOT_LAYER_ID && l.visible())
            .filter_map(|(m, _)| match &m.content {
                OverlayContent::Tree { tree, .. } => Some(tree.handle()),
                _ => None,
            })
            .collect()
    };
    for tree in &mut trees {
        tree.layout();
    }
}

pub(super) fn selection_anchor(
    app: &mut super::App,
    overlays: &super::overlays::Overlays,
    viewport: crate::base::Size,
    p: Point,
) -> PressProbe {
    use super::overlays::{OverlayContent, ROOT_LAYER_ID};
    let vp = Rect::from_size(viewport);
    let mut candidates: Vec<(crate::ui::UiTree, Rect, i32)> = {
        let store = overlays.store().borrow();
        store
            .meta
            .iter()
            .zip(&store.layers)
            .filter(|(m, l)| m.id != ROOT_LAYER_ID && l.visible())
            .filter_map(|(m, l)| match &m.content {
                OverlayContent::Tree { tree, .. } => Some((tree.handle(), l.bounds(), l.z())),
                _ => None,
            })
            .collect()
    };
    candidates.sort_by_key(|(_, _, z)| std::cmp::Reverse(*z));
    for (tree, bounds, _) in candidates {
        if bounds.contains(p) {
            // Overlay trees lay out LAYER-LOCAL: probe in local space,
            // report the pane in screen space. Drag zones inside a drawer
            // or modal therefore stand down like any other (a Scroll in a
            // drawer page owns its thumb too).
            let local = Point::new(p.x - bounds.x, p.y - bounds.y);
            let probe = tree.press_probe_at(local);
            let pane = probe
                .pane
                .map(|r| r.translate(bounds.x, bounds.y))
                .unwrap_or(bounds)
                .intersect(vp);
            return PressProbe {
                pane: Some(if pane.is_empty() { vp } else { pane }),
                drag_owner: probe.drag_owner,
            };
        }
    }
    let probe = app.tree().press_probe_at(p);
    let pane = probe.pane.unwrap_or(vp).intersect(vp);
    PressProbe {
        pane: Some(if pane.is_empty() { vp } else { pane }),
        drag_owner: probe.drag_owner,
    }
}

// ---------------------------------------------------------------------------
// MouseCapture (tier 2)
// ---------------------------------------------------------------------------

#[derive(Default)]
struct CaptureState {
    /// Pending request (latest wins), drained by the driver's next turn.
    requested: Option<bool>,
    /// The last requested posture (for `is_suspended`).
    suspended: bool,
}

/// Cloneable handle suspending/resuming mouse reporting at runtime — the
/// tier-2 "native selection mode" verb. While suspended, the terminal
/// owns the pointer: native drag-select (and its clipboard) works at
/// native quality, and NO mouse events reach the app; keys still arrive,
/// so the conventional shape is suspend-on-keybinding, resume on the
/// next keypress. Requests apply at the driver's next turn (embedders
/// driving their own turns can call `Driver::set_mouse_reporting`
/// directly). Platform note: a job-control `Terminal::suspend` re-enters
/// with the original options, re-arming reporting — suspend again after
/// resume if you keep it off.
#[derive(Clone)]
pub struct MouseCapture {
    state: Rc<RefCell<CaptureState>>,
}

impl MouseCapture {
    /// Request mouse reporting on (`true`, the entered posture) or off
    /// (`false`, terminal-native selection). Latest request wins.
    pub fn set_reporting(&self, on: bool) {
        let mut st = self.state.borrow_mut();
        st.requested = Some(on);
        st.suspended = !on;
        drop(st);
        // A request from a posted job must wake an idle loop; from a key
        // handler this is a no-op frame the turn was running anyway.
        request_frame();
    }

    /// `set_reporting(false)`: hand the pointer back to the terminal.
    pub fn suspend(&self) {
        self.set_reporting(false);
    }

    /// `set_reporting(true)`: re-arm the entered mouse mode.
    pub fn resume(&self) {
        self.set_reporting(true);
    }

    /// The requested posture (applied by the driver's next turn).
    pub fn is_suspended(&self) -> bool {
        self.state.borrow().suspended
    }

    /// Driver drain: the pending request, if any (latest wins).
    pub(crate) fn take_request(&self) -> Option<bool> {
        self.state.borrow_mut().requested.take()
    }
}

#[cfg(test)]
#[path = "selection_tests.rs"]
mod tests;