teksilo_widgets/

rich_text.rs

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2026 FernTech

//! Rich text editor and viewer widget.
//!
//! Two construction presets share the same implementation: [`RichTextEditor::editor`]
//! provides a full editing surface (blinking caret, keyboard commands, clipboard,
//! undo/redo, `Role::MultilineTextInput`) and [`RichTextEditor::read_only`] is a
//! view-only surface (hidden caret, mutations rejected, `Role::Document`). Both
//! bind to an external [`TextDocument`]
//! via `on_change` subscriptions, so any number of editors and viewers can share
//! one document and observe each other's edits live.
//!
//! The widget owns a per-widget `RichTextEngine` (typesetter), and drives its own
//! scroll bars independently of `ScrollArea` to avoid the wrap/scrollbar circular
//! measurement dependency. Use [`RichTextEditor::min_lines`] /
//! [`RichTextEditor::max_lines`] to switch from greedy sizing to intrinsic
//! (messenger-composer) sizing. A detachable [`EditorHandle`] lets toolbars and
//! palette panels issue formatting commands from closures that cannot borrow the
//! editor directly.
//!
//! ```ignore
//! use teksilo_text::text_document::TextDocument;
//! let doc = TextDocument::new();
//! let editor = RichTextEditor::editor(doc)
//!     .min_lines(3)
//!     .max_lines(8)
//!     .wrap_mode(WrapMode::Word);
//! ```
//!
//! ## Pan to scroll
//!
//! The surface installs [`common::scrollable::ScrollableBehavior`](crate::common::scrollable::ScrollableBehavior)
//! — the shared wheel arithmetic, a finger's pan, and the `PanClaim`. The wheel
//! path is unchanged: no tween (these offsets are plain signals), 16 dp a line,
//! `Ignored` at a hard boundary so the page around it takes the rest, and a
//! repaint asked for exactly when an axis moved.
//!
//! **The claim serves this surface even though it also owns the press
//! arena**, which its double- and triple-tap recognizers give it. The router
//! stops its arbitration walk at the press owner only for a `Gesture` member,
//! whose recognizer the capture dispatch is already driving; a `Pan` member is
//! decided in that walk and nowhere else, so it is exempt. A finger on the
//! text therefore scrolls the text, and hands the gesture outward only at this
//! surface's own boundary. See `docs/kinetic-scrolling.md` §10.1.

mod body;
pub mod caret_highlight;
mod clipboard;
mod context_menu;
mod find_session;
mod frame_loop;
// `pub(crate)` so the code editor can reuse the hit-test wrapper rather than
// re-deriving pointer-to-offset resolution. Both surfaces ask the same engine
// the same question; the answer should not have two implementations.
pub(crate) mod hit_test;
pub(crate) mod image_cache;
mod keyboard;
mod lists;
mod mouse;
mod nesting;
pub(crate) mod paint;
mod policy;
mod reading_order;
mod state;
pub(crate) mod touch;
pub(crate) mod touch_mount;

pub use self::lists::list_style_is_ordered;

#[cfg(test)]
mod lists_tests;
#[cfg(test)]
mod nesting_tests;
#[cfg(test)]
mod table_selection_tests;
#[cfg(test)]
mod tests;
#[cfg(test)]
mod touch_tests;
#[cfg(test)]
mod window_tests;

pub use context_menu::{
    INTENT_COPY, INTENT_CUT, INTENT_PASTE, INTENT_PASTE_UNFORMATTED, INTENT_SELECT_ALL,
};
pub use find_session::FindSession;
pub use hit_test::ContextTarget;
pub use policy::{
    AccessibilityRole, CaretPolicy, ClipboardPolicy, CommandFilter, EDITOR_PRESET, EditCommandKind,
    PolicyBundle, READ_ONLY_PRESET,
};

use std::cell::Cell;
use std::rc::Rc;

use teksilo_canvas::{Canvas, Point, Rect, Size, SizeProposal};
use teksilo_core::accessibility::AccessNodeBuilder;
use teksilo_core::build_context::BuildContext;
use teksilo_core::color_prop::ColorProp;
use teksilo_core::signal::Signal;
use teksilo_core::styles::{
    RichTextEditorStyle, RichTextEditorStyleConfig, SharedRichTextEditorStyle,
};
use teksilo_core::widget::{CursorIcon, LayoutContext, PaintContext, Widget, WidgetPlacement};
use teksilo_core::widget_builder::HandlerSet;
use teksilo_core::widget_builder::WidgetBuilder as _;
use teksilo_core::widget_id::WidgetId;
use teksilo_text::text_document::{
    Alignment, BlockFormat, CharVerticalAlignment, LinkExtent, ListStyle, MoveMode, ResourceType,
    SelectionType, TextDirection, TextDocument, TextFormat,
};
use teksilo_text::{
    EditorTypographyDefaults, FontRegistrar, RichTextEngine, SharedTypesetter, WrapMode,
};

use self::paint::{PaintParams, paint_frame};
use self::state::{EditorState, SharedState};
use crate::common::scroll::OverscrollBehavior;
use crate::scroll_bar::{ScrollBar, ScrollBarOrientation, ScrollBarVariant};
use crate::styles::RecipeRichTextEditorStyle;

/// Scroll bar visibility policy for [`RichTextEditor`], applied independently per axis.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ScrollPolicy {
    /// Show the scroll bar only when content overflows the visible area (default).
    #[default]
    Auto,
    /// Always show the scroll bar, reserving gutter space even when content fits.
    AlwaysOn,
    /// Never show the scroll bar; useful when embedding the editor inside an outer
    /// `ScrollArea` or in headless tests.
    AlwaysOff,
}

/// How a piece of text reached the document — the **channel**, not the author.
///
/// Deliberately framework-generic, and deliberately small. These are the routes
/// a toolkit can actually observe: which input path the characters came down.
/// What that *means* is the application's to decide, and every application will
/// decide differently — a writing tool cares that dictation is not typing, a
/// code editor cares that a snippet is not either, and a form cares about none
/// of it. Teksilo says what it saw; it does not interpret.
///
/// ⚠ **Not evidence of who wrote anything.** Text typed one character at a time
/// was typed one character at a time, and that is the entire claim. Anything
/// further — who, or whether a person at all — is an inference this cannot make
/// and no consumer of it should pretend to.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum EditSource {
    /// Typed, one key at a time.
    Keyboard,
    /// The settled result of an IME composition — CJK/Kana candidate selection,
    /// a dead-key accent. Separate from [`Self::Keyboard`] because the
    /// characters that land are not the keys that were pressed.
    Ime,
    /// Pasted, as plain text or as HTML.
    Clipboard,
    /// Arrived through an assistive technology: AccessKit's `SetValue` or
    /// `ReplaceSelectedText`, which is how dictation and a braille display
    /// write.
    ///
    /// **Never folded into [`Self::Keyboard`].** For some people this *is*
    /// typing, and a toolkit that reported it as something else — or as nothing
    /// — would be quietly erasing how they work.
    Accessibility,
    /// Inserted by the application itself rather than by anything the person at
    /// the keyboard did: a template, a substitution, a completion.
    Programmatic,
}

/// The main rich text widget. Construct via [`RichTextEditor::read_only`]
/// (view/select only) or [`RichTextEditor::editor`] (full editing).
pub use self::state::TextAnnotationSpan;

pub struct RichTextEditor {
    state: SharedState,
    v_scroll_policy: ScrollPolicy,
    h_scroll_policy: ScrollPolicy,
    /// Whether to install the built-in context-menu factory during
    /// `build()`. Defaults to `true`. Set `false` via
    /// [`default_context_menu`](Self::default_context_menu) to suppress
    /// the default entirely (right-click then bubbles past the widget;
    /// `context_target_at` stays available for apps that render their
    /// own menu).
    default_context_menu_enabled: bool,
    /// User-supplied context-menu factory (see
    /// [`context_menu`](Self::context_menu)). When set, it takes
    /// precedence over the default factory regardless of
    /// `default_context_menu_enabled`. Taken out (via `Option::take`)
    /// during `build()` because `Box<dyn Fn>` is not `Clone`.
    custom_context_menu: Option<
        Box<
            dyn Fn(
                teksilo_canvas::Point,
                &mut teksilo_core::widget::EventContext,
            ) -> Option<Box<dyn teksilo_core::widget::Widget>>,
        >,
    >,
    /// Minimum visible-text height expressed in lines. When set,
    /// switches `size_that_fits` from greedy (consume the proposal)
    /// to **intrinsic** sizing — see [`min_lines`](Self::min_lines).
    min_lines: Option<u32>,
    /// Maximum visible-text height expressed in lines. Hard-caps
    /// the intrinsic height — see [`max_lines`](Self::max_lines).
    max_lines: Option<u32>,
    /// Per-call style override for the chrome (border, padding, focus
    /// ring). Replaces the theme-wide `style_slots.rich_text_editor`
    /// and the default [`RecipeRichTextEditorStyle`] for just this
    /// editor.
    style_override: Option<SharedRichTextEditorStyle>,
    /// Root of the composed subtree returned by
    /// [`RichTextEditorStyle::make_body`]. Cached so layout queries
    /// route through the chrome without re-running the style call.
    root_child_id: Option<WidgetId>,
    /// The body that holds the text: the node that stands for the editor
    /// in the accessibility tree (see `Widget::accessibility_proxy`).
    body_id: Option<WidgetId>,
    /// Accessible name, set via [`label`](Self::label) and applied to the
    /// body.
    label: Option<teksilo_i18n::LocalizedString>,
    /// Vertical scrollbar child id. `None` when
    /// `v_scroll_policy == ScrollPolicy::AlwaysOff` — in that case
    /// the scrollbar isn't even instantiated.
    v_scrollbar_id: Option<WidgetId>,
    /// Horizontal scrollbar child id. `None` when
    /// `h_scroll_policy == ScrollPolicy::AlwaysOff`.
    h_scrollbar_id: Option<WidgetId>,
    /// Scrollbar **widget-local** bounds, written by `place_children` and
    /// read by the wrapper's `on_pointer_event` handler. Used to bail
    /// out of the drag-select latch when the press lands over an
    /// overlay scrollbar — without this guard the preview-pass pointer
    /// handler on the wrapper runs *before* the scrollbar (its child)
    /// gets the event, sets `drag_state = Selecting` on text under the
    /// overlay, and then steals every subsequent `PointerMove` with
    /// `EventResponse::Handled`, so the scrollbar's gesture arena
    /// never sees the drag.
    v_scrollbar_bounds: Rc<Cell<Rect>>,
    h_scrollbar_bounds: Rc<Cell<Rect>>,
    /// Per-edge `(top, right, bottom, left)` padding between the text
    /// content and the chrome. `None` lets the style apply its own
    /// default (TextInput-style insets for editable, no padding for
    /// read-only). Set via [`content_padding`](Self::content_padding) /
    /// [`content_padding_symmetric`](Self::content_padding_symmetric) /
    /// [`content_padding_each`](Self::content_padding_each).
    content_padding: Option<(f32, f32, f32, f32)>,
    /// Wheel scroll-chaining behavior at the editor's scroll boundary.
    /// [`OverscrollBehavior::Chain`] (the default) declines a wheel event the
    /// editor can no longer absorb so it bubbles to an ancestor scrollable —
    /// the editor embedded in a scrolling form/page hands the leftover scroll
    /// to the page. [`OverscrollBehavior::Contain`] absorbs the event at the
    /// boundary instead. Mirrors the identical knob on `ScrollArea` /
    /// `ListView` / `TableView` / `GridView`. See
    /// [`overscroll_behavior`](Self::overscroll_behavior).
    overscroll_behavior: OverscrollBehavior,
    /// The touch-selection mount: the controller, its two overlays, and the
    /// host intent behind the selection toolbar.
    ///
    /// Minted with the widget rather than in `build()` so the ids and the
    /// toolbar intent survive a rebuild, exactly as the single-line stack's
    /// does. Inert for a mouse: every entry point begins by asking whether the
    /// pointer is direct.
    touch: Rc<touch_mount::EditorTouch>,
}

impl std::fmt::Debug for RichTextEditor {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("RichTextEditor")
            .field("policy", &self.state.borrow().policy)
            .finish_non_exhaustive()
    }
}

impl RichTextEditor {
    /// Construct a read-only rich text viewer bound to `document`. The
    /// document can also back an editable `RichTextEditor::editor` in
    /// another part of the UI — both widgets receive document events
    /// independently via `on_change` subscriptions.
    pub fn read_only(document: TextDocument) -> Self {
        // A viewer defaults to *bare*: it can mirror the same shared document
        // as an editor pane, but stays free of the document's search / spell /
        // syntax highlighting (those are authoring affordances). Opt back in
        // with `.show_highlights(true)` — e.g. a read-only code viewer that
        // *wants* syntax coloring.
        Self::construct(document, READ_ONLY_PRESET).show_highlights(false)
    }

    /// Construct an editable rich text editor bound to `document`.
    /// Uses the full editor preset: every command accepted, caret
    /// blinks, `MultilineTextInput` accessibility role, full clipboard
    /// support. Multiple editors on the same document share live edits
    /// via per-widget `on_change` subscriptions.
    pub fn editor(document: TextDocument) -> Self {
        Self::construct(document, EDITOR_PRESET)
    }

    fn construct(document: TextDocument, policy: PolicyBundle) -> Self {
        // Start with a private engine. `build()` swaps it for one that
        // shares the application's `SharedTypesetter` when one is
        // reachable via `ctx.app_state`, so rendered glyphs land in
        // the atlas that teksilo-render actually uploads to the GPU.
        // Outside a windowed teksilo-app (headless tests) the private
        // engine is correct: no renderer is ever invoked.
        let mut engine = RichTextEngine::private_default();
        engine.set_wrap_mode(WrapMode::Word);
        // Prose editor: hyphenate justified paragraphs. Single-line / label
        // widgets (e.g. TextInputField) deliberately don't enable this.
        engine.set_hyphenate_justified(true);
        let state = EditorState::new(document, engine, policy, WrapMode::Word);
        let touch = touch::mount_for(state.clone());
        Self {
            state,
            v_scroll_policy: ScrollPolicy::Auto,
            h_scroll_policy: ScrollPolicy::Auto,
            default_context_menu_enabled: true,
            custom_context_menu: None,
            min_lines: None,
            max_lines: None,
            style_override: None,
            root_child_id: None,
            body_id: None,
            label: None,
            v_scrollbar_id: None,
            h_scrollbar_id: None,
            v_scrollbar_bounds: Rc::new(Cell::new(Rect::ZERO)),
            h_scrollbar_bounds: Rc::new(Cell::new(Rect::ZERO)),
            content_padding: None,
            overscroll_behavior: OverscrollBehavior::default(),
            touch,
        }
    }

    /// Accessible name for the editor.
    ///
    /// Applied to the body that holds the text, which is the node focus is
    /// published on and the one a screen reader announces: "Notes, entry" for
    /// an editor, "Chapter one, document" for a viewer. The editor's own node
    /// is structure that no adapter shows. An `.access_label(..)`,
    /// `.access_labelled_by(..)` or tooltip attached to the editor reaches the
    /// same node.
    ///
    /// Stays locale-reactive: a `tr!(...)` name is re-resolved when the
    /// locale changes, without a rebuild.
    pub fn label(mut self, label: impl Into<teksilo_i18n::LocalizedString>) -> Self {
        self.label = Some(label.into());
        self
    }

    /// Per-call style override for the editor chrome (border, padding,
    /// focus ring). Replaces the theme-wide
    /// `style_slots.rich_text_editor` and the IntUI default
    /// `RecipeRichTextEditorStyle` for just this editor.
    pub fn style(mut self, style: impl RichTextEditorStyle) -> Self {
        self.style_override = Some(Rc::new(style));
        self
    }

    /// Set a uniform padding (logical pixels) between the text content
    /// and the editor's chrome. Replaces the style's default insets
    /// (TextInput-style for editable, none for read-only). Use
    /// [`content_padding_symmetric`](Self::content_padding_symmetric) or
    /// [`content_padding_each`](Self::content_padding_each) for
    /// per-axis / per-edge control.
    pub fn content_padding(mut self, amount: f32) -> Self {
        self.content_padding = Some((amount, amount, amount, amount));
        self
    }

    /// Set vertical and horizontal padding (logical pixels) between the
    /// text content and the editor's chrome. Replaces the style's
    /// default insets.
    pub fn content_padding_symmetric(mut self, vertical: f32, horizontal: f32) -> Self {
        self.content_padding = Some((vertical, horizontal, vertical, horizontal));
        self
    }

    /// Set per-edge padding `(top, right, bottom, left)` between the
    /// text content and the editor's chrome. Replaces the style's
    /// default insets.
    pub fn content_padding_each(mut self, top: f32, right: f32, bottom: f32, left: f32) -> Self {
        self.content_padding = Some((top, right, bottom, left));
        self
    }

    /// Set just the top inset between the text and the chrome. Leaves
    /// the other edges at their previously-set values, defaulting to
    /// `0.0` for any edge never touched.
    pub fn content_padding_top(mut self, top: f32) -> Self {
        let (_, r, b, l) = self.content_padding.unwrap_or((0.0, 0.0, 0.0, 0.0));
        self.content_padding = Some((top, r, b, l));
        self
    }

    /// Set just the right inset between the text and the chrome.
    pub fn content_padding_right(mut self, right: f32) -> Self {
        let (t, _, b, l) = self.content_padding.unwrap_or((0.0, 0.0, 0.0, 0.0));
        self.content_padding = Some((t, right, b, l));
        self
    }

    /// Set just the bottom inset between the text and the chrome.
    pub fn content_padding_bottom(mut self, bottom: f32) -> Self {
        let (t, r, _, l) = self.content_padding.unwrap_or((0.0, 0.0, 0.0, 0.0));
        self.content_padding = Some((t, r, bottom, l));
        self
    }

    /// Set just the left inset between the text and the chrome.
    pub fn content_padding_left(mut self, left: f32) -> Self {
        let (t, r, b, _) = self.content_padding.unwrap_or((0.0, 0.0, 0.0, 0.0));
        self.content_padding = Some((t, r, b, left));
        self
    }

    // --- Builder methods ------------------------------------------------

    /// Set the line-wrap mode. `WrapMode::Word` (the default) wraps at word
    /// boundaries; `WrapMode::None` allows horizontal overflow — pair with
    /// `.h_scroll_policy(ScrollPolicy::Auto)` to expose a scroll bar.
    pub fn wrap_mode(self, mode: WrapMode) -> Self {
        {
            let mut st = self.state.borrow_mut();
            st.wrap_mode = mode;
            st.engine.set_wrap_mode(mode);
            st.needs_full_layout = true;
        }
        self
    }

    /// Whether this view applies the document's syntax / search / spell
    /// highlighting. `editor` defaults to `true`; `read_only` defaults to
    /// `false` (a bare preview). A highlights-off view pulls a *clean*
    /// snapshot (no highlights at all, even metric ones like keyword bold) and
    /// ignores paint-only highlight events entirely, so it does zero work when
    /// the shared document's search/spell highlights change.
    pub fn show_highlights(self, show: bool) -> Self {
        {
            let mut st = self.state.borrow_mut();
            if st.show_highlights != show {
                st.show_highlights = show;
                // Re-pull the snapshot in the new flavor on the next tick.
                st.needs_full_layout = true;
            }
        }
        self
    }

    /// Declare the annotations (comment threads) covering ranges of this
    /// document, for the **accessibility tree only**.
    ///
    /// Each span becomes a `Role::Comment` node, and every `Role::TextRun` it
    /// covers points at it through AccessKit's `details` relation — the W3C
    /// annotations pattern, and the reason a screen reader can say "has comment"
    /// and let the user navigate in rather than reciting the thread every time the
    /// caret crosses the span.
    ///
    /// Painting is a separate concern: a highlight session draws the underline. A
    /// highlight carries no text and this carries no colour, so neither is
    /// derivable from the other and both are supplied independently.
    pub fn annotation_spans(self, spans: Vec<TextAnnotationSpan>) -> Self {
        self.state.borrow_mut().annotation_spans = spans;
        self
    }

    /// Set which highlight sessions **this view** renders, at runtime.
    ///
    /// [`HighlightMask::all`](teksilo_text::text_document::HighlightMask::all) shows every
    /// session on the document (the default);
    /// [`HighlightMask::only`](teksilo_text::text_document::HighlightMask::only) shows a
    /// chosen set — which is how a per-editor find banner
    /// keeps one pane's find highlighting out of another pane over the same document.
    /// `show_highlights(false)` still overrides this to nothing.
    ///
    /// Forces a re-pull on the next tick so the change is visible immediately.
    pub fn set_highlight_mask(&self, mask: teksilo_text::text_document::HighlightMask) {
        let mut st = self.state.borrow_mut();
        if st.highlight_mask != mask {
            st.highlight_mask = mask;
            st.needs_full_layout = true;
            // A mask change fires no document event, so the AT-cache invalidation the
            // event path does won't run — do it here. Dropping a metric session (syntax
            // bold) out of this view changes what the AT tree should report, and a stale
            // cached tree would keep announcing formatting the pane no longer draws.
            st.invalidate_accessibility_cache();
        }
    }

    /// Set the initial non-destructive default typography (font family / line
    /// height / first-line indent) applied to runs and blocks that carry no
    /// explicit override. Applied before the first layout. These are display
    /// defaults — they never mutate the bound document (no undo entry, no
    /// `modified`); use [`set_typography_defaults`](Self::set_typography_defaults)
    /// or [`EditorHandle::set_typography_defaults`] to change them after mount.
    /// Preferred text size is [`font_size_scale`](Self::font_size_scale).
    pub fn typography_defaults(self, defaults: EditorTypographyDefaults) -> Self {
        {
            let mut st = self.state.borrow_mut();
            st.engine.set_typography_defaults(defaults);
            st.needs_full_layout = true;
        }
        self
    }

    /// Override the editor background fill. Accepts a `Color`, a theme role
    /// (`SurfaceRole::Content`, …), or a `Signal`. Threaded into the active
    /// [`RichTextEditorStyle`]'s `make_body`, so the common case ("give the
    /// editor a surface") needs no custom style. `None` uses the style's
    /// default surface.
    pub fn background(self, color: impl Into<ColorProp>) -> Self {
        self.state.borrow_mut().background_prop = Some(color.into());
        self
    }

    /// Override the selection-highlight color. Accepts a `Color`, theme role,
    /// or `Signal`. Resolved against the active theme on every paint; `None`
    /// uses the engine/theme default.
    pub fn selection_color(self, color: impl Into<ColorProp>) -> Self {
        self.state.borrow_mut().selection_color_prop = Some(color.into());
        self
    }

    /// Override the caret / insertion-point color. Accepts a `Color`, theme
    /// role, or `Signal`. Resolved against the active theme on every paint;
    /// `None` tracks the theme's `editor_caret` role.
    pub fn caret_color(self, color: impl Into<ColorProp>) -> Self {
        self.state.borrow_mut().caret_color_prop = Some(color.into());
        self
    }

    /// Override the default text color. Accepts a `Color`, theme role, or
    /// `Signal`. Resolved against the active theme on every paint; `None`
    /// tracks the theme's `editor_fg` role (so dark / light swaps follow
    /// automatically). A role or `Signal` stays reactive; a bare `Color` pins
    /// it.
    pub fn text_color(self, color: impl Into<ColorProp>) -> Self {
        self.state.borrow_mut().text_color_prop = Some(color.into());
        self
    }

    /// Set the vertical scroll-bar visibility policy.
    pub fn v_scroll_policy(mut self, policy: ScrollPolicy) -> Self {
        self.v_scroll_policy = policy;
        self
    }

    /// Set the horizontal scroll-bar visibility policy.
    pub fn h_scroll_policy(mut self, policy: ScrollPolicy) -> Self {
        self.h_scroll_policy = policy;
        self
    }

    /// Window paint-time culling to the accumulated ancestor clip rather than
    /// this editor's own bounds.
    ///
    /// Enable this **only** for an editor deliberately laid out at its full
    /// document height inside an outer [`ScrollArea`](crate::ScrollArea)
    /// (`v_scroll_policy(ScrollPolicy::AlwaysOff)`, no `max_lines`) — "dubious
    /// mode". Such an editor's own viewport spans the whole document, so the
    /// viewport-derived render cull keeps nothing; this makes it cull to the
    /// visible clip band instead, so a huge document only rasterizes the rows on
    /// screen. Correct under nested ScrollAreas (the clip is the intersection of
    /// all clipping ancestors), and positioning / hit-testing are unaffected.
    ///
    /// A normal self-scrolling editor already culls correctly from its own scroll
    /// offset and doesn't need this — leave it **off** (the default). (The window
    /// is computed relative to the editor's own scroll offset as well, so enabling
    /// it on a self-scroller degrades to a correct-but-redundant cull rather than
    /// rendering the wrong rows.)
    /// Guess this editor's height from its text until something has laid it out.
    ///
    /// `content_height()` is `0` until `layout_full` has run, and that waits for the
    /// editor to have been through a frame on screen. The zero falls through to the
    /// `min_lines` floor, so an editor that has never been shown claims the same few
    /// lines whatever it holds.
    ///
    /// For an editor that **is** on screen that is invisible — it lays out on the
    /// first frame and the floor never shows. Turn this on for one that may not be:
    /// a row of a long column, most of which is below the fold. There the page's
    /// height is the sum of its rows' claims, so the scroll extent starts wrong by an
    /// order of magnitude and settles a row at a time as the reader arrives — and
    /// anything drawing that extent draws the settling.
    ///
    /// Off by default, deliberately. The estimate is crude by construction, and an
    /// editor that lays out immediately gains nothing from it while every consumer of
    /// its first-frame size pays for the guess — including the windowed-render path,
    /// whose culling is derived from the editor's own bounds.
    ///
    /// Never a floor: it goes through the same clamp a real height does, so
    /// `max_lines` still caps it and an over-estimate corrects downwards when the
    /// layout lands.
    pub fn estimate_height_before_layout(self, on: bool) -> Self {
        self.state.borrow_mut().estimate_height_before_layout = on;
        self
    }

    pub fn window_to_clip(self, on: bool) -> Self {
        self.state.borrow_mut().window_to_clip = on;
        self
    }

    /// Set the same scroll-bar visibility policy on both axes.
    pub fn scroll_policy(mut self, policy: ScrollPolicy) -> Self {
        self.v_scroll_policy = policy;
        self.h_scroll_policy = policy;
        self
    }

    /// Whether moving the caret also scrolls any *enclosing* scroll area to
    /// keep the caret on screen — the standard editor "caret stays visible as
    /// you type / navigate" behaviour. **On by default.**
    ///
    /// It fires only on a caret *move*, never on a plain wheel / scrollbar
    /// scroll, so the reader can still scroll freely away from the caret and the
    /// view holds until the caret next moves. This is what makes an editor that
    /// **grows** to its content with its own scroll suppressed (a flowing page
    /// inside an outer `ScrollArea`) track the caret at all — there the editor's
    /// internal caret-visibility is a no-op, so the enclosing-page follow is the
    /// only mechanism that reveals the caret. Pass `false` for the rare layout
    /// where a caret change must never move the surrounding page.
    pub fn follow_caret_in_page(self, follow: bool) -> Self {
        self.state.borrow_mut().follow_caret_in_page = follow;
        self
    }

    /// **Typewriter scrolling**: pin the caret's line at `fraction` of the way
    /// down the enclosing scroll area — `0.0` at the top, `0.5` centred, `1.0`
    /// at the bottom — and let the document scroll under it. `None` (the
    /// default) leaves the ordinary minimal-reveal follow in charge.
    ///
    /// Unlike that follow, which only acts once the caret would leave the
    /// viewport, a pin re-asserts on every caret move, so the line being written
    /// holds a constant height on screen. The classic writing-app feature.
    ///
    /// Three behaviours come with it, each of them the consensus answer among
    /// the editors that ship this well:
    ///
    /// - **The pointer stands the pin down.** A click places the caret without
    ///   scrolling, and that position becomes the new resting place; a
    ///   drag-selection is never interrupted. The next keystroke resumes
    ///   pinning. Editors that re-centre on pointer input instead have open bugs
    ///   about the view fighting the mouse and about drag-selection becoming
    ///   unusable.
    /// - **The rendered row is pinned, not the paragraph.** Under soft wrap a
    ///   long paragraph spans several visual rows; pinning the logical line
    ///   would leave the caret far from the mark.
    /// - **Typing snaps, page jumps glide.** Animating a pin that updates on
    ///   every keystroke is what produces the "screen bouncing" complaint other
    ///   implementations attract.
    ///
    /// Requires [`follow_caret_in_page`](Self::follow_caret_in_page) (on by
    /// default). `fraction` is clamped to `0.0..=1.0`.
    ///
    /// Near the start of the document the pin gives way to the scroll range —
    /// the caret rides above its line until there is room — and near the end it
    /// would do the same, which is usually not what you want: pair this with
    /// `ScrollArea::scroll_past_end(1.0 - fraction)` so the last line can still
    /// reach the pin.
    ///
    /// Takes a plain value, like [`typography_defaults`](Self::typography_defaults);
    /// to follow a setting live, push changes onto the handle with
    /// [`EditorHandle::set_typewriter`].
    pub fn typewriter(self, anchor: Option<f32>) -> Self {
        self.state.borrow_mut().typewriter = anchor.map(|f| f.clamp(0.0, 1.0));
        self
    }

    /// Set the wheel scroll-chaining behavior at the editor's boundary
    /// (default [`OverscrollBehavior::Chain`]). With `Chain`, a wheel event the
    /// editor can no longer absorb (already at the top/bottom, or content that
    /// fits so there is nothing to scroll) is declined so it bubbles to an
    /// ancestor scrollable — an editor embedded in a scrolling form/page lets
    /// the page scroll once the editor reaches its edge.
    /// [`OverscrollBehavior::Contain`] keeps the event at the editor instead.
    /// Mirrors the identical knob on `ScrollArea` / `ListView` / `TableView` /
    /// `GridView`.
    pub fn overscroll_behavior(mut self, behavior: OverscrollBehavior) -> Self {
        self.overscroll_behavior = behavior;
        self
    }

    /// Set a minimum height (in lines of text) for the editor's
    /// **intrinsic** size.
    ///
    /// Setting either `min_lines` or [`max_lines`](Self::max_lines)
    /// switches the editor from greedy sizing (consume the
    /// proposal) to intrinsic sizing: `size_that_fits` returns
    /// `clamp(content_height, min_lines × line_height, max_lines × line_height)`
    /// for the dimension the parent leaves unspecified. A parent
    /// like `VStack` proposes unbounded height to non-Expand
    /// children, so the editor lands at its intrinsic height —
    /// exactly the messenger-composer / chat-input pattern.
    ///
    /// A parent that *forces* the height (e.g. `FixedSize`) wins
    /// regardless. This is intentional and matches Teksilo's
    /// general layout discipline: parents always have the final
    /// say on the dimensions they pin.
    ///
    /// `min_lines` measures the *visible text area*, not the outer
    /// widget — `min_lines(1)` reports a height equal to one line
    /// of text at the typesetter's default font + size, even
    /// before the document has any content.
    pub fn min_lines(mut self, n: u32) -> Self {
        self.min_lines = Some(n);
        self
    }

    /// Set a maximum height (in lines of text) for the editor's
    /// intrinsic size. Past this cap the vertical scroll bar
    /// absorbs further content growth.
    ///
    /// See [`min_lines`](Self::min_lines) for the intrinsic-mode
    /// switch and the parent-proposal interaction. `max_lines`
    /// measures the visible text area, not the outer widget.
    pub fn max_lines(mut self, n: u32) -> Self {
        self.max_lines = Some(n);
        self
    }

    /// Whether this editor's text grows with the global accessibility text
    /// scale (`ctx.text_scale`). Defaults to `true` — like every other text
    /// surface, the editor magnifies when the user raises the app-wide text
    /// size. Pass `false` for an editor whose font sizes are **document
    /// content** (a WYSIWYG / print-layout editor) that must stay at its true
    /// point size regardless of the reader's UI accessibility setting.
    ///
    /// Composed with [`font_size_scale`](Self::font_size_scale):  
    /// `engine.font_scale = (follow ? text_scale : 1.0) × font_size_scale`.
    pub fn follow_text_scale(self, follow: bool) -> Self {
        self.state.borrow_mut().follow_text_scale = follow;
        self
    }

    /// Per-editor logical font-size multiplier (`1.0` = 100 %). Applied
    /// *before* shaping (same channel as accessibility text scale), so text
    /// grows, re-wraps, and stays sharp — the knob for a "Text size"
    /// preference. Composed as
    /// `(follow_text_scale ? ctx.text_scale : 1.0) × font_size_scale`.
    /// Clamped to `[0.1, 10.0]`. Use [`set_font_size_scale`](Self::set_font_size_scale)
    /// after mount.
    pub fn font_size_scale(self, scale: f32) -> Self {
        {
            let mut st = self.state.borrow_mut();
            st.font_size_scale = scale.clamp(0.1, 10.0);
            st.needs_full_layout = true;
            st.content_dirty = true;
        }
        self
    }

    /// Replace the built-in right-click context menu with a
    /// user-provided factory. Same shape as the framework's
    /// [`teksilo_core::widget_builder::ContextMenuFactory`]: the
    /// closure receives the click position (widget-local) and a full
    /// [`EventContext`](teksilo_core::widget::EventContext), and returns
    /// `Some(menu_widget)` to mount or `None` to decline (falling
    /// through to the next ancestor with a factory).
    ///
    /// Taking this branch disables the default menu unconditionally.
    /// The framework's
    /// [`show_context_menu_for`](teksilo_core::widget_tree) handles
    /// the overlay lifecycle (open at pointer, dismiss on
    /// click-outside / Escape, focus-restore on dismiss), so the
    /// factory only needs to build the menu content.
    ///
    /// This is an **inherent method**: it shadows the blanket
    /// [`WidgetBuilder::context_menu`](teksilo_core::widget_builder::WidgetBuilder::context_menu)
    /// trait method so the user can chain it directly on the editor.
    /// Internally, the factory is installed on the editor's arena
    /// node via the same `HandlerSet::context_menu` plumbing.
    pub fn context_menu(
        mut self,
        factory: impl Fn(
            teksilo_canvas::Point,
            &mut teksilo_core::widget::EventContext,
        ) -> Option<Box<dyn teksilo_core::widget::Widget>>
        + 'static,
    ) -> Self {
        self.custom_context_menu = Some(Box::new(factory));
        self
    }

    /// Enable (default) or disable the widget's built-in right-click
    /// context menu (Cut / Copy / Paste / Paste Unformatted / Select
    /// All). When disabled, right-click bubbles past the widget
    /// unhandled and
    /// [`context_target_at`](Self::context_target_at) stays
    /// available for applications that render their own menu.
    ///
    /// Note: if a user factory is installed via
    /// [`context_menu`](Self::context_menu), that factory wins
    /// regardless of this flag — this setter only governs the
    /// *default* menu.
    pub fn default_context_menu(mut self, enabled: bool) -> Self {
        self.default_context_menu_enabled = enabled;
        self
    }

    /// Install a custom font registrar for the fallback private
    /// engine. Only has effect when the editor is built outside a
    /// windowed teksilo-app — once `build()` sees a `SharedTypesetter`
    /// in `app_state`, the private engine is replaced with one that
    /// shares the app's typesetter and this registrar is ignored.
    pub fn font_registrar(self, registrar: &dyn FontRegistrar) -> Self {
        {
            let mut st = self.state.borrow_mut();
            let mut engine = RichTextEngine::private_with_registrar(registrar);
            engine.set_wrap_mode(st.wrap_mode);
            engine.set_hyphenate_justified(true);
            st.engine = engine;
            st.needs_full_layout = true;
        }
        self
    }

    /// Install a callback fired once per batch of genuine **user content
    /// edits** (typing, paste, cut, delete) — and *not* on a programmatic
    /// `set_djot` / `set_markdown` / `set_html` load or a document reset, and
    /// *not* while an IME composition (CJK/Kana candidate preview, dead-key
    /// accent) is still in progress — only the settled result of a commit
    /// fires it. The callback runs on the UI thread during the editor's frame
    /// drain, so it may touch `Signal`s directly — e.g. flip a "dirty" flag or
    /// kick a debounced autosave. Replaces any prior change callback on this
    /// editor.
    ///
    /// For a reactive change *token* (which also bumps on loads/format-only
    /// changes, and on intermediate IME composition steps), observe
    /// [`document_version`](Self::document_version) instead.
    pub fn on_change(self, f: impl Fn() + 'static) -> Self {
        self.state.borrow_mut().on_change = Some(Rc::new(f));
        self
    }

    /// Install a callback fired **at each insertion**, with the
    /// [`EditSource`] the text came through and how many characters it was.
    ///
    /// Additive to [`on_change`](Self::on_change) rather than a replacement for
    /// it, because they answer different questions. `on_change` fires once per
    /// drain batch and says *that* the document changed — the right shape for a
    /// dirty flag and a debounced autosave, and the wrong one for counting: a
    /// batch can carry a typed run and a paste, and after the fact nothing can
    /// tell them apart.
    ///
    /// **Reported where the text is, not derived afterwards.** Every site below
    /// holds the literal `&str` about to be inserted, so the count is what was
    /// actually written rather than a position delta — which is a different
    /// number the moment an insertion replaces a selection.
    ///
    /// Fires for text arriving through:
    ///
    /// - the keyboard, once per batched run of typed characters;
    /// - an IME commit, once for the settled result and never for the
    ///   intermediate composition states;
    /// - a paste, of plain text or HTML;
    /// - an assistive technology, through AccessKit's `SetValue` and
    ///   `ReplaceSelectedText`.
    ///
    /// It does **not** fire for a programmatic `set_djot` / `set_markdown` /
    /// `set_html` load, for undo or redo, or for a format-only change: none of
    /// those is text arriving.
    ///
    /// Replaces any prior callback on this editor. Runs on the UI thread.
    pub fn on_text_inserted(self, f: impl Fn(EditSource, usize) + 'static) -> Self {
        self.state.borrow_mut().on_text_inserted = Some(Rc::new(f));
        self
    }

    // --- Observable signals ---------------------------------------------

    /// Reactive counter that bumps on every document change (content edits,
    /// format changes, load events). Starts at `0`. Use as a change token to
    /// invalidate external caches.
    pub fn document_version(&self) -> Signal<u64> {
        self.state.borrow().document_version.clone()
    }

    /// Current cursor position in the document, in character units.
    /// Exposed for tests and for applications that need to mirror the
    /// caret position externally (status bar, outline panel, etc.).
    pub fn cursor_position(&self) -> usize {
        self.state.borrow().cursor.position()
    }

    /// Current selection anchor (equal to `cursor_position` when there
    /// is no selection).
    pub fn cursor_anchor(&self) -> usize {
        self.state.borrow().cursor.anchor()
    }

    /// `true` while an IME composition (CJK/Kana candidate preview, dead-key
    /// accent) is actively in progress — i.e. [`on_change`](Self::on_change)
    /// is currently suppressed for this editor. Exposed so a caller doing its
    /// own while-typing scanning (e.g. an autocorrect feature) can gate its
    /// own trigger logic the same way, as defense-in-depth alongside
    /// `on_change`'s own gate.
    pub fn is_composing(&self) -> bool {
        self.state.borrow().ime_preedit.is_some()
    }

    /// Reactive cursor position signal. Observers fire whenever the
    /// cursor moves (arrow keys, click, Home/End, …). Useful for
    /// status bars and tests.
    pub fn cursor_position_signal(&self) -> Signal<usize> {
        self.state.borrow().cursor_position.clone()
    }

    /// Reactive selection anchor signal.
    pub fn cursor_anchor_signal(&self) -> Signal<usize> {
        self.state.borrow().cursor_anchor.clone()
    }

    /// Reactive signal — `true` whenever the editor has a non-empty
    /// selection. Updates synchronously after every cursor mutation.
    pub fn has_selection(&self) -> Signal<bool> {
        self.state.borrow().has_selection.clone()
    }

    /// Reactive undo-availability signal, suitable for toolbar button
    /// enable-state. Updated through the frame loop's debounce drain
    /// so toolbars don't flicker during rapid editing.
    pub fn can_undo(&self) -> Signal<bool> {
        self.state.borrow().can_undo.clone()
    }

    /// Reactive redo-availability signal.
    pub fn can_redo(&self) -> Signal<bool> {
        self.state.borrow().can_redo.clone()
    }

    /// Read the current character format at the widget's caret —
    /// the right source for toolbars that mirror bold/italic/underline
    /// state.
    ///
    /// When a selection is active, the format is read from
    /// [`selection_start()`](teksilo_text::text_document::TextCursor::selection_start)
    /// rather than [`position()`](teksilo_text::text_document::TextCursor::position).
    /// Rationale (matches godot-rich-text's `query_char_format`):
    /// `position()` lands at the **end** of the selection and may fall
    /// on a run with different formatting (or past the last character,
    /// on an empty virtual element) — a toolbar observing that value
    /// would flicker or lie. `selection_start()` always points at the
    /// first character of the selected range, so the reading is
    /// stable and matches what a user would expect from "tell me the
    /// format of what I have selected."
    pub fn caret_char_format(&self) -> TextFormat {
        let st = self.state.borrow();
        let probe_pos = if st.cursor.has_selection() {
            st.cursor.selection_start()
        } else {
            st.cursor.position()
        };
        // Read through a fresh cursor so we don't disturb the widget's
        // own cursor (the widget's own cursor has its own position /
        // anchor state that we must not move).
        let probe = st.document.cursor();
        probe.set_position(probe_pos, teksilo_text::text_document::MoveMode::MoveAnchor);
        probe.char_format().unwrap_or_default()
    }

    /// Clone the internal shared state handle for test observation.
    /// Tests take this before `tree.add(editor)` moves the widget
    /// into the arena, so they can read the widget's live cursor,
    /// signal state, and debounce fields through the very same
    /// `Rc<RefCell<EditorState>>` that the arena-stored editor is
    /// mutating.
    #[cfg(test)]
    pub(crate) fn state_handle(&self) -> SharedState {
        self.state.clone()
    }

    /// Reactive vertical scroll offset in logical pixels. Bind to a
    /// scroll bar or observe for scroll-position persistence.
    pub fn scroll_y(&self) -> Signal<f32> {
        self.state.borrow().scroll_y.clone()
    }

    /// Reactive horizontal scroll offset in logical pixels. Non-zero
    /// only when [`wrap_mode`](Self::wrap_mode) is `WrapMode::None`.
    pub fn scroll_x(&self) -> Signal<f32> {
        self.state.borrow().scroll_x.clone()
    }

    // --- Context-menu support (external menus) --------------------------

    /// Classify what is under `point` in the widget's local coordinates
    /// (origin at the widget's top-left, scroll offset handled
    /// internally by the typesetter), for applications building an
    /// external context menu. Returns `None` if the point does not
    /// land on any hit region.
    pub fn context_target_at(&self, point: Point) -> Option<hit_test::ContextTarget> {
        let st = self.state.borrow();
        let hit = hit_test::hit_test_at(&st.engine, point, 0.0, 0.0)?;
        let selection = Some((st.cursor.anchor(), st.cursor.position()));
        Some(hit_test::classify(&hit, selection, &st.document))
    }

    // --- Selection helpers (allowed under both presets) -----------------

    /// Currently selected text, or an empty string if nothing is selected.
    pub fn selected_text(&self) -> String {
        self.state
            .borrow()
            .cursor
            .selected_text()
            .unwrap_or_default()
    }

    /// Select the entire document programmatically. Equivalent to
    /// the final step of the Ctrl+A ladder; resets the ladder state
    /// so a subsequent Ctrl+A starts fresh at level 1.
    pub fn select_all(&self) {
        {
            let mut st = self.state.borrow_mut();
            st.cursor.select(SelectionType::Document);
            st.select_all_level = 0;
            st.select_all_anchor_cell = None;
        }
        sync_cursor_signals(&self.state);
    }

    /// Clear any current selection.
    pub fn deselect(&self) {
        {
            let mut st = self.state.borrow_mut();
            st.cursor.clear_selection();
            st.select_all_level = 0;
            st.select_all_anchor_cell = None;
        }
        sync_cursor_signals(&self.state);
    }

    // --- Cursor mirror API -------------------------------------------------
    //
    // These mirror the corresponding `TextCursor` methods but act on the
    // widget's **internal** cursor (the one tied to caret rendering /
    // blink / focus) rather than a fresh `doc.cursor()`. An application
    // that reaches through `TextDocument::cursor()` gets an independent
    // cursor whose position is decoupled from the widget's caret — any
    // mutation would be invisible to the paint pass. Use these methods
    // when you want programmatic effects to feel like user-typed edits.

    /// Insert plain text at the widget's caret. Replaces any selection.
    pub fn insert_text(&self, text: &str) {
        let st = self.state.borrow();
        let _ = st.cursor.insert_text(text);
        drop(st);
        sync_cursor_signals(&self.state);
    }

    /// Insert a fragment parsed from HTML at the widget's caret.
    /// Replaces any selection. Uses text-document's
    /// [`TextCursor::insert_html`](teksilo_text::text_document::TextCursor::insert_html),
    /// which parses the HTML into a `DocumentFragment` and inserts it.
    pub fn insert_html(&self, html: &str) {
        let st = self.state.borrow();
        let _ = st.cursor.insert_html(html);
        drop(st);
        sync_cursor_signals(&self.state);
    }

    /// Insert a fragment parsed from djot at the widget's caret.
    /// Replaces any selection. Uses text-document's
    /// [`TextCursor::insert_djot`](teksilo_text::text_document::TextCursor::insert_djot),
    /// which parses the djot into a `DocumentFragment` and inserts it — so
    /// unlike [`insert_text`](Self::insert_text), block-level source really
    /// does produce new blocks rather than literal newlines in one paragraph.
    pub fn insert_djot(&self, djot: &str) {
        let st = self.state.borrow();
        let _ = st.cursor.insert_djot(djot);
        drop(st);
        sync_cursor_signals(&self.state);
    }

    /// Split the current block at the widget's caret, as pressing Enter does.
    pub fn insert_block(&self) {
        let st = self.state.borrow();
        let _ = st.cursor.insert_block();
        drop(st);
        sync_cursor_signals(&self.state);
    }

    /// Insert an inline image by logical resource name. `width` and
    /// `height` are in logical pixels.
    ///
    /// `alt` is the image's accessible description and its export representation. It is
    /// passed straight through rather than defaulted here: the caller is the only layer
    /// that knows what the picture shows, and an empty string chosen on its behalf would
    /// be an accessibility decision made silently by a widget wrapper.
    pub fn insert_image(&self, name: &str, alt: &str, width: u32, height: u32) {
        let st = self.state.borrow();
        let _ = st.cursor.insert_image(name, alt, width, height);
        drop(st);
        sync_cursor_signals(&self.state);
    }

    /// Delete the current selection. No-op when nothing is selected.
    pub fn delete_selection(&self) {
        let st = self.state.borrow();
        if st.cursor.has_selection() {
            let _ = st.cursor.remove_selected_text();
        }
        drop(st);
        sync_cursor_signals(&self.state);
    }

    /// Select the word under the widget's caret.
    pub fn select_word(&self) {
        {
            let st = self.state.borrow();
            st.cursor.select(SelectionType::WordUnderCursor);
        }
        sync_cursor_signals(&self.state);
    }

    /// Select the paragraph / block under the widget's caret.
    pub fn select_line(&self) {
        {
            let st = self.state.borrow();
            st.cursor.select(SelectionType::LineUnderCursor);
        }
        sync_cursor_signals(&self.state);
    }

    /// Move the caret to an absolute character position. Collapses any
    /// existing selection (passes [`MoveMode::MoveAnchor`]). Resets
    /// `CursorAffinity` to `Downstream` — programmatic placement
    /// can't know whether the caller wanted the upstream side of a
    /// wrap boundary, so we default to the same placement that
    /// existed before affinity was introduced.
    pub fn set_caret_position(&self, position: usize) {
        {
            let mut st = self.state.borrow_mut();
            st.cursor.set_position(position, MoveMode::MoveAnchor);
            st.cursor_affinity = teksilo_text::CursorAffinity::Downstream;
        }
        sync_cursor_signals(&self.state);
    }

    // --- Search / find-banner support (B3) --------------------------------

    /// Reactive signal — `true` while **this** editor holds keyboard focus.
    ///
    /// A per-editor find banner (Ctrl+F) targets whichever editor is focused, and the split
    /// view has two of them; `focused_side` only names the Primary/Secondary *pane*, not which
    /// editor. This is the per-editor answer, mirroring [`has_selection`](Self::has_selection).
    pub fn focused_signal(&self) -> Signal<bool> {
        self.state.borrow().focus_signal.clone()
    }

    /// Select the character range `[start, end)`, **without** collapsing — unlike
    /// [`set_caret_position`](Self::set_caret_position), which always moves both ends together.
    ///
    /// The anchor lands at `start` and the caret (focus) at `end`, so the standard selection
    /// highlight marks the range and a subsequent replace acts on it. Used to select a search
    /// match. (The non-collapsing two-call shape is the same one the AccessKit
    /// `SetTextSelection` handler uses.)
    pub fn select_range(&self, start: usize, end: usize) {
        {
            let mut st = self.state.borrow_mut();
            st.cursor.set_position(start, MoveMode::MoveAnchor);
            st.cursor.set_position(end, MoveMode::KeepAnchor);
            // The caret sits at `end`; downstream affinity matches placement at a range end.
            st.cursor_affinity = teksilo_text::CursorAffinity::Downstream;
        }
        sync_cursor_signals(&self.state);
    }

    /// Scroll the character range `[start, end)` into view within the enclosing scroll area.
    ///
    /// Reveals an **arbitrary** offset range — the current search match — rather than the live
    /// caret the follow-into-view path tracks, and works whether or not the editor is focused.
    ///
    /// **Returns whether it could.** `false` means this editor has no layout to locate the
    /// range in — never laid out, or parked dormant in a tab that is not on screen — and
    /// nothing was requested. A caller holding several editors over one document (two split
    /// panes; a stream row and that row's own tab) must try the next rather than take the
    /// first as the answer: revealing through a dormant one silently does nothing, which
    /// reads as "the viewport does not follow".
    ///
    /// Under [`typewriter`](Self::typewriter) scrolling the range is *pinned* to
    /// the anchor rather than merely revealed, so a search walks matches to the
    /// same height the caret writes at instead of leaving them wherever they
    /// happened to fall. Because a search jump is a deliberate, screen-sized
    /// move, it glides.
    pub fn reveal_range(
        &self,
        ctx: &mut teksilo_core::widget::EventContext,
        start: usize,
        end: usize,
    ) -> bool {
        reveal_range_impl(&self.state, ctx, start, end)
    }

    // --- Character-format commands ----------------------------------------
    //
    // Each setter writes to `TextCursor::merge_char_format`, which
    // applies to the current selection — a collapsed caret formats
    // nothing, since the document model has no typing/pending format. Toggle
    // variants (`toggle_bold`, `toggle_italic`, `toggle_underline`,
    // `toggle_strikethrough`) read the current state via
    // [`caret_char_format`](Self::caret_char_format) first and flip,
    // which matches the Ctrl+B / Ctrl+I / Ctrl+U keyboard shortcuts.

    fn apply_char_format(&self, fmt: TextFormat) {
        let st = self.state.borrow();
        let _ = st.cursor.merge_char_format(&fmt);
        // `pending_format_changed` gets set by `drain_events` when the
        // document emits its `FormatChanged` event in response to the
        // cursor mutation, so no manual bookkeeping is needed here.
    }

    /// Apply **bold** to the current selection. A no-op when nothing is
    /// selected — the document model has no typing format. Pairs with
    /// [`is_bold`](Self::is_bold) and [`toggle_bold`](Self::toggle_bold).
    pub fn set_bold(&self, enabled: bool) {
        self.apply_char_format(TextFormat {
            font_bold: Some(enabled),
            ..Default::default()
        });
    }

    /// Apply *italic* to the current selection.
    pub fn set_italic(&self, enabled: bool) {
        self.apply_char_format(TextFormat {
            font_italic: Some(enabled),
            ..Default::default()
        });
    }

    /// Apply underline to the current selection.
    pub fn set_underline(&self, enabled: bool) {
        self.apply_char_format(TextFormat {
            font_underline: Some(enabled),
            ..Default::default()
        });
    }

    /// Apply strikethrough to the current selection.
    pub fn set_strikethrough(&self, enabled: bool) {
        self.apply_char_format(TextFormat {
            font_strikeout: Some(enabled),
            ..Default::default()
        });
    }

    /// Set the font size (in points) for the current selection.
    pub fn set_font_size(&self, size: u32) {
        self.apply_char_format(TextFormat {
            font_point_size: Some(size),
            ..Default::default()
        });
    }

    /// Set the font family for the current selection. `family` must be
    /// a name resolvable by the shared typesetter's font registrar.
    pub fn set_font_family(&self, family: impl Into<String>) {
        self.apply_char_format(TextFormat {
            font_family: Some(family.into()),
            ..Default::default()
        });
    }

    /// Toggle bold on the current selection, reading the current state
    /// via [`caret_char_format`](Self::caret_char_format). Matches the
    /// Ctrl+B keyboard shortcut's behaviour.
    pub fn toggle_bold(&self) {
        let current = self.caret_char_format().font_bold.unwrap_or(false);
        self.set_bold(!current);
    }

    /// Toggle italic; see [`toggle_bold`](Self::toggle_bold).
    pub fn toggle_italic(&self) {
        let current = self.caret_char_format().font_italic.unwrap_or(false);
        self.set_italic(!current);
    }

    /// Toggle underline; see [`toggle_bold`](Self::toggle_bold).
    pub fn toggle_underline(&self) {
        let current = self.caret_char_format().font_underline.unwrap_or(false);
        self.set_underline(!current);
    }

    /// Toggle strikethrough; see [`toggle_bold`](Self::toggle_bold).
    pub fn toggle_strikethrough(&self) {
        let current = self.caret_char_format().font_strikeout.unwrap_or(false);
        self.set_strikethrough(!current);
    }

    // --- Vertical alignment (super / subscript) ---------------------------
    //
    // One property with three meaningful states, surfaced as two independent
    // toggles because that is how a toolbar presents it. Setting one clears
    // the other, since a run cannot be both.

    /// Raise the selection to superscript, or drop it back to the baseline.
    pub fn set_superscript(&self, enabled: bool) {
        self.set_vertical_alignment(if enabled {
            CharVerticalAlignment::SuperScript
        } else {
            CharVerticalAlignment::Normal
        });
    }

    /// Lower the selection to subscript, or drop it back to the baseline.
    pub fn set_subscript(&self, enabled: bool) {
        self.set_vertical_alignment(if enabled {
            CharVerticalAlignment::SubScript
        } else {
            CharVerticalAlignment::Normal
        });
    }

    /// Set the selection's vertical alignment directly. `Normal` is the
    /// baseline; `Middle` exists in the model but has no toolbar affordance.
    pub fn set_vertical_alignment(&self, alignment: CharVerticalAlignment) {
        self.apply_char_format(TextFormat {
            vertical_alignment: Some(alignment),
            ..Default::default()
        });
    }

    /// The caret's vertical alignment, `Normal` when unset.
    pub fn get_vertical_alignment(&self) -> CharVerticalAlignment {
        self.caret_char_format()
            .vertical_alignment
            .unwrap_or(CharVerticalAlignment::Normal)
    }

    /// True while the caret sits in superscript text.
    pub fn is_superscript(&self) -> bool {
        self.get_vertical_alignment() == CharVerticalAlignment::SuperScript
    }

    /// True while the caret sits in subscript text.
    pub fn is_subscript(&self) -> bool {
        self.get_vertical_alignment() == CharVerticalAlignment::SubScript
    }

    /// Flip superscript on the selection. Turning it on replaces subscript.
    pub fn toggle_superscript(&self) {
        self.set_superscript(!self.is_superscript());
    }

    /// Flip subscript on the selection. Turning it on replaces superscript.
    pub fn toggle_subscript(&self) {
        self.set_subscript(!self.is_subscript());
    }

    // --- Block-format commands --------------------------------------------

    /// Set an arbitrary [`BlockFormat`] on the caret's current block.
    /// The higher-level helpers [`set_alignment`](Self::set_alignment)
    /// and [`set_heading_level`](Self::set_heading_level) go through
    /// this method. Exposed so apps that need less common fields
    /// (`indent`, `left_margin`, `line_height`, …) don't have to
    /// reach through `TextDocument::cursor()` and lose the widget's
    /// caret continuity.
    pub fn apply_block_format(&self, fmt: BlockFormat) {
        let st = self.state.borrow();
        let _ = st.cursor.set_block_format(&fmt);
        // See `apply_char_format` — `FormatChanged` propagates
        // through `drain_events` and updates `pending_format_changed`
        // + `format_version` there.
    }

    /// Set an arbitrary [`TextFormat`] on the current selection.
    /// Public counterpart of the private `apply_char_format` helper,
    /// for apps that need fields beyond the dedicated
    /// `set_bold` / `set_italic` / … setters (e.g. `letter_spacing`,
    /// `foreground_color`).
    pub fn apply_text_format(&self, fmt: TextFormat) {
        self.apply_char_format(fmt);
    }

    /// Set the paragraph alignment for the current block (or the block
    /// containing the selection anchor).
    pub fn set_alignment(&self, alignment: Alignment) {
        self.apply_block_format(BlockFormat {
            alignment: Some(alignment),
            ..Default::default()
        });
    }

    /// Unset the block's direction, handing the paragraph back to
    /// automatic detection.
    ///
    /// Not the same as setting left-to-right. An explicit direction
    /// *pins* the paragraph and overrides the bidi algorithm, so
    /// "clearing" a direction by writing `LeftToRight` would force
    /// Arabic and Hebrew prose to lay out backwards. Only an unset
    /// direction lets the text speak for itself.
    pub fn clear_direction(&self) {
        self.apply_block_format(BlockFormat {
            clear_direction: true,
            ..Default::default()
        });
    }

    /// Set the base reading direction of the current block.
    ///
    /// This is the *paragraph* direction, not a character property: it
    /// decides which edge unaligned text sits against and, more
    /// importantly, overrides the bidi algorithm's first-strong-character
    /// guess — which misreads an Arabic paragraph opening with a Latin
    /// acronym as left-to-right.
    pub fn set_direction(&self, direction: TextDirection) {
        self.apply_block_format(BlockFormat {
            direction: Some(direction),
            ..Default::default()
        });
    }

    /// Set the heading level of the current block. `0` = plain
    /// paragraph; `1..=6` follow the HTML `<h1>..<h6>` convention.
    pub fn set_heading_level(&self, level: u8) {
        self.apply_block_format(BlockFormat {
            heading_level: Some(level),
            ..Default::default()
        });
    }

    // --- List commands ----------------------------------------------------

    /// Create a list at the current selection. `ordered = true` uses
    /// decimal numbering; `ordered = false` uses a bullet disc.
    /// Choose a specific style with [`create_list`](Self::create_list).
    pub fn insert_list(&self, ordered: bool) {
        let style = if ordered {
            ListStyle::Decimal
        } else {
            ListStyle::Disc
        };
        self.create_list(style);
    }

    /// Create a list with an explicit [`ListStyle`]. Exposed for
    /// applications that want e.g. lowercase Roman numerals or circle
    /// bullets.
    pub fn create_list(&self, style: ListStyle) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.create_list(style);
        }
        sync_cursor_signals(&self.state);
    }

    /// Increase the nesting depth of the caret's current list item by
    /// one. No-op when the caret is not inside a list. Equivalent to
    /// pressing Tab while the caret is on a list item — same behaviour,
    /// same `nest_current_list_item` codepath, exposed for toolbar
    /// buttons that do not want to synthesise key events.
    ///
    /// Also a no-op at the editor's list ceiling (level 16, a top-level item
    /// being level 1). A list item in a blockquote or a table cell moves as
    /// one in the main text does; in a table cell, where Tab moves to the next
    /// cell, this is the way to nest an item.
    pub fn indent(&self) {
        keyboard::indent_current_block(&mut self.state.borrow_mut());
        sync_cursor_signals(&self.state);
    }

    /// Decrease the nesting depth of the caret's current list item by
    /// one. No-op at depth 0 (use `Backspace` at block-start to exit
    /// the list entirely). Toolbar counterpart of Shift+Tab.
    pub fn outdent(&self) {
        keyboard::dedent_current_block(&mut self.state.borrow_mut());
        sync_cursor_signals(&self.state);
    }

    /// Take the caret's block out of its list entirely, leaving a plain
    /// paragraph. No-op when the caret is not inside a list.
    ///
    /// [`outdent`](Self::outdent) deliberately stops at depth 0 — Shift+Tab
    /// should not silently destroy the list — so a toolbar that offers
    /// "remove list formatting" needs this instead. Backspace at block-start
    /// reaches the same codepath from the keyboard.
    pub fn remove_from_list(&self) {
        let _ = self.state.borrow().cursor.remove_current_block_from_list();
        sync_cursor_signals(&self.state);
    }

    /// The style of the list the caret's paragraph belongs to, or `None`
    /// outside a list. What a toolbar reads to show its "Bullets" or
    /// "Numbering" button pressed; [`list_style_is_ordered`] says which.
    pub fn current_list_style(&self) -> Option<ListStyle> {
        lists::current_list_style(&self.state.borrow())
    }

    /// Give the caret's whole list `style`, keeping its depth: every item of
    /// it, not only the caret's. No-op outside a list.
    pub fn set_list_style(&self, style: ListStyle) {
        lists::set_list_style(&self.state.borrow(), style);
        sync_cursor_signals(&self.state);
    }

    /// The press of a word processor's "Bullets" (`ordered == false`) or
    /// "Numbering" (`ordered == true`) button, as one undo step:
    ///
    /// * in a list of that kind, the caret's paragraph (or every selected
    ///   one) leaves the list;
    /// * in a list of the other kind, the caret's whole list changes kind
    ///   (with a selection, the selected paragraphs become one new list);
    /// * outside a list, the paragraphs become one, as
    ///   [`insert_list`](Self::insert_list) does.
    ///
    /// "Kind" is [`list_style_is_ordered`]: a circle-bullet list is a bullet
    /// list, and a roman-numbered one a numbered list.
    pub fn toggle_list(&self, ordered: bool) {
        lists::toggle_list(&self.state.borrow(), ordered);
        sync_cursor_signals(&self.state);
    }

    // --- Blockquote commands ----------------------------------------------

    /// True iff the caret currently sits inside a blockquote frame at
    /// any nesting depth. Used by the toolbar to drive the toggle
    /// button's pressed state and the context menu's label.
    pub fn is_in_blockquote(&self) -> bool {
        let st = self.state.borrow();
        st.cursor.is_in_blockquote()
    }

    /// True iff the current selection spans more than one frame. The
    /// "Toggle blockquote" affordance is disabled in this case because
    /// wrapping a cross-frame range has no well-defined semantics
    /// (different blocks already belong to different containers).
    pub fn selection_spans_multiple_frames(&self) -> bool {
        let st = self.state.borrow();
        st.cursor.selection_spans_multiple_frames()
    }

    /// Wrap the current block (or selection) in a blockquote, or
    /// unwrap the innermost enclosing blockquote if already inside one.
    /// No-op (returns silently) when the selection spans multiple
    /// frames.
    ///
    /// The wrap is also a no-op where it would take a block past the
    /// editor's quote ceiling (64 levels), including a quote the selection
    /// holds: the wrap takes the whole selection one level deeper. The
    /// unwrap is never limited.
    pub fn toggle_blockquote(&self) {
        nesting::toggle_blockquote(&self.state.borrow());
        sync_cursor_signals(&self.state);
    }

    /// Equivalent to pressing Tab inside a blockquote — wraps the
    /// current block in a deeper nested quote. No-op when the caret is
    /// not in a quote, and where the wrap would take a block past the
    /// editor's quote ceiling (64 levels).
    pub fn increase_blockquote_depth(&self) {
        nesting::increase_blockquote_depth(&self.state.borrow());
        sync_cursor_signals(&self.state);
    }

    /// Take the caret's block out of one blockquote nesting level. At depth 1
    /// this unwraps the block to a plain paragraph. No-op when the caret is
    /// not in a quote.
    ///
    /// Shift+Tab in a quote does the same outside a list or a table. On a list
    /// item it is a list outdent instead (see [`outdent`](Self::outdent)): it
    /// moves the item one list level up and leaves the quote around it alone.
    /// This command takes a list item out of one quote level and keeps its
    /// list level.
    pub fn decrease_blockquote_depth(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.decrease_blockquote_depth();
        }
        sync_cursor_signals(&self.state);
    }

    // --- Table commands ---------------------------------------------------
    //
    // Each table command drops through `sync_cursor_signals` because
    // the underlying `cursor.*` calls move the caret (insert_table
    // lands past the new table; row/column ops may shift the caret's
    // logical position). Callers observing `cursor_position_signal`
    // see the post-operation position without waiting for the next
    // frame tick.

    /// Insert a fresh `rows × columns` table at the caret. Any
    /// existing selection is replaced.
    pub fn insert_table(&self, rows: usize, columns: usize) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_table(rows, columns);
        }
        sync_cursor_signals(&self.state);
    }

    /// Remove the table containing the caret (if any). No-op when the
    /// caret is not inside a table.
    pub fn remove_current_table(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.remove_current_table();
        }
        sync_cursor_signals(&self.state);
    }

    /// Insert a row above the caret's current table row. No-op when
    /// outside a table.
    pub fn insert_row_above(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_row_above();
        }
        sync_cursor_signals(&self.state);
    }

    /// Insert a row below the caret's current table row.
    pub fn insert_row_below(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_row_below();
        }
        sync_cursor_signals(&self.state);
    }

    /// Insert a column before the caret's current table column.
    pub fn insert_column_before(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_column_before();
        }
        sync_cursor_signals(&self.state);
    }

    /// Insert a column after the caret's current table column.
    pub fn insert_column_after(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_column_after();
        }
        sync_cursor_signals(&self.state);
    }

    /// Remove the caret's current table row.
    pub fn remove_current_row(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.remove_current_row();
        }
        sync_cursor_signals(&self.state);
    }

    /// Remove the caret's current table column.
    pub fn remove_current_column(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.remove_current_column();
        }
        sync_cursor_signals(&self.state);
    }

    /// Whether the caret is currently inside a table cell.
    pub fn is_in_table(&self) -> bool {
        self.state.borrow().cursor.current_table().is_some()
    }

    // --- Format query methods (toolbar state) -----------------------------
    //
    // Every query goes through [`caret_char_format`](Self::caret_char_format)
    // which honours the selection-start rule — toolbar buttons reflect
    // "the format of what's selected," not "the format after the
    // selection ends."

    /// Whether the current selection / typing position is bold.
    pub fn is_bold(&self) -> bool {
        self.caret_char_format().font_bold.unwrap_or(false)
    }

    /// Whether italic.
    pub fn is_italic(&self) -> bool {
        self.caret_char_format().font_italic.unwrap_or(false)
    }

    // ── Hyperlinks ───────────────────────────────────────────────
    //
    // A link is a character format, not an object: applying one merges a
    // destination onto a range, so any bold or italic already there survives
    // and no markup has to be escaped. What it does not get for free is
    // removal — every field of a merge means "leave this alone" when unset —
    // hence `clear_link` rather than "set the destination to nothing".

    /// Point the selection at `href`.
    ///
    /// Merges, so formatting already on the range is kept. A collapsed
    /// selection formats nothing (as everywhere else), so a caller linking
    /// existing text should select it first — see
    /// [`link_at_caret`](Self::link_at_caret) for the range of a link already
    /// there.
    pub fn set_link(&self, href: &str) {
        self.apply_char_format(TextFormat {
            anchor_href: Some(href.to_string()),
            ..Default::default()
        });
    }

    /// Take the link off the selection, leaving its text.
    pub fn clear_link(&self) {
        self.apply_char_format(TextFormat {
            clear_link: true,
            ..Default::default()
        });
    }

    /// The link the caret is in, and how far it reaches.
    ///
    /// Coalesced across the runs an inner mark splits a link into, so the
    /// range covers the whole link rather than the piece under the caret.
    /// `None` when the caret is not on a link.
    pub fn link_at_caret(&self) -> Option<LinkExtent> {
        self.state.borrow().cursor.link_at_caret()
    }

    /// Whether the caret / selection sits on a link.
    pub fn is_link(&self) -> bool {
        self.caret_char_format().is_anchor.unwrap_or(false)
    }

    /// Whether underline.
    pub fn is_underline(&self) -> bool {
        self.caret_char_format().font_underline.unwrap_or(false)
    }

    /// Whether strikethrough.
    pub fn is_strikethrough(&self) -> bool {
        self.caret_char_format().font_strikeout.unwrap_or(false)
    }

    /// Current heading level (0 = plain paragraph). Reads the caret's
    /// current block format.
    pub fn get_heading_level(&self) -> u8 {
        self.state
            .borrow()
            .cursor
            .block_format()
            .ok()
            .and_then(|f| f.heading_level)
            .unwrap_or(0)
    }

    /// Current block alignment.
    pub fn get_alignment(&self) -> Alignment {
        self.state
            .borrow()
            .cursor
            .block_format()
            .ok()
            .and_then(|f| f.alignment)
            .unwrap_or(Alignment::Left)
    }

    /// The block's explicitly-set reading direction, if it has one.
    /// `None` means the bidi algorithm decides from the text.
    pub fn get_direction(&self) -> Option<TextDirection> {
        self.state
            .borrow()
            .cursor
            .block_format()
            .ok()
            .and_then(|f| f.direction)
    }

    // --- History ---------------------------------------------------------
    //
    // Programmatic Undo / Redo. Failures (e.g. empty undo stack) are
    // silently discarded — toolbars gate the buttons on
    // [`can_undo`](Self::can_undo) / [`can_redo`](Self::can_redo)
    // signals so the error path is unreachable in normal use, and the
    // keyboard handlers at `keyboard.rs:512-523` use the same
    // `let _ =` discipline.

    /// Undo the most recent edit. Mirrors Ctrl+Z. No-op when the undo
    /// stack is empty.
    pub fn undo(&self) {
        let _ = self.state.borrow().document.undo();
        sync_cursor_signals(&self.state);
    }

    /// Close the current undo entry, so the next edit starts a new one.
    ///
    /// Typing coalesces into word-sized undo steps by looking only at the shape
    /// of two edits — adjacent, moments apart. It cannot see that the user did
    /// something else in between, somewhere else in the application, that they
    /// would remember as a dividing line. A host that knows one was crossed says
    /// so here, and the burst before it stops merging with the burst after.
    pub fn break_undo_merge(&self) {
        self.state.borrow().document.break_undo_merge();
    }

    /// Redo the most recently undone edit. Mirrors Ctrl+Y /
    /// Ctrl+Shift+Z. No-op when the redo stack is empty.
    pub fn redo(&self) {
        let _ = self.state.borrow().document.redo();
        sync_cursor_signals(&self.state);
    }

    // --- Edit blocks (composite undo) ------------------------------------
    //
    // Every command on this type is its own transaction, so a caller that
    // composes several of them into one user-visible action — "clear
    // formatting" turning off four marks and flattening a heading — leaves
    // the user pressing Ctrl+Z once per property. Wrapping the sequence in
    // an edit block makes it one entry.
    //
    // The editor already groups this way internally for IME composition
    // (`keyboard.rs`) and for list nesting; these expose the same primitive
    // to external toolbars. Composites nest, so it is safe to wrap calls
    // that open one of their own.

    /// Begin grouping subsequent edits into a single undo entry.
    ///
    /// Must be paired with [`end_edit_block`](Self::end_edit_block). Prefer
    /// [`edit_block`](Self::edit_block), which pairs them for you.
    pub fn begin_edit_block(&self) {
        self.state.borrow().cursor.begin_edit_block();
    }

    /// Close the group opened by [`begin_edit_block`](Self::begin_edit_block).
    pub fn end_edit_block(&self) {
        self.state.borrow().cursor.end_edit_block();
    }

    /// Run `edits` as one undo entry.
    ///
    /// The scoped form of [`begin_edit_block`](Self::begin_edit_block) — the
    /// block is closed even if `edits` returns early, which hand-pairing gets
    /// wrong eventually.
    pub fn edit_block<R>(&self, edits: impl FnOnce() -> R) -> R {
        self.begin_edit_block();
        let result = edits();
        self.end_edit_block();
        result
    }

    /// Set the document-wide default language (ISO 639-1 code, e.g. "en",
    /// "fr", "de"). Blocks that don't set their own language inherit it
    /// for hyphenation. Forces a full re-layout so the change takes effect
    /// on the next frame. No-op-safe if the document rejects the update.
    pub fn set_default_language(&self, language: &str) {
        let _ = self.state.borrow().document.set_default_language(language);
        self.state.borrow_mut().needs_full_layout = true;
    }

    /// The document-wide default language (ISO 639-1 code). Defaults to
    /// `"en"` when never set.
    pub fn default_language(&self) -> String {
        self.state.borrow().document.default_language()
    }

    // --- External handle -------------------------------------------------

    /// Cheap clone-able handle for external toolbars / palettes — see
    /// [`EditorHandle`]. The handle shares the editor's internal
    /// state (same `Rc<RefCell<…>>`), so mutations through the handle
    /// are immediately observable through the editor's reactive
    /// signals (and vice versa).
    ///
    /// Use this when the caller needs to invoke editor commands from
    /// `on_activate_fn` / `ctx.effect` closures that outlive the
    /// borrow of `&editor`: `RichTextEditor` itself is move-only
    /// (the optional context-menu factory holds a `Box<dyn Fn>`,
    /// which prevents `Clone`).
    pub fn handle(&self) -> EditorHandle {
        EditorHandle {
            state: self.state.clone(),
        }
    }

    // --- Clipboard (programmatic) -----------------------------------------
    //
    // Direct programmatic counterparts of Ctrl+C / Ctrl+X / Ctrl+V /
    // Ctrl+Shift+V. The `ctx` argument is the active
    // [`EventContext`](teksilo_core::widget::EventContext) — the clipboard
    // lookup flows through `ctx.app_state::<ClipboardHandle>()` which
    // only has a value during event dispatch. Callers outside that
    // scope (e.g. ambient "restore from file" flows) should operate on
    // the `TextDocument` and the app-level clipboard directly.

    /// Copy the current selection to the system clipboard (plain +
    /// HTML payloads). No-op when there is no selection.
    ///
    /// All clipboard methods take `&EventContext` because they only
    /// need read access — the clipboard handle is looked up via
    /// `ctx.app_state::<ClipboardHandle>()`. A call site that holds
    /// `&mut EventContext` can pass `&ctx` directly; Rust reborrows
    /// automatically.
    pub fn copy(&self, ctx: &teksilo_core::widget::EventContext) {
        let mut st = self.state.borrow_mut();
        clipboard::copy(&mut st, ctx);
    }

    /// Cut the current selection: copy first, then remove.
    pub fn cut(&self, ctx: &teksilo_core::widget::EventContext) {
        {
            let mut st = self.state.borrow_mut();
            clipboard::cut(&mut st, ctx);
        }
        sync_cursor_signals(&self.state);
    }

    /// Paste from the system clipboard. Prefers an in-process fragment
    /// over HTML over plain text — see
    /// `rich_text/clipboard.rs`.
    pub fn paste(&self, ctx: &teksilo_core::widget::EventContext) {
        {
            let mut st = self.state.borrow_mut();
            clipboard::paste(&mut st, ctx);
        }
        sync_cursor_signals(&self.state);
    }

    /// Paste plain text only, stripping any rich payload.
    pub fn paste_unformatted(&self, ctx: &teksilo_core::widget::EventContext) {
        {
            let mut st = self.state.borrow_mut();
            clipboard::paste_unformatted(&mut st, ctx);
        }
        sync_cursor_signals(&self.state);
    }

    /// Whether a paste would insert anything — `true` iff the system
    /// clipboard carries text **or** an HTML payload (the shapes
    /// [`paste`](Self::paste) can consume; an HTML-only clipboard pastes
    /// fine, so probing plain text alone would under-report).
    ///
    /// Clipboard contents are not reactively observable, so this is a
    /// **point-in-time query** rather than a `Signal`: pass the active
    /// [`EventContext`](teksilo_core::widget::EventContext). It probes
    /// the clipboard (an X11 HTML probe can round-trip to the selection
    /// owner), so a menu / toolbar builder should re-query when the menu
    /// opens, not per frame. Returns `false` when no clipboard backend
    /// is installed (headless or feature-off builds) — the same
    /// "silently no-op" degradation the paste path itself uses.
    pub fn can_paste(&self, ctx: &teksilo_core::widget::EventContext) -> bool {
        clipboard::can_paste(ctx)
    }

    /// Set the per-editor logical font-size multiplier (`1.0` = 100 %).
    /// Composed with accessibility text scale at paint; forces relayout.
    /// See [`font_size_scale`](Self::font_size_scale).
    pub fn set_font_size_scale(&self, scale: f32) {
        let mut st = self.state.borrow_mut();
        let scale = scale.clamp(0.1, 10.0);
        if (st.font_size_scale - scale).abs() <= f32::EPSILON {
            return;
        }
        st.font_size_scale = scale;
        // Force the paint pass to re-push engine font_scale (it compares
        // against `last_font_scale` only).
        st.last_font_scale = f32::NAN;
        st.needs_full_layout = true;
        st.content_dirty = true;
        if let Some(handle) = &st.frame_request {
            handle.set(true);
        }
    }

    /// Current per-editor font-size scale (`1.0` = 100 %).
    pub fn get_font_size_scale(&self) -> f32 {
        self.state.borrow().font_size_scale
    }

    /// Set the non-destructive default typography at runtime. Re-lays out and
    /// schedules a repaint. Never mutates the document.
    pub fn set_typography_defaults(&self, defaults: EditorTypographyDefaults) {
        let mut st = self.state.borrow_mut();
        st.engine.set_typography_defaults(defaults);
        st.needs_full_layout = true;
        st.content_dirty = true;
        if let Some(handle) = &st.frame_request {
            handle.set(true);
        }
    }

    /// Current default typography (see [`typography_defaults`](Self::typography_defaults)).
    pub fn get_typography_defaults(&self) -> EditorTypographyDefaults {
        self.state.borrow().engine.typography_defaults().clone()
    }

    /// Set the typewriter-scrolling anchor at runtime — see
    /// [`typewriter`](Self::typewriter). `None` turns pinning off.
    ///
    /// Takes effect on the next caret move rather than scrolling immediately: a
    /// pin is a follow rule, and re-anchoring the page the instant a setting
    /// changes would jump the view under a reader who is not even typing.
    pub fn set_typewriter(&self, anchor: Option<f32>) {
        let mut st = self.state.borrow_mut();
        st.typewriter = anchor.map(|f| f.clamp(0.0, 1.0));
        // Drop the pin's dedup memory: the *next* caret move must re-pin even if
        // it lands where the last chase already was.
        st.last_chase_y = None;
    }

    /// Current typewriter anchor (see [`typewriter`](Self::typewriter)).
    pub fn get_typewriter(&self) -> Option<f32> {
        self.state.borrow().typewriter
    }

    /// Narrow (or restore) what the keyboard may do on this mounted editor.
    ///
    /// The other three policy dimensions — caret, accessibility role, clipboard
    /// surface — describe what *kind* of surface this is and are fixed at
    /// construction; only the command filter is a mode the host can change
    /// while the writer is looking at it. Swapping in
    /// [`CommandFilter::ForwardOnly`] gives a forward-only drafting mode;
    /// [`CommandFilter::All`] restores ordinary editing.
    ///
    /// Every gate reads the filter live — the keyboard dispatch, the default
    /// context menu, and drag-and-drop — so this takes effect on the next
    /// event without rebuilding the widget.
    pub fn set_command_filter(&self, filter: policy::CommandFilter) {
        self.state.borrow_mut().policy.command_filter = filter;
    }

    /// The filter currently in force (see
    /// [`set_command_filter`](Self::set_command_filter)).
    pub fn command_filter(&self) -> policy::CommandFilter {
        self.state.borrow().policy.command_filter
    }

    /// Draw an ambient band behind the sentence — or paragraph — the caret is in.
    ///
    /// `None` (the default) draws nothing and registers no session on the document. The band
    /// shows only while **this** editor has focus, so two panes over one document never band
    /// twice, and it disappears when focus leaves the editor entirely.
    ///
    /// The band is registered below every other highlight layer, so a find match or a spell
    /// squiggle always paints over it. Give it a paint-only `format` — a background colour —
    /// or it will force a reshape on every caret move.
    pub fn set_caret_highlight(&self, highlight: Option<caret_highlight::CaretHighlight>) {
        set_caret_highlight(&self.state, highlight);
    }

    /// What this editor's caret band is currently configured to draw.
    pub fn get_caret_highlight(&self) -> Option<caret_highlight::CaretHighlight> {
        self.state
            .borrow()
            .caret_highlight
            .as_ref()
            .and_then(|s| s.config())
    }

    /// The caret's rectangle in **absolute window (tree) coordinates**, or
    /// `None` when the editor is unfocused or has not been laid out yet.
    ///
    /// The same rect the OS-IME reporting and the caret follow use, exposed for
    /// hosts that need to position something against the caret (and for tests
    /// that need to assert where a pin actually put it).
    pub fn caret_window_rect(&self) -> Option<teksilo_canvas::Rect> {
        self::keyboard::caret_window_rect(&self.state.borrow())
    }

    // --- Observability: reactive version counters -------------------------

    /// Signal that bumps on every format-only document event (bold /
    /// italic / heading / alignment / list style changes …).
    /// Distinct from [`document_version`](Self::document_version),
    /// which also bumps on content changes. Useful for toolbar
    /// observers that want to refresh button state on format changes
    /// without flickering during plain typing.
    pub fn format_version(&self) -> Signal<u64> {
        self.state.borrow().format_version.clone()
    }

    /// Signal that bumps once per document-loaded event (fires when
    /// an async `set_html` / `set_markdown` import completes). Starts
    /// at 0; observers see a new value each time a long import
    /// finishes.
    pub fn document_loaded_count(&self) -> Signal<u64> {
        self.state.borrow().document_loaded_count.clone()
    }

    // --- Link / image click callbacks -------------------------------------
    //
    // Installed via builder methods (below). The widget fires these
    // on a Primary PointerDown whose hit lands on a `HitRegion::Link`
    // or `HitRegion::Image`, before any caret placement.

    /// Install a callback fired when the user Primary-clicks a link
    /// (an element with an anchor `href`). The callback receives the
    /// href string and the active `EventContext`.
    ///
    /// The callback replaces any prior link-click callback on this
    /// builder chain. To stop observing, reconstruct the editor
    /// without the setter.
    pub fn on_link_activated(
        self,
        handler: impl Fn(&str, &mut teksilo_core::widget::EventContext) + 'static,
    ) -> Self {
        self.state.borrow_mut().on_link_activated = Some(std::rc::Rc::new(handler));
        self
    }

    /// Supply an image's bytes on demand, when the document has no resource
    /// under that name.
    ///
    /// An inline image references its pixels by name, and those pixels live on
    /// the *document*. So a name that arrives without them — which is exactly
    /// what pasting an image into a second editor is, since the interchange
    /// format carries the reference and not the bytes — lays out at its full
    /// size and paints nothing.
    ///
    /// Rather than make every host re-scan its document after every edit for
    /// names that have appeared, the editor asks for what it is missing, once,
    /// at the moment it needs it. The bytes are written onto the document, so
    /// the answer is permanent and every later reader (a save, an export, a
    /// second view of the same document) sees them too.
    ///
    /// One hook serves paste, drag-and-drop, and an undo that re-inserts a
    /// deleted image, without any of them knowing it exists.
    pub fn on_image_missing(
        self,
        resolve: impl Fn(&str) -> Option<(String, Vec<u8>)> + 'static,
    ) -> Self {
        self.state.borrow_mut().image_resolver = Some(std::rc::Rc::new(resolve));
        self
    }

    /// Install a callback fired when files are dropped on the editor.
    ///
    /// The editor places the caret at the drop point and then hands the paths
    /// over: what a dropped file *means* — a picture to embed, a link to write,
    /// a document to include — is the host's policy, and a text editor that
    /// guessed would be wrong for every host but one.
    ///
    /// Without this, file drops are declined, and the drag bubbles to whatever
    /// ancestor claims it.
    pub fn on_files_dropped(
        self,
        handler: impl Fn(&[std::path::PathBuf], &mut teksilo_core::widget::EventContext) + 'static,
    ) -> Self {
        self.state.borrow_mut().on_files_dropped = Some(std::rc::Rc::new(handler));
        self
    }

    /// Install a callback fired when the reader finishes dragging one of a
    /// selected image's corner grips.
    ///
    /// The widget does not resize the picture itself. It cannot: an image's
    /// display size lives in the host's own document format (an attribute, a
    /// style, a column of a table), and only the host knows how to write it
    /// there so it survives a save. So the drag reports a size and the host
    /// decides what that means — the same division of labour as
    /// [`on_image_activated`](Self::on_image_activated).
    ///
    /// Fired once, on release. During the drag the widget shows an outline at
    /// the proposed size, which costs no relayout and keeps one gesture to one
    /// entry on the host's undo stack.
    pub fn on_image_resized(
        self,
        handler: impl Fn(&ImageResize, &mut teksilo_core::widget::EventContext) + 'static,
    ) -> Self {
        self.state.borrow_mut().on_image_resized = Some(std::rc::Rc::new(handler));
        self
    }

    /// Install a callback fired when the user Primary-clicks an inline
    /// image. The callback receives the activation (see
    /// [`ImageActivation`]) and the active `EventContext`.
    pub fn on_image_activated(
        self,
        handler: impl Fn(&ImageActivation, &mut teksilo_core::widget::EventContext) + 'static,
    ) -> Self {
        self.state.borrow_mut().on_image_activated = Some(std::rc::Rc::new(handler));
        self
    }
}

// =============================================================================
// EditorHandle — external toolbar / palette handle
// =============================================================================

/// A clone-able, `'static` handle to a [`RichTextEditor`]'s shared
/// state.
///
/// Use this when a toolbar, palette, command panel, or other external
/// widget needs to invoke editor commands from `on_activate_fn` /
/// `ctx.effect` closures that outlive the borrow of `&editor`.
/// [`RichTextEditor`] itself is move-only (the optional
/// `custom_context_menu` factory holds a `Box<dyn Fn>`, which prevents
/// `Clone`), so a closure cannot just capture `editor.clone()`.
/// Obtain a handle via [`RichTextEditor::handle()`] and clone it into
/// each closure that needs to issue commands.
///
/// `EditorHandle` mirrors the toolbar-relevant subset of the editor's
/// public API:
///
/// * Inline character formatting — [`set_bold`](Self::set_bold) /
///   [`toggle_bold`](Self::toggle_bold) / [`is_bold`](Self::is_bold)
///   and the italic / underline / strikethrough variants.
/// * Block-level formatting — [`set_alignment`](Self::set_alignment),
///   [`set_heading_level`](Self::set_heading_level),
///   [`apply_block_format`](Self::apply_block_format),
///   [`insert_list`](Self::insert_list),
///   [`indent`](Self::indent) / [`outdent`](Self::outdent).
/// * Tables — [`insert_table`](Self::insert_table) and the per-row /
///   per-column / remove operations, plus [`is_in_table`](Self::is_in_table)
///   for contextual UI enable state.
/// * History — [`undo`](Self::undo) / [`redo`](Self::redo).
/// * Clipboard — [`copy`](Self::copy) / [`cut`](Self::cut) /
///   [`paste`](Self::paste) /
///   [`paste_unformatted`](Self::paste_unformatted), plus
///   [`can_paste`](Self::can_paste) for Paste enable-state — so a
///   context-menu factory (which can only capture a handle, never the
///   editor that owns it) can rebuild Cut / Copy / Paste /
///   Paste-Unformatted.
/// * Selection — [`select_all`](Self::select_all) /
///   [`delete_selection`](Self::delete_selection).
/// * Reactive signal accessors —
///   [`format_version`](Self::format_version),
///   [`cursor_position_signal`](Self::cursor_position_signal),
///   [`cursor_anchor_signal`](Self::cursor_anchor_signal),
///   [`has_selection`](Self::has_selection),
///   [`can_undo`](Self::can_undo) / [`can_redo`](Self::can_redo) — so
///   callers that hold only an `EditorHandle` can derive bound signals
///   without keeping a separate `RichTextEditor` reference.
///
/// Cloning is cheap (an `Rc` clone). All clones share the same
/// underlying state — mutations through any clone, through other
/// clones, or through the originating `RichTextEditor` are all
/// immediately observable through the same signals.
#[derive(Clone)]
pub struct EditorHandle {
    state: SharedState,
}

impl std::fmt::Debug for EditorHandle {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("EditorHandle").finish_non_exhaustive()
    }
}

/// An [`EditorHandle`] that does not keep its editor alive.
///
/// **For a callback the editor itself stores.** `on_image_activated`,
/// `on_image_resized`, `on_link_activated`, `on_files_dropped`, `on_change`,
/// `on_text_inserted` and the image resolver are all kept on the editor's own
/// state, so a handler that captures an [`EditorHandle`] by value makes the state
/// own itself. Nothing can break that ring afterwards: the widget can be
/// destroyed, its tree dropped and its window closed, and the editor — with its
/// document, its cursor and its shaped layout — stays resident for the life of
/// the process. It is a leak with no owner left to blame, and it is easy to write,
/// because reaching for `editor.handle()` is the obvious way for such a handler to
/// act on the editor it belongs to.
///
/// Capture this instead and [`upgrade`](Self::upgrade) inside the handler. The
/// handler runs only while the editor is alive, which is the only time it could
/// have done anything anyway.
///
/// ```ignore
/// let editor = RichTextEditor::editor(doc);
/// let weak = editor.handle().downgrade();
/// let editor = editor.on_image_activated(move |activation, _ctx| {
///     let Some(handle) = weak.upgrade() else { return };
///     handle.select_range(activation.offset, activation.offset + 1);
/// });
/// ```
///
/// A factory the *builder* stores rather than the state —
/// [`context_menu`](RichTextEditor::context_menu) is the one today — may hold a
/// strong handle safely, because it dies with the widget.
#[derive(Clone)]
pub struct WeakEditorHandle {
    state: std::rc::Weak<std::cell::RefCell<EditorState>>,
}

impl WeakEditorHandle {
    /// The handle, if its editor is still alive.
    pub fn upgrade(&self) -> Option<EditorHandle> {
        self.state.upgrade().map(|state| EditorHandle { state })
    }
}

impl std::fmt::Debug for WeakEditorHandle {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("WeakEditorHandle")
            .field("alive", &self.state.strong_count().min(1))
            .finish()
    }
}

/// An inline image the user clicked.
///
/// Carries the offset as well as the name because a document may hold the same
/// picture more than once — a name alone cannot say *which* one was clicked, so
/// a host acting on the click (selecting it, editing its size, replacing it)
/// would be guessing. The offset addresses the image's single `U+FFFC`, so
/// `select_range(offset, offset + 1)` selects exactly it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImageActivation {
    /// The image's resource name — the `src` the document stores.
    pub name: String,
    /// Character offset of the image within the document.
    pub offset: usize,
}

/// Rich text being dragged out of an editor.
///
/// The typed fast path for editor-to-editor drags: it carries the
/// `DocumentFragment` itself, so formatting, tables and inline images survive a
/// move the way they survive a copy/paste — where the `text/plain` MIME
/// alternative the drag also advertises (for other applications) could only
/// carry the words.
///
/// `source` and `range` are what let the drop tell a *move* from a *copy*:
/// dropped back into the editor it came from, the original has to be removed,
/// and only the source editor can say which range that was.
#[derive(Debug, Clone)]
pub struct EditorTextDrag {
    /// The editor the text was picked up from.
    pub source: teksilo_core::WidgetId,
    /// The dragged range in that editor, as document offsets.
    pub range: (usize, usize),
    /// The dragged content, with its formatting.
    pub fragment: teksilo_text::text_document::DocumentFragment,
    /// The same content as plain text — the drop's fallback, and the bytes
    /// handed to another application when the drag leaves the window.
    pub text: String,
}

/// Whether this payload is one the editor can take.
///
/// Text, files, and an [`EditorTextDrag`] from any editor. Any other typed
/// payload belongs to whichever widget understands that type — a binder row
/// dropped on the prose should still open a document, not paste its debug
/// representation.
///
/// **Optimistic while the drag is still in the air.** On Wayland the concrete
/// `files` / `text` arrive only at drop; during hover the payload carries just
/// the *advertised* formats. Judging by content alone therefore refuses every
/// external drag for its whole flight — the drop is forbidden everywhere right
/// up to the release that would have filled it in. So an advertised
/// `text/uri-list` or text format counts as acceptance, and the real check
/// happens at drop, where there is finally something to check. This is the same
/// rule `DropTarget::accept_external_files` / `accept_external_text` apply.
fn droppable(payload: &teksilo_core::DragPayload) -> bool {
    if payload.get_typed::<EditorTextDrag>().is_some() {
        return true;
    }
    if !payload.files().is_empty() || payload.text().is_some_and(|t| !t.is_empty()) {
        return true;
    }
    payload.formats().iter().any(|f| {
        f.starts_with("text/uri-list")
            || f.starts_with("text/plain")
            || matches!(f.as_str(), "UTF8_STRING" | "STRING" | "TEXT")
    })
}

/// A resize the reader finished dragging.
///
/// Reported once, on release, rather than continuously: the document is the
/// durable record and rewriting it on every pointer move would put a hundred
/// entries on the undo stack for one gesture.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImageResize {
    /// The image's resource name.
    pub name: String,
    /// Character offset of its `U+FFFC` — the identity, since a document may
    /// hold one picture in several places.
    pub offset: usize,
    /// The new display size in logical pixels, proportions preserved.
    pub width: u32,
    pub height: u32,
}

impl EditorHandle {
    /// A handle that does not keep this editor alive.
    ///
    /// Capture this, not `self`, in any handler the editor stores — see
    /// [`WeakEditorHandle`] for which those are and what a strong capture costs.
    pub fn downgrade(&self) -> WeakEditorHandle {
        WeakEditorHandle {
            state: Rc::downgrade(&self.state),
        }
    }

    // --- Search / find-banner support (B3, handle mirror) ------------------
    //
    // These mirror the same-named [`RichTextEditor`] methods (which operate on
    // the same `state`), so a per-editor find banner built *above* the editor
    // can drive selection / scroll-into-view on the current match through the
    // handle it captured — the widget itself is long gone into the tree by then.

    /// This editor's content as Djot.
    ///
    /// The counterpart to [`insert_djot`](Self::insert_djot): a toolbar or command that can
    /// write into an editor it did not build should be able to read it back the same way.
    /// Without this the only route to the text is the host's own document bookkeeping,
    /// which knows about the editors it *mounted* and not about the ones a list or a card
    /// grid created — so a command ends up working on some surfaces and silently doing
    /// nothing on others.
    ///
    /// Empty string on a serialisation error, matching `TextDocument::to_djot`'s own
    /// callers: a command reading an editor has no better answer than "nothing there", and
    /// propagating a `Result` here would push that decision onto every call site.
    pub fn to_djot(&self) -> String {
        self.state.borrow().document.to_djot().unwrap_or_default()
    }

    /// This editor's content as the *addressable* plain text — the view whose
    /// character offsets are the document's own.
    ///
    /// The counterpart to [`to_djot`](Self::to_djot) for a caller that has an
    /// offset (a caret, a selection, a click) and needs to know what is there.
    /// An inline image appears as its `U+FFFC`, so offsets into this string are
    /// offsets into the document, character for character — which the `.txt`
    /// export's view deliberately is not.
    ///
    /// Empty string on error, for the same reason `to_djot` returns one.
    pub fn to_plain_text(&self) -> String {
        self.state
            .borrow()
            .document
            .to_plain_text()
            .unwrap_or_default()
    }

    /// Whether this editor holds no text at all.
    ///
    /// `character_count() == 0`, so a document of one empty paragraph is empty but one
    /// holding only spaces is not. The distinction a caller usually wants is
    /// `to_plain_text().trim().is_empty()`, and this is the cheap O(1) pre-check. The Djot
    /// does not answer it: from text-document 1.12.3 on, [`to_djot`](Self::to_djot) keeps a
    /// paragraph's edge spaces between `{}` markers, so a paragraph of spaces writes a
    /// non-empty text.
    pub fn is_empty(&self) -> bool {
        self.state.borrow().document.is_empty()
    }

    /// Reactive signal — `true` while **this** editor holds keyboard focus.
    /// See [`RichTextEditor::focused_signal`].
    pub fn focused_signal(&self) -> Signal<bool> {
        self.state.borrow().focus_signal.clone()
    }

    /// Select the character range `[start, end)` without collapsing (anchor at
    /// `start`, caret at `end`). See [`RichTextEditor::select_range`].
    pub fn select_range(&self, start: usize, end: usize) {
        {
            let mut st = self.state.borrow_mut();
            st.cursor.set_position(start, MoveMode::MoveAnchor);
            st.cursor.set_position(end, MoveMode::KeepAnchor);
            st.cursor_affinity = teksilo_text::CursorAffinity::Downstream;
        }
        sync_cursor_signals(&self.state);
    }

    /// Replace the character range `[start, end)` with `text`, leaving the caret
    /// after the inserted text.
    ///
    /// The counterpart to [`select_range`](Self::select_range) for callers that
    /// must *rewrite* a span rather than merely reveal it — a spell-check
    /// correction picked from a context menu, an autocorrect, a
    /// replace-this-occurrence action. It goes through the widget's **internal**
    /// cursor, so the edit behaves exactly like typed text: it lands on the
    /// editor's undo stack as one entry (the replacement is a single
    /// insert-over-selection), fires the document's change notifications, and
    /// leaves the caret where the user would expect it.
    ///
    /// Offsets are **character** positions, the same space
    /// [`cursor_position`](Self::cursor_position) and `select_range` use. The
    /// inserted text inherits the character format at `start`, so correcting a
    /// word inside italic prose stays italic.
    ///
    /// Reaching through [`TextDocument::cursor`](teksilo_text::text_document::TextDocument::cursor)
    /// instead would mutate the document behind the widget's back, leaving the
    /// caret decoupled from the edit — use this.
    pub fn replace_range(&self, start: usize, end: usize, text: &str) {
        self.replace_range_from(start, end, text, EditSource::Programmatic);
    }

    /// As [`replace_range`](Self::replace_range), saying which channel the text
    /// came through for [`on_text_inserted`](RichTextEditor::on_text_inserted).
    ///
    /// `replace_range` itself reports [`EditSource::Programmatic`], which is
    /// what a handle-driven edit is by default: a toolbar, a menu command, a
    /// substitution the application made. **An application that knows better
    /// should say so here rather than let the default stand.** The distinction
    /// that matters most is an edit which merely puts back what the person
    /// typed — undoing an autocorrect, say. Those characters were typed, they
    /// are being typed again, and reporting them as the application's own work
    /// would credit the application with the writer's words.
    ///
    /// One call rather than an insert plus a separate report, so the two cannot
    /// drift apart at a call site that later grows a second early return.
    pub fn replace_range_from(&self, start: usize, end: usize, text: &str, source: EditSource) {
        // Select, then insert over the selection — each step in its own borrow
        // scope, mirroring `select_range` / `RichTextEditor::insert_text`. The
        // insert must not run while a `borrow_mut` is held: it notifies document
        // observers, which are free to read the state back.
        self.select_range(start, end);
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_text(text);
            st.report_inserted(source, text);
        }
        sync_cursor_signals(&self.state);
    }

    /// Insert plain text at the caret, replacing any selection. The
    /// [`EditorHandle`] counterpart of
    /// [`RichTextEditor::insert_text`](RichTextEditor::insert_text), for callers
    /// that hold only a handle — a toolbar button or a global menu command.
    pub fn insert_text(&self, text: &str) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_text(text);
        }
        sync_cursor_signals(&self.state);
    }

    /// Register an image's bytes on this editor's document, under `name`.
    ///
    /// An inline image stores only a name; the paint pass resolves it to pixels
    /// through the document's resource table. So an image inserted without this
    /// lays out and stays blank — and the name is also what a *reload* resolves
    /// against, which is why a host restoring a document has to register its
    /// images before the first paint rather than at insertion time only.
    ///
    /// On the handle rather than only on the widget because commands operate on
    /// whichever editor has focus, including ones a list or card grid built that
    /// the host never mounted itself.
    pub fn add_image_resource(&self, name: &str, mime_type: &str, bytes: &[u8]) -> bool {
        let st = self.state.borrow();
        st.document
            .add_resource(ResourceType::Image, name, mime_type, bytes)
            .is_ok()
    }

    /// The natural pixel size of a registered image, decoded from its bytes.
    ///
    /// What the file actually is, not what the document asks it to be shown at
    /// — so a host offering "reset to the original size" restores the picture's
    /// own dimensions rather than a number remembered from when it was inserted,
    /// which is wrong the moment the file behind the name is replaced.
    ///
    /// Decodes on call. That is deliberate: this answers an explicit, rare
    /// request, and caching it would mean holding a second copy of every image
    /// in the document for a question almost nobody asks.
    pub fn image_resource_size(&self, name: &str) -> Option<(u32, u32)> {
        let bytes = self.state.borrow().document.resource(name).ok()??;
        let icon = teksilo_canvas::RasterIcon::decode(&bytes).ok()?;
        Some((icon.width(), icon.height()))
    }

    /// Whether this editor's document already has an image under `name`.
    ///
    /// Registering the same name twice appends a second resource row, so a host
    /// re-registering on every paint would grow the document without bound.
    pub fn has_image_resource(&self, name: &str) -> bool {
        let st = self.state.borrow();
        st.document.resource(name).ok().flatten().is_some()
    }

    /// Insert a fragment parsed from djot at the caret, replacing any selection.
    ///
    /// Unlike [`insert_text`](Self::insert_text), which drops its bytes into the
    /// current block verbatim (a `\n` becomes literal content, not a new
    /// paragraph), this parses block-level djot into a `DocumentFragment`, so
    /// inserting a standalone paragraph really does create one.
    pub fn insert_djot(&self, djot: &str) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_djot(djot);
        }
        sync_cursor_signals(&self.state);
    }

    /// Split the current block at the caret, as pressing Enter does.
    pub fn insert_block(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_block();
        }
        sync_cursor_signals(&self.state);
    }

    /// Insert `text` as a **paragraph of its own** at the caret: split here, fill
    /// the new block, split again, so whatever followed the caret continues in a
    /// third block.
    ///
    /// Deliberately one call rather than three. Composing
    /// `insert_block` + `insert_text` + `insert_block` from outside re-enters the
    /// widget three times, and an application that rebuilds its editor in
    /// response to the first change notification is left driving a handle that
    /// no longer points at the mounted widget — the split lands and the text
    /// silently does not. Doing the whole edit under a single borrow, with one
    /// signal sync at the end, makes it atomic from the caller's side.
    /// Returns `false` if any step failed, leaving the document as far as it
    /// got. Steps are **not** attempted after a failure: filling and re-splitting
    /// on top of a split that did not happen produces a mangled paragraph rather
    /// than a partial one, and the caller has no way to tell.
    pub fn insert_paragraph(&self, text: &str) -> bool {
        let ok = {
            let st = self.state.borrow();
            st.cursor.insert_block().is_ok()
                && st.cursor.insert_text(text).is_ok()
                && st.cursor.insert_block().is_ok()
        };
        sync_cursor_signals(&self.state);
        ok
    }

    /// The live selection as `(anchor, position)`, unordered — `anchor` is where the
    /// selection started, `position` is where the caret is, so a backwards drag
    /// reports `anchor > position`. Equal values mean no selection.
    ///
    /// Both ends are read under a **single** borrow, so the pair cannot tear. That is
    /// the reason to prefer this over pairing [`cursor_position`](Self::cursor_position)
    /// with [`cursor_anchor_signal`](Self::cursor_anchor_signal): the former is a live
    /// read of the cursor while the latter is a mirror refreshed on sync, so combining
    /// them mixes two different moments in time and can invent — or miss — a selection
    /// if the mirror lags. A caller deciding *"is there a selection, and over what"*
    /// wants one consistent answer.
    pub fn selection(&self) -> (usize, usize) {
        let st = self.state.borrow();
        (st.cursor.anchor(), st.cursor.position())
    }

    /// The selected text, or an empty string when nothing is selected.
    ///
    /// O(selection), not O(document). Pairs with [`selection`](Self::selection)
    /// for a caller that needs the range *and* what is in it — a link dialog
    /// pre-filling its display name from what the writer highlighted, say.
    pub fn selected_text(&self) -> String {
        self.state
            .borrow()
            .cursor
            .selected_text()
            .unwrap_or_default()
    }

    /// The **window-space** rectangle enclosing the character range `[start, end)`.
    ///
    /// The inverse of [`offset_at_point`](Self::offset_at_point): that maps a point
    /// to an offset, this maps offsets back to a point. It is what a decoration
    /// drawn *outside* the editor — a margin annotation, a connector leader, a
    /// bracket spanning a paragraph — needs in order to line itself up with the
    /// text it refers to.
    ///
    /// Coordinates match what the arena stores (`viewport_origin` + engine-local −
    /// scroll), so the result can be compared with any other widget's bounds
    /// directly, and it tracks scrolling for free.
    ///
    /// `None` before the first full layout. Focus is **not** required — a margin
    /// annotation must stay aligned whether or not the writer is typing.
    pub fn range_rect(&self, start: usize, end: usize) -> Option<Rect> {
        let st = self.state.borrow();
        keyboard::range_window_rect(&st, start, end)
    }

    /// The **window-space** caret rectangle at one offset — a zero-width
    /// [`range_rect`](Self::range_rect), and the anchor point for a marker drawn at
    /// one end of a span (the triangle at a comment's tail).
    pub fn offset_rect(&self, offset: usize) -> Option<Rect> {
        self.range_rect(offset, offset)
    }

    /// The **content-space** rectangle enclosing `[start, end)` — y = 0 at the top
    /// of the laid-out text, unaffected by scrolling and by where the editor sits
    /// in the window.
    ///
    /// The scroll-free counterpart to [`range_rect`](Self::range_rect), and the one
    /// to reach for when the question is *what proportion of the document is this*
    /// rather than *where is this on screen*. Divided by
    /// [`content_height`](Self::content_height) it gives a fraction an overview
    /// strip can draw against, for offsets the writer has long scrolled past —
    /// which window space cannot express at all, since it reports those relative to
    /// a viewport they are nowhere near.
    ///
    /// `None` before the first full layout. Focus is not required.
    pub fn range_content_rect(&self, start: usize, end: usize) -> Option<Rect> {
        let st = self.state.borrow();
        keyboard::range_content_rect(&st, start, end)
    }

    /// The **content-space** caret rectangle at one offset — a zero-width
    /// [`range_content_rect`](Self::range_content_rect).
    pub fn offset_content_rect(&self, offset: usize) -> Option<Rect> {
        self.range_content_rect(offset, offset)
    }

    /// Reactive counter that bumps on every document change — the handle mirror of
    /// [`RichTextEditor::document_version`].
    ///
    /// The change token a decoration drawn *outside* the editor binds, so it
    /// re-derives when the text moves under it. Without it such a widget has only
    /// the scroll metrics to go on, and those move on a reflow but not on an edit
    /// that leaves the height alone — which is most edits, and exactly the ones that
    /// shift the offsets a mark is anchored to.
    pub fn document_version(&self) -> Signal<u64> {
        self.state.borrow().document_version.clone()
    }

    /// Height of the laid-out text, in the same space
    /// [`range_content_rect`](Self::range_content_rect) reports.
    ///
    /// The denominator that turns a content rect into a fraction of the document.
    /// `None` before the first full layout — the same gate the rect queries use, so
    /// a caller that has one has the other and the division is never against a
    /// stale height.
    ///
    /// This is the *text's* height, not the widget's: an editor laid out taller
    /// than its content (a short scene in a tall pane) reports the text.
    pub fn content_height(&self) -> Option<f32> {
        let st = self.state.borrow();
        st.engine
            .has_full_layout()
            .then(|| st.engine.content_height())
    }

    /// Hit-test a point — **in window coordinates**, as a
    /// [`context_menu`](RichTextEditor::context_menu) factory receives it — to a
    /// document character offset. `None` when the point resolves to no text
    /// (past the last glyph on an empty line, outside the body, etc.).
    ///
    /// Lets a custom context-menu factory resolve "the word under the pointer"
    /// from the right-click position, since a bare right-click does not move the
    /// caret on its own.
    pub fn offset_at_point(&self, window_point: Point) -> Option<usize> {
        mouse::offset_at_window_point(&self.state, window_point)
    }

    /// Reposition the caret to a right-click point (**window coordinates**)
    /// unless the click lands inside the current selection (then the selection
    /// is preserved). Call this at the top of a custom
    /// [`context_menu`](RichTextEditor::context_menu) factory so the menu's Paste
    /// — and any caret-relative action — operates where the user clicked, exactly
    /// as the built-in menu and the single-line field do.
    ///
    /// Only when a pointer opened the menu
    /// ([`EventContext::context_menu_trigger`](teksilo_core::widget::EventContext::context_menu_trigger)):
    /// a menu opened from the keyboard is handed an anchor in the middle of the
    /// editor, and moving the caret there sends Paste away from where the user is.
    pub fn reposition_caret_for_context_menu(&self, window_point: Point) {
        mouse::reposition_caret_for_context_menu(&self.state, window_point);
    }

    /// Scroll the character range `[start, end)` into view, reporting whether this editor
    /// could — it has a layout to locate the range in, and is on screen rather than parked
    /// dormant. See [`RichTextEditor::reveal_range`].
    ///
    /// When it answers `false` because there is no layout yet, the coarser
    /// [`reveal_widget`](Self::reveal_widget) is the way to get one.
    pub fn reveal_range(
        &self,
        ctx: &mut teksilo_core::widget::EventContext,
        start: usize,
        end: usize,
    ) -> bool {
        reveal_range_impl(&self.state, ctx, start, end)
    }

    /// Scroll **the editor itself** into view — the coarse fallback for the one case
    /// [`reveal_range`](Self::reveal_range) cannot serve at all. Reports whether this
    /// editor could: it has been built, so the arena knows a widget to scroll to, and
    /// it is on screen rather than parked dormant.
    ///
    /// A row of a stream that has never been painted has no full layout, so there is
    /// no rect to locate an offset in and `reveal_range` answers `false` — for ever,
    /// because the row only gets a layout when it is painted and it is only painted
    /// when it comes on screen. That is a deadlock a range reveal has no way out of:
    /// a match found in row 31 of a Book leaves the page exactly where it was, with
    /// the counter cheerfully reading `1 of 40`.
    ///
    /// Revealing by *widget* breaks it, because the arena knows where row 31 is laid
    /// out whether or not its text has been shaped. The row comes on screen, the next
    /// paint gives it a layout, and a later `reveal_range` can then put the match
    /// itself where the caller wants it. Coarser on purpose: this reveals the row,
    /// not the offset inside it.
    pub fn reveal_widget(&self, ctx: &mut teksilo_core::widget::EventContext) -> bool {
        let id = {
            let st = self.state.borrow();
            // The same dormancy gate `reveal_range` applies, and for the same reason:
            // a parked editor's bounds are still in the arena, so the walk would
            // happily scroll a container nobody can see and answer `true` — and a
            // caller told `true` stops looking for the editor that is on screen.
            if st.activation.as_ref().is_some_and(|a| !a.get()) {
                return false;
            }
            // `None` only before the editor's first build: nothing is mounted, so
            // there is no widget for the arena to resolve bounds for.
            match st.self_id {
                Some(id) => id,
                None => return false,
            }
        };
        ctx.ensure_widget_visible(id);
        true
    }

    /// Move keyboard focus onto the editor. Lets a control built *above* the
    /// editor — a find banner returning focus to the prose on Escape — put the
    /// caret back where the user expects. A no-op until the editor has built at
    /// least once (its wrapper id is stashed then).
    pub fn focus(&self, ctx: &mut teksilo_core::widget::EventContext) {
        if let Some(id) = self.state.borrow().self_id {
            ctx.request_focus(id);
        }
    }

    // --- Character-format query / apply ------------------------------------

    /// Read the current character format at the caret. When a selection
    /// is active, reads from `selection_start()` rather than
    /// `position()` so toolbar bistate stays stable across selection
    /// extension (same rule as
    /// [`RichTextEditor::caret_char_format`]).
    pub fn caret_char_format(&self) -> TextFormat {
        let st = self.state.borrow();
        let probe_pos = if st.cursor.has_selection() {
            st.cursor.selection_start()
        } else {
            st.cursor.position()
        };
        let probe = st.document.cursor();
        probe.set_position(probe_pos, MoveMode::MoveAnchor);
        probe.char_format().unwrap_or_default()
    }

    fn apply_char_format(&self, fmt: TextFormat) {
        let st = self.state.borrow();
        let _ = st.cursor.merge_char_format(&fmt);
    }

    /// Apply **bold** to the current selection.
    pub fn set_bold(&self, enabled: bool) {
        self.apply_char_format(TextFormat {
            font_bold: Some(enabled),
            ..Default::default()
        });
    }

    /// Apply *italic* to the current selection.
    pub fn set_italic(&self, enabled: bool) {
        self.apply_char_format(TextFormat {
            font_italic: Some(enabled),
            ..Default::default()
        });
    }

    /// Apply underline to the current selection.
    pub fn set_underline(&self, enabled: bool) {
        self.apply_char_format(TextFormat {
            font_underline: Some(enabled),
            ..Default::default()
        });
    }

    /// Apply strikethrough to the current selection.
    pub fn set_strikethrough(&self, enabled: bool) {
        self.apply_char_format(TextFormat {
            font_strikeout: Some(enabled),
            ..Default::default()
        });
    }

    /// Set the font family for the current selection (a character-format
    /// change applied over the selected range). Like the other char-format
    /// setters (`set_bold`, …), this is a **no-op when there is no
    /// selection** — the document model has no typing/pending format, so a
    /// bare caret has no range to format. `family` must be a name resolvable
    /// by the shared typesetter's font registrar — e.g. a value chosen from
    /// a [`FontPicker`](crate::font_picker::FontPicker).
    pub fn set_font_family(&self, family: impl Into<String>) {
        self.apply_char_format(TextFormat {
            font_family: Some(family.into()),
            ..Default::default()
        });
    }

    /// Set the font size (in points) for the current selection.
    pub fn set_font_size(&self, size: u32) {
        self.apply_char_format(TextFormat {
            font_point_size: Some(size),
            ..Default::default()
        });
    }

    // --- Default typography / font size (non-destructive, whole editor) ---

    /// Set the non-destructive default typography (font family / line height /
    /// first-line indent) filled onto runs and blocks with no explicit
    /// override. Unlike [`set_font_family`](Self::set_font_family) /
    /// [`set_font_size`](Self::set_font_size) — which mutate the selected text —
    /// this is a display-time default: it never touches the document, undo
    /// stack, or `modified` flag. Schedules a relayout + repaint.
    pub fn set_typography_defaults(&self, defaults: EditorTypographyDefaults) {
        let mut st = self.state.borrow_mut();
        st.engine.set_typography_defaults(defaults);
        st.needs_full_layout = true;
        st.content_dirty = true;
        if let Some(handle) = &st.frame_request {
            handle.set(true);
        }
    }

    /// Current default typography.
    pub fn get_typography_defaults(&self) -> EditorTypographyDefaults {
        self.state.borrow().engine.typography_defaults().clone()
    }

    /// Set the per-editor logical font-size multiplier. See
    /// [`RichTextEditor::set_font_size_scale`].
    pub fn set_font_size_scale(&self, scale: f32) {
        let mut st = self.state.borrow_mut();
        let scale = scale.clamp(0.1, 10.0);
        if (st.font_size_scale - scale).abs() <= f32::EPSILON {
            return;
        }
        st.font_size_scale = scale;
        st.last_font_scale = f32::NAN;
        st.needs_full_layout = true;
        st.content_dirty = true;
        if let Some(handle) = &st.frame_request {
            handle.set(true);
        }
    }

    /// Current per-editor font-size scale (`1.0` = 100 %).
    pub fn get_font_size_scale(&self) -> f32 {
        self.state.borrow().font_size_scale
    }

    /// Set the typewriter-scrolling anchor — the [`EditorHandle`] counterpart of
    /// [`RichTextEditor::set_typewriter`]. `None` turns pinning off.
    ///
    /// This is the door a host uses to keep the pin following a live setting,
    /// the same way [`set_typography_defaults`](Self::set_typography_defaults)
    /// keeps typography following one.
    pub fn set_typewriter(&self, anchor: Option<f32>) {
        let mut st = self.state.borrow_mut();
        st.typewriter = anchor.map(|f| f.clamp(0.0, 1.0));
        st.last_chase_y = None;
    }

    /// Current typewriter anchor.
    pub fn get_typewriter(&self) -> Option<f32> {
        self.state.borrow().typewriter
    }

    /// Narrow (or restore) what the keyboard may do — the [`EditorHandle`]
    /// counterpart of [`RichTextEditor::set_command_filter`], for hosts that
    /// drive a drafting mode from a settings or session effect after the editor
    /// is mounted.
    pub fn set_command_filter(&self, filter: policy::CommandFilter) {
        self.state.borrow_mut().policy.command_filter = filter;
    }

    /// The filter currently in force on this editor.
    pub fn command_filter(&self) -> policy::CommandFilter {
        self.state.borrow().policy.command_filter
    }

    /// Draw an ambient band behind the caret's sentence or paragraph — the [`EditorHandle`]
    /// counterpart of [`RichTextEditor::set_caret_highlight`], for hosts that re-push it from a
    /// settings or theme effect after the editor is mounted.
    pub fn set_caret_highlight(&self, highlight: Option<caret_highlight::CaretHighlight>) {
        set_caret_highlight(&self.state, highlight);
    }

    /// What this editor's caret band is currently configured to draw.
    pub fn get_caret_highlight(&self) -> Option<caret_highlight::CaretHighlight> {
        self.state
            .borrow()
            .caret_highlight
            .as_ref()
            .and_then(|s| s.config())
    }

    /// The caret's rectangle in **absolute window (tree) coordinates** — the
    /// [`EditorHandle`] counterpart of [`RichTextEditor::caret_window_rect`].
    /// `None` when unfocused or not yet laid out.
    pub fn caret_window_rect(&self) -> Option<teksilo_canvas::Rect> {
        self::keyboard::caret_window_rect(&self.state.borrow())
    }

    /// Apply an arbitrary [`TextFormat`] (escape hatch for fields not
    /// covered by the dedicated setters: `letter_spacing`,
    /// `foreground_color`, …).
    pub fn apply_text_format(&self, fmt: TextFormat) {
        self.apply_char_format(fmt);
    }

    /// Toggle bold on the current selection.
    pub fn toggle_bold(&self) {
        let current = self.caret_char_format().font_bold.unwrap_or(false);
        self.set_bold(!current);
    }

    /// Toggle italic on the current selection.
    pub fn toggle_italic(&self) {
        let current = self.caret_char_format().font_italic.unwrap_or(false);
        self.set_italic(!current);
    }

    /// Toggle underline on the current selection.
    pub fn toggle_underline(&self) {
        let current = self.caret_char_format().font_underline.unwrap_or(false);
        self.set_underline(!current);
    }

    /// Toggle strikethrough on the current selection.
    pub fn toggle_strikethrough(&self) {
        let current = self.caret_char_format().font_strikeout.unwrap_or(false);
        self.set_strikethrough(!current);
    }

    /// Whether the selection / typing position is bold.
    pub fn is_bold(&self) -> bool {
        self.caret_char_format().font_bold.unwrap_or(false)
    }

    /// Whether italic.
    pub fn is_italic(&self) -> bool {
        self.caret_char_format().font_italic.unwrap_or(false)
    }

    // ── Hyperlinks ───────────────────────────────────────────────
    //
    // A link is a character format, not an object: applying one merges a
    // destination onto a range, so any bold or italic already there survives
    // and no markup has to be escaped. What it does not get for free is
    // removal — every field of a merge means "leave this alone" when unset —
    // hence `clear_link` rather than "set the destination to nothing".

    /// Point the selection at `href`.
    ///
    /// Merges, so formatting already on the range is kept. A collapsed
    /// selection formats nothing (as everywhere else), so a caller linking
    /// existing text should select it first — see
    /// [`link_at_caret`](Self::link_at_caret) for the range of a link already
    /// there.
    pub fn set_link(&self, href: &str) {
        self.apply_char_format(TextFormat {
            anchor_href: Some(href.to_string()),
            ..Default::default()
        });
    }

    /// Take the link off the selection, leaving its text.
    pub fn clear_link(&self) {
        self.apply_char_format(TextFormat {
            clear_link: true,
            ..Default::default()
        });
    }

    /// The link the caret is in, and how far it reaches.
    ///
    /// Coalesced across the runs an inner mark splits a link into, so the
    /// range covers the whole link rather than the piece under the caret.
    /// `None` when the caret is not on a link.
    pub fn link_at_caret(&self) -> Option<LinkExtent> {
        self.state.borrow().cursor.link_at_caret()
    }

    /// Whether the caret / selection sits on a link.
    pub fn is_link(&self) -> bool {
        self.caret_char_format().is_anchor.unwrap_or(false)
    }

    /// Whether underline.
    pub fn is_underline(&self) -> bool {
        self.caret_char_format().font_underline.unwrap_or(false)
    }

    /// Whether strikethrough.
    pub fn is_strikethrough(&self) -> bool {
        self.caret_char_format().font_strikeout.unwrap_or(false)
    }

    // --- Vertical alignment (super / subscript) ----------------------------
    //
    // See [`RichTextEditor::set_superscript`]: one tri-state property shown as
    // two toggles, because a run cannot be both raised and lowered.

    /// Raise the selection to superscript, or return it to the baseline.
    pub fn set_superscript(&self, enabled: bool) {
        self.set_vertical_alignment(if enabled {
            CharVerticalAlignment::SuperScript
        } else {
            CharVerticalAlignment::Normal
        });
    }

    /// Lower the selection to subscript, or return it to the baseline.
    pub fn set_subscript(&self, enabled: bool) {
        self.set_vertical_alignment(if enabled {
            CharVerticalAlignment::SubScript
        } else {
            CharVerticalAlignment::Normal
        });
    }

    /// Set the selection's vertical alignment directly.
    pub fn set_vertical_alignment(&self, alignment: CharVerticalAlignment) {
        self.apply_char_format(TextFormat {
            vertical_alignment: Some(alignment),
            ..Default::default()
        });
    }

    /// The caret's vertical alignment, `Normal` when unset.
    pub fn get_vertical_alignment(&self) -> CharVerticalAlignment {
        self.caret_char_format()
            .vertical_alignment
            .unwrap_or(CharVerticalAlignment::Normal)
    }

    /// True while the caret sits in superscript text.
    pub fn is_superscript(&self) -> bool {
        self.get_vertical_alignment() == CharVerticalAlignment::SuperScript
    }

    /// True while the caret sits in subscript text.
    pub fn is_subscript(&self) -> bool {
        self.get_vertical_alignment() == CharVerticalAlignment::SubScript
    }

    /// Flip superscript on the selection. Turning it on replaces subscript.
    pub fn toggle_superscript(&self) {
        self.set_superscript(!self.is_superscript());
    }

    /// Flip subscript on the selection. Turning it on replaces superscript.
    pub fn toggle_subscript(&self) {
        self.set_subscript(!self.is_subscript());
    }

    // --- Block-format query / apply ----------------------------------------

    /// Apply an arbitrary [`BlockFormat`] to the caret's block.
    pub fn apply_block_format(&self, fmt: BlockFormat) {
        let st = self.state.borrow();
        let _ = st.cursor.set_block_format(&fmt);
    }

    /// Set paragraph alignment for the caret's block.
    pub fn set_alignment(&self, alignment: Alignment) {
        self.apply_block_format(BlockFormat {
            alignment: Some(alignment),
            ..Default::default()
        });
    }

    /// Unset the block's direction, handing the paragraph back to
    /// automatic detection.
    ///
    /// Not the same as setting left-to-right. An explicit direction
    /// *pins* the paragraph and overrides the bidi algorithm, so
    /// "clearing" a direction by writing `LeftToRight` would force
    /// Arabic and Hebrew prose to lay out backwards. Only an unset
    /// direction lets the text speak for itself.
    pub fn clear_direction(&self) {
        self.apply_block_format(BlockFormat {
            clear_direction: true,
            ..Default::default()
        });
    }

    /// Set the base reading direction of the caret's block. See
    /// [`RichTextEditor::set_direction`].
    pub fn set_direction(&self, direction: TextDirection) {
        self.apply_block_format(BlockFormat {
            direction: Some(direction),
            ..Default::default()
        });
    }

    /// Set heading level for the caret's block. `0` = plain paragraph,
    /// `1..=6` follow the HTML `<h1>..<h6>` convention.
    pub fn set_heading_level(&self, level: u8) {
        self.apply_block_format(BlockFormat {
            heading_level: Some(level),
            ..Default::default()
        });
    }

    /// Current block alignment.
    pub fn get_alignment(&self) -> Alignment {
        self.state
            .borrow()
            .cursor
            .block_format()
            .ok()
            .and_then(|f| f.alignment)
            .unwrap_or(Alignment::Left)
    }

    /// The block's explicitly-set reading direction, if it has one.
    ///
    /// `None` means the writer never chose — the bidi algorithm decides
    /// from the text. That is a genuinely different state from an
    /// explicit left-to-right, so it is reported rather than defaulted:
    /// a toggle needs to show "auto" as its own setting.
    pub fn get_direction(&self) -> Option<TextDirection> {
        self.state
            .borrow()
            .cursor
            .block_format()
            .ok()
            .and_then(|f| f.direction)
    }

    /// Current heading level (0 = plain paragraph).
    pub fn get_heading_level(&self) -> u8 {
        self.state
            .borrow()
            .cursor
            .block_format()
            .ok()
            .and_then(|f| f.heading_level)
            .unwrap_or(0)
    }

    // --- Lists -------------------------------------------------------------

    /// Wrap the caret's block in a list. `ordered = true` uses decimal
    /// numbering, `false` uses bullet discs.
    pub fn insert_list(&self, ordered: bool) {
        let style = if ordered {
            ListStyle::Decimal
        } else {
            ListStyle::Disc
        };
        self.create_list(style);
    }

    /// Wrap the caret's block in a list with an explicit
    /// [`ListStyle`].
    pub fn create_list(&self, style: ListStyle) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.create_list(style);
        }
        sync_cursor_signals(&self.state);
    }

    /// Indent the caret's current list item by one nesting level.
    /// No-op when the caret is not inside a list, and at the list ceiling (see
    /// [`RichTextEditor::indent`]). Equivalent to Tab.
    pub fn indent(&self) {
        keyboard::indent_current_block(&mut self.state.borrow_mut());
        sync_cursor_signals(&self.state);
    }

    /// Outdent the caret's current list item by one nesting level.
    /// No-op at depth 0. Equivalent to Shift+Tab.
    pub fn outdent(&self) {
        keyboard::dedent_current_block(&mut self.state.borrow_mut());
        sync_cursor_signals(&self.state);
    }

    /// Take the caret's block out of its list entirely, leaving a plain
    /// paragraph. No-op when the caret is not inside a list.
    ///
    /// See [`RichTextEditor::remove_from_list`] for why this is separate from
    /// [`outdent`](Self::outdent), which stops at depth 0 by design.
    pub fn remove_from_list(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.remove_current_block_from_list();
        }
        sync_cursor_signals(&self.state);
    }

    /// The style of the caret's list, or `None` outside a list. See
    /// [`RichTextEditor::current_list_style`].
    pub fn current_list_style(&self) -> Option<ListStyle> {
        lists::current_list_style(&self.state.borrow())
    }

    /// Give the caret's whole list `style`, keeping its depth. No-op outside a
    /// list. See [`RichTextEditor::set_list_style`].
    pub fn set_list_style(&self, style: ListStyle) {
        lists::set_list_style(&self.state.borrow(), style);
        sync_cursor_signals(&self.state);
    }

    /// The press of a "Bullets" or "Numbering" button, as one undo step. See
    /// [`RichTextEditor::toggle_list`].
    pub fn toggle_list(&self, ordered: bool) {
        lists::toggle_list(&self.state.borrow(), ordered);
        sync_cursor_signals(&self.state);
    }

    // --- Blockquotes -------------------------------------------------------

    /// True iff the caret currently sits inside a blockquote frame at
    /// any nesting depth.
    pub fn is_in_blockquote(&self) -> bool {
        let st = self.state.borrow();
        st.cursor.is_in_blockquote()
    }

    /// True iff the selection spans more than one frame — the
    /// "Toggle blockquote" affordance should be disabled in this case.
    pub fn selection_spans_multiple_frames(&self) -> bool {
        let st = self.state.borrow();
        st.cursor.selection_spans_multiple_frames()
    }

    /// Wrap the current block/selection in a blockquote, or unwrap the
    /// innermost enclosing blockquote if already inside one. Toolbar
    /// counterpart for a Ctrl+Shift+Q-style toggle. The wrap does nothing
    /// where it would take a block past the quote ceiling (see
    /// [`RichTextEditor::toggle_blockquote`]).
    pub fn toggle_blockquote(&self) {
        nesting::toggle_blockquote(&self.state.borrow());
        sync_cursor_signals(&self.state);
    }

    /// Wrap the current block in a deeper nested quote. Equivalent to
    /// Tab inside a blockquote: a no-op outside a quote and at the quote
    /// ceiling (see [`RichTextEditor::increase_blockquote_depth`]).
    pub fn increase_blockquote_depth(&self) {
        nesting::increase_blockquote_depth(&self.state.borrow());
        sync_cursor_signals(&self.state);
    }

    /// Pop the caret out of one blockquote nesting level. Shift+Tab does the
    /// same in a quote outside a list or a table; on a list item it is a list
    /// outdent and leaves the quote alone (see
    /// [`RichTextEditor::decrease_blockquote_depth`]).
    pub fn decrease_blockquote_depth(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.decrease_blockquote_depth();
        }
        sync_cursor_signals(&self.state);
    }

    // --- Tables ------------------------------------------------------------

    /// Insert a fresh `rows × columns` table at the caret.
    pub fn insert_table(&self, rows: usize, columns: usize) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_table(rows, columns);
        }
        sync_cursor_signals(&self.state);
    }

    /// Remove the table containing the caret. No-op outside a table.
    pub fn remove_current_table(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.remove_current_table();
        }
        sync_cursor_signals(&self.state);
    }

    /// Insert a row above the caret's current table row.
    pub fn insert_row_above(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_row_above();
        }
        sync_cursor_signals(&self.state);
    }

    /// Insert a row below the caret's current table row.
    pub fn insert_row_below(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_row_below();
        }
        sync_cursor_signals(&self.state);
    }

    /// Insert a column before the caret's current table column.
    pub fn insert_column_before(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_column_before();
        }
        sync_cursor_signals(&self.state);
    }

    /// Insert a column after the caret's current table column.
    pub fn insert_column_after(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.insert_column_after();
        }
        sync_cursor_signals(&self.state);
    }

    /// Remove the caret's current table row.
    pub fn remove_current_row(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.remove_current_row();
        }
        sync_cursor_signals(&self.state);
    }

    /// Remove the caret's current table column.
    pub fn remove_current_column(&self) {
        {
            let st = self.state.borrow();
            let _ = st.cursor.remove_current_column();
        }
        sync_cursor_signals(&self.state);
    }

    /// Whether the caret is currently inside a table cell.
    pub fn is_in_table(&self) -> bool {
        self.state.borrow().cursor.current_table().is_some()
    }

    // --- History -----------------------------------------------------------

    /// Undo the most recent edit. No-op when the undo stack is empty.
    pub fn undo(&self) {
        let _ = self.state.borrow().document.undo();
        sync_cursor_signals(&self.state);
    }

    /// Close the current undo entry, so the next edit starts a new one.
    ///
    /// Typing coalesces into word-sized undo steps by looking only at the shape
    /// of two edits — adjacent, moments apart. It cannot see that the user did
    /// something else in between, somewhere else in the application, that they
    /// would remember as a dividing line. A host that knows one was crossed says
    /// so here, and the burst before it stops merging with the burst after.
    pub fn break_undo_merge(&self) {
        self.state.borrow().document.break_undo_merge();
    }

    /// Redo the most recently undone edit. No-op when the redo stack
    /// is empty.
    pub fn redo(&self) {
        let _ = self.state.borrow().document.redo();
        sync_cursor_signals(&self.state);
    }

    // --- Edit blocks (composite undo) --------------------------------------
    //
    // See [`RichTextEditor::begin_edit_block`] for the rationale: a toolbar
    // action composed of several commands should cost one Ctrl+Z, not one per
    // property it touched.

    /// Begin grouping subsequent edits into a single undo entry. Pair with
    /// [`end_edit_block`](Self::end_edit_block), or prefer the scoped
    /// [`edit_block`](Self::edit_block).
    pub fn begin_edit_block(&self) {
        self.state.borrow().cursor.begin_edit_block();
    }

    /// Close the group opened by [`begin_edit_block`](Self::begin_edit_block).
    pub fn end_edit_block(&self) {
        self.state.borrow().cursor.end_edit_block();
    }

    /// Run `edits` as one undo entry — the pairing-safe form.
    pub fn edit_block<R>(&self, edits: impl FnOnce() -> R) -> R {
        self.begin_edit_block();
        let result = edits();
        self.end_edit_block();
        result
    }

    // --- Clipboard ---------------------------------------------------------
    //
    // Programmatic counterparts of Ctrl+C / Ctrl+X / Ctrl+V /
    // Ctrl+Shift+V, mirroring [`RichTextEditor::copy`] / `cut` / `paste` /
    // `paste_unformatted` body-for-body. Each takes the active
    // [`EventContext`](teksilo_core::widget::EventContext) because the
    // clipboard handle is looked up via `ctx.app_state::<ClipboardHandle>()`,
    // which only has a value during event dispatch — so these are callable
    // from an `on_activate_fn` / context-menu closure that captured just a
    // handle. A call site holding `&mut EventContext` can pass `&ctx`
    // directly; Rust reborrows automatically.

    /// Copy the current selection to the system clipboard (plain + HTML
    /// payloads). No-op when there is no selection. See
    /// [`RichTextEditor::copy`].
    pub fn copy(&self, ctx: &teksilo_core::widget::EventContext) {
        let mut st = self.state.borrow_mut();
        clipboard::copy(&mut st, ctx);
    }

    /// Cut the current selection: copy first, then remove. See
    /// [`RichTextEditor::cut`].
    pub fn cut(&self, ctx: &teksilo_core::widget::EventContext) {
        {
            let mut st = self.state.borrow_mut();
            clipboard::cut(&mut st, ctx);
        }
        sync_cursor_signals(&self.state);
    }

    /// Paste from the system clipboard. Prefers an in-process fragment
    /// over HTML over plain text. See [`RichTextEditor::paste`].
    pub fn paste(&self, ctx: &teksilo_core::widget::EventContext) {
        {
            let mut st = self.state.borrow_mut();
            clipboard::paste(&mut st, ctx);
        }
        sync_cursor_signals(&self.state);
    }

    /// Paste plain text only, stripping any rich payload. See
    /// [`RichTextEditor::paste_unformatted`].
    pub fn paste_unformatted(&self, ctx: &teksilo_core::widget::EventContext) {
        {
            let mut st = self.state.borrow_mut();
            clipboard::paste_unformatted(&mut st, ctx);
        }
        sync_cursor_signals(&self.state);
    }

    /// Whether a paste would insert anything — `true` iff the system
    /// clipboard carries text **or** an HTML payload. A point-in-time
    /// query (clipboard contents are not reactively observable), taking
    /// the active [`EventContext`](teksilo_core::widget::EventContext).
    /// Use it to drive a context-menu / toolbar Paste enable-state,
    /// re-querying on menu-open. Mirrors [`RichTextEditor::can_paste`].
    pub fn can_paste(&self, ctx: &teksilo_core::widget::EventContext) -> bool {
        clipboard::can_paste(ctx)
    }

    // --- Selection ---------------------------------------------------------

    /// Select the entire document programmatically. Resets the Ctrl+A
    /// ladder so a subsequent Ctrl+A starts fresh at level 1. Mirrors
    /// [`RichTextEditor::select_all`].
    pub fn select_all(&self) {
        {
            let mut st = self.state.borrow_mut();
            st.cursor.select(SelectionType::Document);
            st.select_all_level = 0;
            st.select_all_anchor_cell = None;
        }
        sync_cursor_signals(&self.state);
    }

    /// Delete the current selection. No-op when nothing is selected.
    /// Mirrors [`RichTextEditor::delete_selection`].
    pub fn delete_selection(&self) {
        {
            let st = self.state.borrow();
            if st.cursor.has_selection() {
                let _ = st.cursor.remove_selected_text();
            }
        }
        sync_cursor_signals(&self.state);
    }

    // --- Reactive signal accessors -----------------------------------------

    /// Bumps on every format-only document event (bold / italic /
    /// heading / alignment / list-style changes). See
    /// [`RichTextEditor::format_version`].
    pub fn format_version(&self) -> Signal<u64> {
        self.state.borrow().format_version.clone()
    }

    /// The **live** caret offset — reads `cursor.position()` directly, unbatched. Unlike
    /// [`cursor_position_signal`](Self::cursor_position_signal), whose stored value lags one frame
    /// behind a just-typed printable character (the insert is deferred to the frame loop and the
    /// signal is only re-synced on the *next* caret event), this always reflects the true caret —
    /// what a host that recomputes highlights on a frame tick must read. Mirrors
    /// [`RichTextEditor::cursor_position`].
    pub fn cursor_position(&self) -> usize {
        self.state.borrow().cursor.position()
    }

    /// `true` while an IME composition is actively in progress. Mirrors
    /// [`RichTextEditor::is_composing`].
    pub fn is_composing(&self) -> bool {
        self.state.borrow().ime_preedit.is_some()
    }

    /// Reactive caret position signal.
    pub fn cursor_position_signal(&self) -> Signal<usize> {
        self.state.borrow().cursor_position.clone()
    }

    /// Reactive selection anchor signal.
    pub fn cursor_anchor_signal(&self) -> Signal<usize> {
        self.state.borrow().cursor_anchor.clone()
    }

    /// Reactive selection-non-empty signal.
    pub fn has_selection(&self) -> Signal<bool> {
        self.state.borrow().has_selection.clone()
    }

    /// Reactive undo-availability signal (toolbar enable-state source).
    pub fn can_undo(&self) -> Signal<bool> {
        self.state.borrow().can_undo.clone()
    }

    /// Reactive redo-availability signal.
    pub fn can_redo(&self) -> Signal<bool> {
        self.state.borrow().can_redo.clone()
    }
}

/// Private leaf body for [`RichTextEditor`].
///
/// Pure rendering surface: layout (intrinsic / greedy via
/// `min_lines` / `max_lines`), `place_children` (records the
/// viewport on `state`), `paint` (glyph runs, caret, selection),
/// `accessibility` (Role::MultilineTextInput / Role::Document plus
/// the flow-snapshot walk, whose text-run children hang directly off
/// this node except under a table, blockquote or heading).
///
/// Handlers, focus, the context-menu factory, and per-frame ticking
/// all live on the composing outer [`RichTextEditor`]; the body
/// itself is non-focusable and has no event handlers. It is still the
/// node that stands for the editor in the accessibility tree
/// (`accessibility_proxy`), so focus on the editor is published here,
/// where the text and the caret are. The shared
/// `state` is what links them — both widgets hold an `Rc` to the
/// same [`EditorState`], so a key event on the wrapper mutates the
/// state and the body re-paints on the next frame.
pub(crate) struct RichTextEditorBody {
    state: SharedState,
    min_lines: Option<u32>,
    max_lines: Option<u32>,
}

impl std::fmt::Debug for RichTextEditorBody {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("RichTextEditorBody")
            .field("policy", &self.state.borrow().policy)
            .finish_non_exhaustive()
    }
}

impl Widget for RichTextEditor {
    fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
        // Tell the framework this widget edits text.
        //
        // What it buys: an application running Undo or Copy from a menu or a
        // toolbar — an intent whose walk never passes through this widget —
        // can tell that the caret is *here*, and drive this surface rather
        // than its own history. Without it, such an application silently
        // breaks every text widget it does not personally know about. See
        // `teksilo_core::text_surface`.
        ctx.register_text_surface(std::rc::Rc::new(self.handle()));
        // Engine swap: replace the private fallback with one sharing
        // the application's `SharedTypesetter` so rendered glyphs end
        // up in the atlas teksilo-render uploads to the GPU. Headless
        // tests without a `SharedTypesetter` keep the private engine
        // untouched. Lives on the wrapper because state mutation
        // doesn't depend on `ctx.self_id()`.
        if let Some(shared) = ctx.app_state::<SharedTypesetter>() {
            let mut st = self.state.borrow_mut();
            let wrap = st.wrap_mode;
            // Carry over builder-set engine config that the swap would otherwise
            // drop — `.typography_defaults()`, `.echo_char()` are set on the
            // private engine before mount, and this runs on every rebuild.
            // (Theme colours / font-scale re-derive themselves in `paint()`.)
            let typography = st.engine.typography_defaults().clone();
            let echo = st.engine.echo_char();
            let mut engine = RichTextEngine::from_shared(shared.clone());
            engine.set_wrap_mode(wrap);
            engine.set_hyphenate_justified(true);
            engine.set_typography_defaults(typography);
            engine.set_echo_char(echo);
            st.engine = engine;
            st.needs_full_layout = true;
        }

        // Stash the tree's frame-request handle on the state so the
        // frame-tick effect can self-chain (caret blink, drag
        // auto-scroll) without mutable access to the tree.
        {
            let mut st = self.state.borrow_mut();
            st.frame_request = Some(ctx.frame_request_handle());
            st.frame_wake_at = Some(ctx.wake_at_handle());
            // Remember this build's wrapper id — the `.focusable(true)` node — so a
            // held handle can request focus back onto the editor.
            st.self_id = Some(ctx.self_id());
            // The density ladder the pointer geometry reads. A snapshot, not a
            // per-event read: `EventContext` exposes no theme, and
            // `set_input_density` marks at `BindingLevel::Rebuild`, so this
            // refreshes with the density.
            st.input_tokens = ctx.theme().input;
        }

        // Kick off the first frame so the initial layout/paint runs
        // through the tick path and populates max_scroll / content
        // metrics. Gated by activation: a tab content pane parked in a
        // non-selected `Switcher` branch must not keep the event loop
        // awake just because it was built (TabWidget pre-mounts every
        // open tab).
        let activation = ctx.activation_signal(ctx.self_id());
        // Stash it too: `reveal_range` has no other way to tell an on-screen
        // editor from one parked dormant, because the engine's layout survives
        // the parking. Taken from the signal rather than set by the dormancy
        // effect below, which fires only on a *transition* — an editor built
        // dormant (a TabWidget pre-mounts every open tab) never transitions.
        self.state.borrow_mut().activation = Some(activation.clone());
        if activation.get() {
            ctx.request_frame();
        }

        // When this editor is parked dormant (tab switch, collapsed
        // pane, …) clear local focus state synchronously. The tree may
        // also dispatch FocusLost via revalidate, but a race between
        // selection change and pointer focus — or a programmatic
        // selection change that never moves focus — used to leave
        // `has_focus = true` on every visited tab. Each stuck editor
        // kept scheduling caret `wake_at`s, and every open tab's
        // frame-tick effect still ran on those wakes (observers are
        // not dormancy-gated). Rapid tab switching made CPU climb.
        {
            let state = self.state.clone();
            ctx.effect(&activation, move |&active| {
                if active {
                    // **Re-activated** — re-arm the frame loop.
                    //
                    // The dormant branch below deliberately does not re-arm
                    // `frame_request`, and the frame-tick effect is skipped
                    // entirely while dormant, so nothing restarts the tick on the
                    // way back: the editor paints once and then goes quiet. The
                    // caret is what makes that visible — `on_focus` restarts the
                    // blink, but only the tick pushes the cursor through to the
                    // engine, so a re-activated editor that is then focused shows
                    // **no caret at all** and reads as a broken surface.
                    //
                    // The in-tree modal path hits this on every open: it builds
                    // the content, marks it dormant, mounts it, activates it and
                    // *then* moves focus in (`present_in_tree_modal_request`). A
                    // tab switch and a collapsed pane take the same route back.
                    //
                    // Cheap and self-limiting: one frame request, after which the
                    // ordinary tick loop re-arms itself only while it has work.
                    let st = state.borrow();
                    if let Some(handle) = &st.frame_request {
                        handle.set(true);
                    }
                    return;
                }
                let mut st = state.borrow_mut();
                if st.has_focus {
                    st.has_focus = false;
                    st.focus_signal.set(false);
                }
                if st.caret_visible.get() {
                    st.caret_visible.set(false);
                }
                st.blink.reset();
                // Retire the caret band here too. Only `frame_loop::tick` pushes the band's
                // focus state through to the document, and the tick effect below is skipped
                // entirely while dormant — so a parked editor would keep its last band
                // registered on a document its siblings are still showing, and a split pane
                // over the same document would show two. Clearing `has_focus` above is not
                // enough; nothing would ever act on it.
                if let Some(band) = &st.caret_highlight {
                    band.set_active(false);
                }
                st.caret_highlight_active = false;
                // Do not re-arm frame_request here: a dormant editor has
                // nothing to paint, and re-arming is exactly the leak
                // this gate exists to stop.
            });
        }

        // Frame-tick effect — drains document events, blinks the
        // caret, runs drag auto-scroll. Re-arms the tree's
        // frame-request flag while there's still pending work.
        // Skipped entirely while dormant so a multi-tab TabWidget does
        // not pay O(open tabs) per wake for editors nobody can see.
        {
            let state = self.state.clone();
            let active = activation.clone();
            let tick_signal = ctx.frame_tick();
            ctx.effect(&tick_signal, move |delta| {
                if !active.get() {
                    return;
                }
                let mut st = state.borrow_mut();
                let more = frame_loop::tick(&mut st, *delta);
                // Signal::set is unconditional (clones+invokes every
                // observer even when value unchanged), so only call it
                // when the bool actually flipped. Avoids per-tick fanout
                // to chrome widgets that watch the selection state.
                let new_has_selection = st.cursor.has_selection();
                if st.has_selection.get() != new_has_selection {
                    st.has_selection.set(new_has_selection);
                }
                if more && let Some(handle) = &st.frame_request {
                    handle.set(true);
                }
                drop(st);
            });
        }

        // Window-active effect — mirror the tree's window-active state onto the
        // editor state so the frame loop (which has no context) can gate the
        // caret. The frame loop may not tick while the window is inactive (the
        // animation scheduler is parked), so on deactivation we hide the caret
        // *synchronously* here rather than waiting for a tick, and request a
        // frame so the change reaches a paint pass — but only while this
        // editor is itself active. A dormant tab must not re-arm the frame
        // loop just because the host window blinked.
        {
            let state = self.state.clone();
            let active = activation.clone();
            let wa_signal = ctx.window_active_signal();
            ctx.effect(&wa_signal, move |&window_active| {
                let mut st = state.borrow_mut();
                st.window_active = window_active;
                if window_active {
                    // Reactivated: if the editor still holds focus, show the
                    // caret immediately (restart the blink phase) rather than
                    // waiting up to one blink interval. `Hidden` policy stays
                    // hidden — the paint gate suppresses it anyway.
                    let show =
                        st.has_focus && !matches!(st.policy.caret_policy, CaretPolicy::Hidden);
                    if show && !st.caret_visible.get() {
                        st.caret_visible.set(true);
                    }
                    st.blink.reset();
                } else {
                    // Deactivated: hide the caret synchronously (the frame loop
                    // may not tick while the window is inactive).
                    if st.caret_visible.get() {
                        st.caret_visible.set(false);
                    }
                    st.blink.reset();
                }
                if active.get()
                    && let Some(handle) = &st.frame_request
                {
                    handle.set(true);
                }
                drop(st);
            });
        }

        // Attach handlers on the WRAPPER — making the composing
        // widget itself the focus + event target. The body is a
        // pure leaf so users can wrap it in arbitrary chrome via
        // `RichTextEditorStyle::make_body` without losing focus
        // semantics.
        let mut handlers = HandlerSet::new();
        // Editable editors are text-input surfaces — enable the OS IME
        // while focused. Read-only viewers stay focusable for selection but
        // accept no text input, so they leave the IME descriptor unset.
        if !self.state.borrow().policy.is_read_only() {
            handlers = handlers.ime_input(teksilo_core::ime::ImeContext::text());
        }
        handlers = handlers
            // Text and files dropped onto the editor land at the caret, and the
            // caret follows the drag so the writer can see where that is. An
            // editor with no drop handling at all is not merely inert: the drag
            // bubbles to whatever ancestor claims it, and the pane's own
            // `DropTarget` paints a reject tint across the whole surface, which
            // reads as the editor refusing the drop rather than never being
            // offered it.
            .on_drag_hover({
                let state = self.state.clone();
                move |payload, pos, ctx| {
                    // Read the policy live rather than snapshotting it here: the
                    // command filter is swappable on a mounted editor
                    // (`set_command_filter`), and a value captured at build time
                    // would keep promising a drop the drop handler then refuses.
                    let read_only = state.borrow().policy.is_read_only();
                    if read_only || !droppable(payload) {
                        // `NoFeedback` rather than a reject visual: the drag
                        // must keep bubbling so an ancestor that does want this
                        // payload — a binder row dropped on the editor pane —
                        // still gets it.
                        return teksilo_core::DropFeedback::NoFeedback;
                    }
                    // A drop this editor refuses gets no caret promising where
                    // it would land, and the selection it carries stays put.
                    if payload
                        .get_typed::<EditorTextDrag>()
                        .is_some_and(|drag| self::mouse::refuses_text_drop(&state, drag))
                    {
                        self::mouse::clear_drop_caret(&state);
                        return teksilo_core::DropFeedback::NoFeedback;
                    }
                    if !self::mouse::move_caret_for_drag(&state, pos) {
                        self::mouse::clear_drop_caret(&state);
                        return teksilo_core::DropFeedback::NoFeedback;
                    }
                    ctx.request_frame();
                    // The caret IS the feedback — a framework insertion line
                    // would draw a second, differently-placed promise about
                    // where the drop lands.
                    teksilo_core::DropFeedback::Accept
                }
            })
            // The drag moved off this editor (or was cancelled over it): stop
            // promising a landing place. Without this the drop caret is left
            // burnt into an editor the drag has already left.
            .on_drag_leave({
                let state = self.state.clone();
                move |ctx| {
                    self::mouse::clear_drop_caret(&state);
                    ctx.request_frame();
                }
            })
            .on_drop({
                let state = self.state.clone();
                move |payload, pos, ctx| {
                    self::mouse::clear_drop_caret(&state);
                    // Live, for the same reason as `on_drag_hover` above.
                    let read_only = state.borrow().policy.is_read_only();
                    if read_only || !droppable(&payload) {
                        return false;
                    }
                    // Refused before the caret is placed below, which would
                    // collapse the selection the drag carries.
                    if payload
                        .get_typed::<EditorTextDrag>()
                        .is_some_and(|drag| self::mouse::refuses_text_drop(&state, drag))
                    {
                        return false;
                    }
                    // Place the caret one last time: a drop can arrive without a
                    // final hover at the same point (a fast release, or a
                    // backend that only fills the payload at drop time).
                    self::mouse::move_caret_for_drag(&state, pos);
                    // Text dragged out of an editor. Dropped back into the one
                    // it came from it is a *move* — the original goes away —
                    // and dropped into any other editor it is a copy, which is
                    // what a writer means by carrying a phrase to a second
                    // document rather than emptying it out of the first.
                    if let Some(drag) = payload.get_typed::<EditorTextDrag>() {
                        let same_editor = state.borrow().self_id == Some(drag.source);
                        let moved = self::mouse::apply_text_drop(&state, drag, same_editor);
                        if moved {
                            sync_cursor_signals(&state);
                            state.borrow_mut().pending_text_changed = true;
                            // Take the caret with the text. Focus is still in
                            // the editor the drag *started* in, so without this
                            // the writer is left looking at text they just
                            // placed here while typing into somewhere else.
                            let self_id = state.borrow().self_id;
                            if let Some(id) = self_id {
                                ctx.request_focus(id);
                            }
                            ctx.request_frame();
                        }
                        return moved;
                    }
                    let files: Vec<std::path::PathBuf> = payload.files().to_vec();
                    if !files.is_empty() {
                        // Files mean nothing to a text editor on their own —
                        // whether a path becomes a picture, a link, or an
                        // include is the host's policy. Hand them over.
                        let cb = state.borrow().on_files_dropped.clone();
                        let Some(cb) = cb else { return false };
                        cb(&files, ctx);
                        ctx.request_frame();
                        return true;
                    }
                    // Advertised but delivered nothing: decline, so the drag
                    // bubbles rather than being silently eaten.
                    let Some(text) = payload.text().filter(|t| !t.is_empty()) else {
                        return false;
                    };
                    {
                        let st = state.borrow();
                        let _ = st.cursor.insert_text(text);
                    }
                    sync_cursor_signals(&state);
                    state.borrow_mut().pending_text_changed = true;
                    ctx.request_frame();
                    true
                }
            })
            .focusable(true)
            .cursor(CursorIcon::Text)
            .on_focus({
                let state = self.state.clone();
                let touch = self.touch.clone();
                move |gained, ctx| {
                    let mut st = state.borrow_mut();
                    st.has_focus = gained;
                    // Mirror onto the reactive signal so chrome
                    // installed by `RichTextEditorStyle::make_body`
                    // (focus-aware border / ring) re-renders.
                    st.focus_signal.set(gained);
                    if gained && matches!(st.policy.caret_policy, CaretPolicy::Blinking) {
                        st.blink.restart();
                        st.caret_visible.set(true);
                    }
                    drop(st);
                    if gained {
                        // Seed the OS IME candidate area at the caret.
                        self::keyboard::report_ime_cursor_area(&state, ctx);
                    } else {
                        // Abandon any in-progress composition on blur, and drop
                        // the IME-area / caret-chase caches. The OS IME candidate
                        // area is a single *per-window* resource a sibling field
                        // may have re-pointed while we were unfocused; clearing
                        // `last_ime_area` forces the next focus-gain report to
                        // re-seed it (the dedup must not swallow that re-seed).
                        // Clearing `last_chase_pos` lets a refocus re-reveal the
                        // caret even if it has not moved since we lost focus.
                        // The affordance band is exempt from outside-press
                        // dismissal — every caret-moving tap is outside a
                        // handle — so retirement on focus loss is the host's.
                        touch.dismiss();
                        self::keyboard::clear_ime_preedit(&state);
                        let mut st = state.borrow_mut();
                        st.last_ime_area = None;
                        st.last_chase_pos = None;
                    }
                    ctx.request_frame();
                }
            })
            .on_pointer_event({
                let state = self.state.clone();
                let touch = self.touch.clone();
                let v_sb = self.v_scrollbar_bounds.clone();
                let h_sb = self.h_scrollbar_bounds.clone();
                move |event, ctx| {
                    self::mouse::handle_pointer_event(&state, &touch, &v_sb, &h_sb, event, ctx)
                }
            })
            // A hold selects the word under the finger. Attaching this
            // **withdraws** the tree-owned long-press route (`touch_route`
            // rule 1: a widget's own `on_long_press` wins), which is what used
            // to open this editor's context menu for a coarse pointer — the
            // selection toolbar the mount raises is its replacement, and offers
            // the same commands from the same rows.
            .on_long_press({
                let state = self.state.clone();
                let touch = self.touch.clone();
                move |event, ctx| {
                    self::mouse::handle_long_press(&state, &touch, event, ctx);
                }
            })
            .on_key({
                let state = self.state.clone();
                let touch = self.touch.clone();
                move |event, ctx| {
                    let response = self::keyboard::handle_key(&state, event, ctx);
                    // A keystroke moves the caret and edits the text, neither of
                    // which the controller made — so the handles it published
                    // are pointing at where the text used to be. `refresh` is a
                    // no-op until something has been raised.
                    touch.refresh(ctx, touch_mount::ToolbarIntent::Hide);
                    response
                }
            })
            .on_double_tap({
                let state = self.state.clone();
                let touch = self.touch.clone();
                move |event, ctx| {
                    self::mouse::handle_double_tap(&state, event.position, ctx);
                    // A finger can double-tap too, and the selection it just
                    // made is one the controller did not make.
                    if event.pointer.kind.is_direct() {
                        touch.raise(ctx, touch_mount::ToolbarIntent::Show);
                    }
                }
            })
            .on_triple_tap({
                let state = self.state.clone();
                let touch = self.touch.clone();
                move |event, ctx| {
                    self::mouse::handle_triple_tap(&state, event.position, ctx);
                    if event.pointer.kind.is_direct() {
                        touch.raise(ctx, touch_mount::ToolbarIntent::Show);
                    }
                }
            })
            .on_access_action_request({
                let state = self.state.clone();
                let touch = self.touch.clone();
                move |action, target_node, data, ctx| {
                    let response =
                        handle_access_action_request(&state, action, target_node, data, ctx);
                    // An assistive client's `SetTextSelection` / `SetValue` /
                    // `ReplaceSelectedText` moves the selection without going
                    // through the controller, so raised handles would be left
                    // marking the old range.
                    touch.refresh(ctx, touch_mount::ToolbarIntent::Keep);
                    response
                }
            });

        // Context-menu factory — same shape as before, just hosted on
        // the wrapper. The factory reads the policy from the shared state on
        // each right-click, so a filter swapped in after mount is honoured.
        if let Some(factory) = context_menu::resolve_factory(
            self.custom_context_menu.take(),
            self.default_context_menu_enabled,
            self.state.clone(),
        ) {
            handlers = handlers.context_menu(move |pos, ctx| factory(pos, ctx));
        }

        // Scroll: the wheel path this surface always had, a finger's pan, and
        // the claim that puts it on a pan's claimant chain — all from
        // `common::text_scroll`, which the three text surfaces share.
        {
            let (x, max_x, y, max_y, scroller) = {
                let st = self.state.borrow();
                (
                    st.scroll_x.clone(),
                    st.max_scroll_x.clone(),
                    st.scroll_y.clone(),
                    st.max_scroll_y.clone(),
                    st.scroller.clone(),
                )
            };
            let behavior = crate::common::text_scroll::text_surface_behavior(
                crate::common::text_scroll::TextScrollState {
                    x,
                    max_x,
                    y,
                    max_y,
                    scroller,
                },
                self.overscroll_behavior,
                ctx.prefers_reduced_motion(),
                ctx.theme().input.scroll_physics,
            );
            handlers = behavior.install(handlers);
        }

        ctx.apply_self_handlers(handlers);

        // Select-all, the clipboard and undo / redo come through the
        // rebindable `edit.*` shortcuts, not as keys.
        {
            let state = self.state.clone();
            let touch = self.touch.clone();
            let surfaces = ctx.text_surfaces();
            crate::common::standard_edit::register_standard_edit_actions(
                ctx,
                move |command, ctx| {
                    let ran = self::keyboard::run_standard_edit(
                        &state,
                        command,
                        surfaces.empty_history_passes_on(),
                        ctx,
                    );
                    if ran {
                        // As after a key: the published handles point at
                        // where the text used to be.
                        touch.refresh(ctx, touch_mount::ToolbarIntent::Hide);
                    }
                    ran
                },
            );
        }

        // Bold, italic, underline and the forced paragraph insert: shared
        // `format.*` shortcuts, declared while an editable editor exists, and
        // an action per command here.
        if !self.state.borrow().policy.is_read_only() {
            for command in crate::editor_shortcuts::FormatShortcut::ALL {
                ctx.register_shortcut_shared(command.shortcut());
            }
        }
        for command in crate::editor_shortcuts::FormatShortcut::ALL {
            let state = self.state.clone();
            let touch = self.touch.clone();
            crate::common::standard_edit::register_command_action(ctx, command.id(), move |ctx| {
                let ran = self::keyboard::run_format_shortcut(&state, command, ctx);
                if ran {
                    touch.refresh(ctx, touch_mount::ToolbarIntent::Hide);
                }
                ran
            });
        }

        // The touch-selection overlays: the affordance layer (handles + lens)
        // and the selection toolbar, both detached content owned by this build.
        // Inert until a finger raises them.
        let self_id = ctx.self_id();
        self.touch.build(ctx, self_id);

        // Build the pure-paint leaf body. The body carries
        // layout/paint/accessibility (using its own `self_id()` for
        // `caret_visible` + `document_version` bindings); the shared
        // `state` propagates handler-driven mutations into it.
        let body = RichTextEditorBody {
            state: self.state.clone(),
            min_lines: self.min_lines,
            max_lines: self.max_lines,
        };
        // The name goes on the body, the node focus is published on; see
        // [`label`](Self::label). `LocalizedString -> Prop<String>` keeps it
        // locale-reactive.
        let viewport_id = match self.label.clone() {
            Some(label) => ctx.add(body.access_label(label)),
            None => ctx.add(body),
        };
        self.body_id = Some(viewport_id);

        // Reactive colour overrides: a signal/role-bound `ColorProp` must
        // repaint the body (the leaf that resolves + applies them in `paint`)
        // when it changes. Bind to `viewport_id`, not the wrapper — the painter
        // owns its prop bindings (the `RectWidget` pattern). Theme-role changes
        // already dirty every node via the reactive theme; this covers
        // `Signal`-bound props. The background prop is reactive through the
        // `RectWidget` the style builds, so it isn't registered here.
        {
            let props = {
                let st = self.state.borrow();
                [
                    st.text_color_prop.clone(),
                    st.caret_color_prop.clone(),
                    st.selection_color_prop.clone(),
                ]
            };
            let registry = ctx.binding_registry();
            for prop in props.iter().flatten() {
                prop.register_if_bound(
                    viewport_id,
                    registry,
                    teksilo_core::binding::BindingLevel::RepaintOnly,
                );
            }
        }

        // Snapshot focus + read-only state for the chrome. `is_focused`
        // is the reactive mirror updated by `on_focus`; `is_read_only`
        // is sampled from the policy bundle.
        let (is_focused, is_read_only) = {
            let st = self.state.borrow();
            (st.focus_signal.clone(), st.policy.is_read_only())
        };

        let style: SharedRichTextEditorStyle = self
            .style_override
            .clone()
            .or_else(|| ctx.theme().style_slots.rich_text_editor.clone())
            .unwrap_or_else(|| Rc::new(RecipeRichTextEditorStyle));
        let cfg = RichTextEditorStyleConfig {
            viewport: viewport_id,
            is_focused,
            is_read_only,
            content_padding: self.content_padding,
            background: self.state.borrow().background_prop.clone(),
        };
        let root = style.make_body(&cfg, ctx);
        self.root_child_id = Some(root);

        // Overlay scrollbars — floated on top of the chrome at the
        // right / bottom edges. Driven by the same signals the frame
        // loop publishes (`scroll_*`, `max_scroll_*`, `viewport_ratio_*`).
        // ScrollPolicy::AlwaysOff suppresses the widget entirely so it
        // doesn't sit in the children list as a zero-sized stub.
        let (scroll_x, scroll_y, max_scroll_x, max_scroll_y, vr_x, vr_y) = {
            let st = self.state.borrow();
            (
                st.scroll_x.clone(),
                st.scroll_y.clone(),
                st.max_scroll_x.clone(),
                st.max_scroll_y.clone(),
                st.viewport_ratio_x.clone(),
                st.viewport_ratio_y.clone(),
            )
        };

        let mut children = vec![root];
        if self.v_scroll_policy != ScrollPolicy::AlwaysOff {
            let v_sb = ScrollBar::new(
                ScrollBarOrientation::Vertical,
                scroll_y,
                max_scroll_y.clone(),
                vr_y,
            )
            .visual(ScrollBarVariant::Overlay);
            let v_id = ctx.add(v_sb);
            self.v_scrollbar_id = Some(v_id);
            children.push(v_id);
        }
        if self.h_scroll_policy != ScrollPolicy::AlwaysOff {
            let h_sb = ScrollBar::new(
                ScrollBarOrientation::Horizontal,
                scroll_x,
                max_scroll_x.clone(),
                vr_x,
            )
            .visual(ScrollBarVariant::Overlay);
            let h_id = ctx.add(h_sb);
            self.h_scrollbar_id = Some(h_id);
            children.push(h_id);
        }

        // `place_children` reads `max_scroll_y` / `max_scroll_x`
        // synchronously to decide whether to give the overlay
        // scrollbars a non-zero rect under `ScrollPolicy::Auto`. The
        // frame loop publishes those values from `Step 7` on every
        // tick — without a Relayout binding the wrapper wouldn't
        // re-place its children when the values cross zero, so the
        // bars would stay sized 0×0 until something else (scroll
        // wheel, resize) forced a layout pass.
        let self_id = ctx.self_id();
        let registry = ctx.binding_registry();
        max_scroll_y.bind_to(
            self_id,
            registry,
            teksilo_core::binding::BindingLevel::Relayout,
        );
        max_scroll_x.bind_to(
            self_id,
            registry,
            teksilo_core::binding::BindingLevel::Relayout,
        );

        children
    }

    fn layout_response(
        &self,
        proposal: SizeProposal,
        ctx: &LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        self.root_child_id
            .and_then(|id| ctx.child_size(id, proposal))
            .unwrap_or_else(|| proposal.resolve(0.0, 0.0))
            .into()
    }

    fn place_children(
        &self,
        bounds: Rect,
        _proposal: SizeProposal,
        children: &mut [WidgetPlacement],
        _ctx: &LayoutContext,
    ) {
        // Chrome (first child) fills the entire bounds. Overlay
        // scrollbars float on top at the right (vertical) and
        // bottom (horizontal) edges — collapsed to zero when the
        // axis policy is `Auto` and there's nothing to scroll.
        let sb_thickness = self::frame_loop::SCROLLBAR_THICKNESS;
        {
            // Record the wrapper node's window-space origin so the pointer
            // handlers can reconstruct window coords from the now
            // wrapper-node-local positions (see `State::node_origin`).
            let mut st = self.state.borrow_mut();
            st.node_origin = teksilo_canvas::Point::new(bounds.x, bounds.y);
        }
        let st = self.state.borrow();
        let max_y = st.max_scroll_y.get();
        let max_x = st.max_scroll_x.get();
        drop(st);
        let show_v = match self.v_scroll_policy {
            ScrollPolicy::AlwaysOn => true,
            ScrollPolicy::Auto => max_y > 0.0,
            ScrollPolicy::AlwaysOff => false,
        };
        let show_h = match self.h_scroll_policy {
            ScrollPolicy::AlwaysOn => true,
            ScrollPolicy::Auto => max_x > 0.0,
            ScrollPolicy::AlwaysOff => false,
        };
        let mut v_rect = Rect::ZERO;
        let mut h_rect = Rect::ZERO;
        for (idx, child) in children.iter_mut().enumerate() {
            if idx == 0 {
                child.origin = teksilo_canvas::Point::new(bounds.x, bounds.y);
                child.size = Size::new(bounds.width, bounds.height);
            } else if Some(child.id) == self.v_scrollbar_id {
                if show_v {
                    let h = if show_h {
                        (bounds.height - sb_thickness).max(0.0)
                    } else {
                        bounds.height
                    };
                    child.origin = teksilo_canvas::Point::new(
                        bounds.x + bounds.width - sb_thickness,
                        bounds.y,
                    );
                    child.size = Size::new(sb_thickness, h);
                    // Widget-local: pointer events arrive widget-local, so
                    // the published bounds the press-bypass test compares
                    // against must be local too (subtract the widget origin).
                    v_rect = Rect::new(
                        child.origin.x - bounds.x,
                        child.origin.y - bounds.y,
                        sb_thickness,
                        h,
                    );
                } else {
                    child.origin = teksilo_canvas::Point::new(bounds.x, bounds.y);
                    child.size = Size::ZERO;
                }
            } else if Some(child.id) == self.h_scrollbar_id {
                if show_h {
                    let w = if show_v {
                        (bounds.width - sb_thickness).max(0.0)
                    } else {
                        bounds.width
                    };
                    child.origin = teksilo_canvas::Point::new(
                        bounds.x,
                        bounds.y + bounds.height - sb_thickness,
                    );
                    child.size = Size::new(w, sb_thickness);
                    // Widget-local (see the v_scrollbar branch).
                    h_rect = Rect::new(
                        child.origin.x - bounds.x,
                        child.origin.y - bounds.y,
                        w,
                        sb_thickness,
                    );
                } else {
                    child.origin = teksilo_canvas::Point::new(bounds.x, bounds.y);
                    child.size = Size::ZERO;
                }
            }
        }
        // Published to the wrapper's `on_pointer_event` so a press over
        // an overlay scrollbar bypasses the drag-select latch — see
        // [`v_scrollbar_bounds`](Self::v_scrollbar_bounds).
        self.v_scrollbar_bounds.set(v_rect);
        self.h_scrollbar_bounds.set(h_rect);
    }

    fn children(&self) -> Vec<WidgetId> {
        let mut ids = Vec::with_capacity(3);
        if let Some(id) = self.root_child_id {
            ids.push(id);
        }
        if let Some(id) = self.v_scrollbar_id {
            ids.push(id);
        }
        if let Some(id) = self.h_scrollbar_id {
            ids.push(id);
        }
        ids
    }

    fn clips_children(&self) -> bool {
        // Mirror the body's clipping so chrome around the editor
        // doesn't leak the body's overflow.
        true
    }

    fn focus_reveal_rect(&self, _bounds: Rect) -> Option<Rect> {
        // On focus gain the framework reveals the focused widget into any
        // enclosing ScrollArea. Reveal the caret *line*, not the (potentially
        // page-tall, own-scroll-suppressed) whole editor: a click that only
        // placed the caret near the top must not jump the page to the editor's
        // bottom. Returns the exact absolute caret rect the in-page caret-follow
        // uses (viewport_origin + caret − scroll); `scroll_rect_into_view`
        // excludes the editor itself, so this targets the enclosing ScrollArea
        // with no double-scroll. `None` (→ reveal whole bounds) before the first
        // layout or while unfocused.
        self::keyboard::caret_window_rect(&self.state.borrow())
    }

    fn accessibility(&self, builder: &mut AccessNodeBuilder) {
        // Transparent container in the AT tree — the inner
        // `RichTextEditorBody` carries the real role
        // (`MultilineTextInput` / `Document`) plus the paragraph and
        // text-run children. Without this method the wrapper would
        // emit a `Role::Unknown` node (the `AccessNodeBuilder`
        // default), which screen readers can't classify.
        builder.set_role(teksilo_core::accesskit::Role::GenericContainer);
    }

    fn accessibility_proxy(&self) -> Option<WidgetId> {
        // The body stands for the editor: this widget takes the keys, and the
        // body holds the text, so focus, a name and anything an application
        // attaches here are published on the body.
        self.body_id
    }
}

// ---------------------------------------------------------------------------
// Event handlers — take `&SharedState` so they can be boxed into handler
// closures without borrowing `self`.
// ---------------------------------------------------------------------------

/// Shared body of [`RichTextEditor::reveal_range`] and its
/// [`EditorHandle`] twin — one implementation so the two can never drift on the
/// typewriter-pin rule.
///
/// The pin applies here even though the range is not the caret: with typewriter
/// scrolling on, walking search hits should bring each one to the same height
/// the writer works at. Unlike the caret chase, a pointer anchor does *not*
/// suppress it — the user asked for this jump explicitly by pressing Find Next,
/// so there is no gesture to fight.
fn reveal_range_impl(
    state: &SharedState,
    ctx: &mut teksilo_core::widget::EventContext,
    start: usize,
    end: usize,
) -> bool {
    // **Named as the rect's owner**, so the scroll walk climbs the *editor's*
    // ancestors and not the handler's. The two are the same widget when the editor
    // reveals its own caret, and different every time something built beside it asks
    // — a find banner's Next button, a mention counter's chevron. Those sit outside
    // the scrolling page, so a walk from them leaves through the strip and never
    // meets the scroll container: the match was selected, the counter moved, and the
    // viewport stayed exactly where it was. `self_id` is `None` only before the
    // editor's first build, and there is nothing laid out to reveal then anyway.
    let (area, pin, owner) = {
        let st = state.borrow();
        // **Dormant is "no layout to do it in"**, even though the engine still holds
        // one: `has_full_layout` is set at the first full layout and never cleared, and
        // parking an editor clears its focus, caret and band but not its layout. So the
        // rect below resolves perfectly for a tab nobody can see, the ancestor walk
        // finds a scroll container that is not on screen, and the answer `true` tells a
        // caller holding several editors over one document to stop looking — while the
        // visible one, never asked, stays exactly where it was.
        if st.activation.as_ref().is_some_and(|a| !a.get()) {
            return false;
        }
        match self::keyboard::range_window_rect(&st, start, end) {
            Some(a) => (a, st.typewriter, st.self_id),
            None => return false,
        }
    };
    match (pin, owner) {
        (Some(fraction), Some(owner)) => ctx.ensure_visible_aligned_from(
            owner,
            area,
            fraction,
            teksilo_core::event::ScrollMotion::Smooth,
        ),
        (Some(fraction), None) => {
            ctx.ensure_visible_aligned(area, fraction, teksilo_core::event::ScrollMotion::Smooth)
        }
        (None, Some(owner)) => ctx.ensure_visible_from(owner, area),
        (None, None) => ctx.ensure_visible(area),
    }
    true
}

/// Set (or clear) an editor's ambient caret band. Shared by
/// [`RichTextEditor::set_caret_highlight`] and its [`EditorHandle`] mirror.
///
/// The session is created on first use and torn down when the band is cleared, so an editor
/// that never asks for one registers nothing on the document at all — which matters, since
/// every read-only preview pane shares the documents the writing panes are editing.
fn set_caret_highlight(state: &SharedState, highlight: Option<caret_highlight::CaretHighlight>) {
    let mut st = state.borrow_mut();
    match (&st.caret_highlight, &highlight) {
        (None, None) => return,
        (None, Some(_)) => {
            let session = caret_highlight::CaretHighlightSession::new(&st.document);
            session.set_config(highlight);
            // The frame loop hands it the focus state and the caret on the next tick, so a band
            // switched on mid-session appears without the editor having to be touched.
            let active = st.has_focus && !st.cursor.has_selection();
            session.set_active(active);
            st.caret_highlight_active = active;
            st.caret_highlight = Some(session);
        }
        (Some(_), None) => {
            // Dropping the session retires its highlight layer.
            st.caret_highlight = None;
            st.caret_highlight_active = false;
        }
        (Some(session), Some(_)) => {
            session.set_config(highlight);
        }
    }
    // A band that appeared, vanished or changed colour needs a frame to draw it — and the
    // resolve-and-push itself only happens in `frame_loop::tick`, so without waking the tree an
    // idle editor stays configured-but-unbanded until some unrelated interaction pumps a frame.
    // Same poke `set_typography_defaults` / `set_font_size_scale` make, for the same reason:
    // these are the ctx-less setters a host calls from a settings or theme effect.
    st.content_dirty = true;
    if let Some(handle) = &st.frame_request {
        handle.set(true);
    }
}

/// Push the current cursor position / anchor / selection flag into
/// the state's reactive signals. Called after every cursor mutation
/// so external observers (status bars, tests) see the change on the
/// next signal propagation. Exported to `keyboard` and `mouse`
/// because every event handler ends with a signal publish.
pub(super) fn sync_cursor_signals(state: &SharedState) {
    let mut st = state.borrow_mut();
    let pos = st.cursor.position();
    let anc = st.cursor.anchor();
    let has_sel = st.cursor.has_selection();
    let pos_sig = st.cursor_position.clone();
    let anc_sig = st.cursor_anchor.clone();
    let sel_sig = st.has_selection.clone();
    let caret_vis_sig = st.caret_visible.clone();
    // Restart the blink phase on every cursor mutation: a steady-visible
    // caret while typing or holding an arrow key, blinking only
    // resumes after the user stops moving. Mirrors focus-gain behavior
    // (see the `on_focus` handler around rich_text.rs:3854). The frame
    // loop only toggles once a full interval has elapsed since the phase
    // start, so restarting here delays the next toggle by a full interval.
    let blink_reset = st.has_focus && matches!(st.policy.caret_policy, CaretPolicy::Blinking);
    if blink_reset {
        st.blink.restart();
    }
    drop(st);
    pos_sig.set(pos);
    anc_sig.set(anc);
    sel_sig.set(has_sel);
    if blink_reset && !caret_vis_sig.get() {
        caret_vis_sig.set(true);
    }
}

/// Dispatch an AccessKit `ActionRequest` payload for the rich text
/// editor. Handles `SetTextSelection` (screen-reader-initiated
/// caret moves), `SetValue` (whole-document replacement),
/// `ReplaceSelectedText` (insert at the caret over the selection),
/// and `ScrollIntoView` (scroll so the caret is visible).
fn handle_access_action_request(
    state: &SharedState,
    action: teksilo_core::accesskit::Action,
    _target_node: teksilo_core::accesskit::NodeId,
    data: Option<teksilo_core::accesskit::ActionData>,
    ctx: &mut teksilo_core::widget::EventContext,
) -> teksilo_core::event::EventResponse {
    use self::policy::EditCommandKind;
    use teksilo_core::accesskit::{Action, ActionData};
    use teksilo_core::event::EventResponse;
    use teksilo_text::text_document::{MoveMode, SelectionType};

    match (action, data) {
        (Action::SetTextSelection, Some(ActionData::SetTextSelection(sel))) => {
            let filter = state.borrow().policy.command_filter;
            // Screen-reader-initiated caret moves are "navigation",
            // filtered under the same rule as arrow keys.
            if !filter.accepts(EditCommandKind::MoveLeft) {
                return EventResponse::Ignored;
            }
            let resolve = |pos: teksilo_core::accesskit::TextPosition| -> Option<usize> {
                let st = state.borrow();
                let map = st.synthetic_to_element.borrow();
                let er = map.get(&pos.node)?.clone();
                // Convert character_index (char units within the run)
                // to a byte offset within the run's text, then add
                // absolute_start to get the document position.
                let byte_off = er
                    .text
                    .char_indices()
                    .nth(pos.character_index)
                    .map(|(i, _)| i)
                    .unwrap_or(er.text.len());
                Some(er.absolute_start + byte_off)
            };
            if let (Some(a), Some(f)) = (resolve(sel.anchor), resolve(sel.focus)) {
                let st = state.borrow();
                st.cursor.set_position(a, MoveMode::MoveAnchor);
                st.cursor.set_position(f, MoveMode::KeepAnchor);
                drop(st);
                sync_cursor_signals(state);
                ctx.request_frame();
                EventResponse::Handled
            } else {
                EventResponse::Ignored
            }
        }
        (Action::SetValue, Some(ActionData::Value(value))) => {
            let filter = state.borrow().policy.command_filter;
            // `SetValue` swaps the *whole document* for the supplied string, so
            // accepting `InsertChar` is not enough on its own: under a
            // forward-only filter this is the single most destructive edit
            // available, however additive the incoming text looks. Dictation
            // that wants to add rather than replace arrives as
            // `ReplaceSelectedText` below.
            if !filter.accepts(EditCommandKind::InsertChar)
                || !filter.allows_wholesale_replacement()
            {
                return EventResponse::Ignored;
            }
            let st = state.borrow();
            st.cursor.select(SelectionType::Document);
            let _ = st.cursor.insert_text(value.as_ref());
            // For some people this **is** typing — dictation, a braille display —
            // and it is reported as itself rather than as `Keyboard` or as
            // nothing at all. A toolkit that folded it into typing would erase
            // how they work; one that reported nothing would leave anything
            // counting arrivals silently short for exactly those writers.
            st.report_inserted(EditSource::Accessibility, value.as_ref());
            drop(st);
            sync_cursor_signals(state);
            ctx.request_frame();
            EventResponse::Handled
        }
        (Action::ReplaceSelectedText, Some(ActionData::Value(value))) => {
            // Insert at the caret, replacing the active selection (if
            // any) — NOT the whole document like `SetValue`. The AT-SPI
            // (Linux) / UIA (Windows) braille-keyboard & dictation
            // insertion path; macOS routes insertion through `SetValue`.
            // We advertise the action in `accessibility()`, so service it.
            let filter = state.borrow().policy.command_filter;
            if !filter.accepts(EditCommandKind::InsertChar) {
                return EventResponse::Ignored;
            }
            let st = state.borrow();
            self::keyboard::collapse_selection_before_insert(&st);
            let _ = st.cursor.insert_text(value.as_ref());
            // The AT-SPI / UIA insertion path, which is how a braille keyboard
            // and most dictation write. Same reason as `SetValue` above.
            st.report_inserted(EditSource::Accessibility, value.as_ref());
            drop(st);
            sync_cursor_signals(state);
            ctx.request_frame();
            EventResponse::Handled
        }
        (Action::ScrollIntoView, _) => {
            let mut st = state.borrow_mut();
            if let Some(new_y) = st.engine.ensure_caret_visible() {
                st.scroll_y.set(new_y);
            }
            drop(st);
            ctx.request_frame();
            EventResponse::Handled
        }
        _ => EventResponse::Ignored,
    }
}

/// Convert an intra-fragment byte offset into a character index.
/// Convert an intra-fragment byte offset into a character index —
/// AccessKit's `TextPosition.character_index`, which indexes into the
/// target TextRun's `character_lengths`, i.e. one entry per Rust `char`.
///
/// (No caller remains since the a11y walk moved to `body/flow_walk.rs`;
/// deleting the function outright is the honest fix.)
fn char_index_in_text(text: &str, byte_offset: usize) -> usize {
    // Walk char_indices until we pass byte_offset; the count at
    // that point is the character index. Fall back to the char
    // count when byte_offset >= text.len().
    if byte_offset >= text.len() {
        return text.chars().count();
    }
    let mut count = 0usize;
    for (i, _) in text.char_indices() {
        if i >= byte_offset {
            return count;
        }
        count += 1;
    }
    count
}

// ── The framework's uniform view of a text-editing widget ────────────────────

impl teksilo_core::text_surface::TextSurface for EditorHandle {
    fn can_undo(&self) -> bool {
        EditorHandle::can_undo(self).get()
    }

    fn can_redo(&self) -> bool {
        EditorHandle::can_redo(self).get()
    }

    fn undo(&self) {
        EditorHandle::undo(self);
    }

    fn redo(&self) {
        EditorHandle::redo(self);
    }

    /// The editor's own [`CommandFilter`]
    /// is the authority: a host that has imposed `ForwardOnly` or `ReadOnly` on
    /// this editor must not be able to route around it from a menu.
    fn history_frozen(&self) -> bool {
        !self.command_filter().accepts(EditCommandKind::Undo)
    }

    fn has_selection(&self) -> bool {
        EditorHandle::has_selection(self).get()
    }

    fn is_read_only(&self) -> bool {
        !self.command_filter().accepts(EditCommandKind::InsertChar)
    }

    fn allows_copy(&self) -> bool {
        self.command_filter().accepts(EditCommandKind::Copy)
    }

    fn cut(&self, ctx: &teksilo_core::widget::EventContext<'_>) {
        EditorHandle::cut(self, ctx);
    }

    fn copy(&self, ctx: &teksilo_core::widget::EventContext<'_>) {
        EditorHandle::copy(self, ctx);
    }

    fn paste(&self, ctx: &teksilo_core::widget::EventContext<'_>) {
        EditorHandle::paste(self, ctx);
    }

    fn paste_plain(&self, ctx: &teksilo_core::widget::EventContext<'_>) {
        EditorHandle::paste_unformatted(self, ctx);
    }

    fn select_all(&self) {
        EditorHandle::select_all(self);
    }
}