quadraui 0.2.0

//! GTK rasteriser for the [`Editor`] primitive.
//!
//! Handles every editor paint category: backgrounds (active /
//! cursorline / DAP-stopped / diff), pre-text selection overlays
//! (drawn before the text so text reads on top in Cairo's painter
//! order), gutter (BP / git / line numbers right-aligned / diagnostic
//! dot / lightbulb), syntax-highlighted text via Pango attributes,
//! ghost continuation, inline annotations, indent guides, color
//! columns, bracket-match (alpha rect), wavy diagnostic underlines,
//! dotted spell underlines, cursor (Block alpha rect, Bar 2px,
//! Underline 12% line height), AI ghost text after the cursor, and
//! secondary cursors.
//!
//! ## Selection paint ordering vs TUI
//!
//! GTK paints selections **before** text. TUI paints selections
//! **after** text (modifies bg on cells whose chars are already in the
//! buffer). The divergence is intrinsic to the surfaces — Cairo paints
//! in order, while ratatui cells coalesce fg+bg+char. The data
//! primitive is shared; the paint approach is not. Don't try to
//! consolidate the orders across rasterisers.
//!
//! ## Status line
//!
//! The per-window status line is **not** painted by this rasteriser.
//! The host shrinks `editor.rect` for the status row before calling
//! `draw_editor` and paints the status line separately afterwards.
//!
//! ## Scrollbars
//!
//! `draw_editor` paints both scrollbars itself. Geometry comes from
//! [`Editor::layout`] (the same call hit-testing already uses, so
//! paint and click agree by construction), converted to
//! [`crate::primitives::scrollbar::Scrollbar`] and painted through
//! [`crate::primitives::scrollbar::native_surface_paint::paint`] via
//! the shared [`super::surface::CairoSurface`] adapter — the same
//! pattern `gtk::data_table` and `gtk::list` already use to paint an
//! embedded scrollbar from a bare `cr: &Context` rather than a live
//! `GtkBackend`.
//!
//! Unlike TUI's fixed-cell grid — where a cell can only ever hold one
//! glyph, so "paint the scrollbar after the text" is only possible
//! because `viewport_cols` was pre-narrowed by one column before any
//! text was painted into it — Cairo's pixel surface *can* paint one
//! thing directly on top of another. To still match TUI's actual
//! result (a reserved column, not a glyph visible under a translucent
//! track), this rasteriser narrows the **content clip** by the same
//! `editor_geom.text_bounds.width` [`Editor::layout`] computes for
//! hit-testing *before* painting any text/indent-guides/color-columns/
//! diagnostic+spell-underlines/bracket-match (see "Clip to text area"
//! below), then paints the scrollbar itself afterwards, once, directly
//! into the now-untouched column. "Paints after" here means "paints
//! into reserved pixels no glyph touched" — the same outcome as TUI's
//! narrowing, reached by clipping instead of by shrinking a cell count,
//! because that's what the two surfaces each make possible. Backgrounds
//! painted *before* the clip is installed (window/cursorline/diff/DAP
//! backgrounds, selection overlays) are deliberately left full-width,
//! matching TUI's own `line_bg`/`render_selection`, which paint the
//! full row before the scrollbar draw call overwrites whatever ended up
//! in its column — narrowing those too would just be extra clipping
//! for a region the scrollbar paints over regardless.
//!
//! ## Minimap interaction
//!
//! This rasteriser has no awareness of a `Minimap` primitive sitting
//! beside the editor — that would violate this crate's
//! primitive-distinctness rule (`DECISIONS.md`), the same reason the
//! status line isn't painted here either (see below). But
//! `Editor::layout`'s `has_v_scrollbar` fires whenever the buffer
//! overflows the viewport, with no awareness of whether a sibling
//! `Minimap` is already offering a scroll affordance. The minimap-as-
//! scrollbar case (VS-Code-style: the slider draws *over* the minimap,
//! which acts as the track), and narrowing `editor.rect` alone can't
//! suppress this rasteriser's own column without also strangling the
//! text viewport. [`crate::primitives::editor::EditorPaintOptions::
//! suppress_v_scrollbar`] is the opt-out: a host running its minimap
//! in scrollbar mode calls [`draw_editor_with_options`] with that flag
//! set, which makes `Editor::layout_with_options` return
//! `v_scrollbar_bounds: None` unconditionally — no column is reserved
//! by the content clip above, and this function skips the vertical
//! scrollbar paint entirely, leaving the minimap as the sole scroll
//! affordance. It isn't a field on `Editor` itself: both known
//! downstream consumers build `Editor` with exhaustive struct literals,
//! so a new field there would break them with `E0063`. `draw_editor`
//! (unchanged, plain-`Editor` signature) keeps calling through with the
//! default (`false`) options, so every existing caller is unaffected.

use crate::primitives::editor::{
    CursorShape, DiagnosticSeverity, DiffLine, Editor, EditorLayout, EditorLine,
    EditorPaintOptions, EditorSelection, EditorStyledSpan, GitLineStatus, SelectionKind,
};
use crate::primitives::scrollbar::Scrollbar;
use crate::theme::Theme;
use crate::types::Color;
use gtk4::cairo::Context;
use gtk4::pango::{self, AttrColor, AttrList};

/// Paint an [`Editor`] primitive into the supplied Cairo context.
///
/// `char_width` and `line_height` are surface-native pixel
/// measurements obtained from the host's font metrics — passed in so
/// the host's font/scale settings stay authoritative.
///
/// Equivalent to [`draw_editor_with_options`] with
/// `EditorPaintOptions::default()` — kept as a separate, unchanged
/// function (rather than growing this one's argument list) so every
/// existing caller keeps compiling untouched.
#[allow(clippy::too_many_arguments)]
pub fn draw_editor(
    cr: &Context,
    layout: &pango::Layout,
    font_metrics: &pango::FontMetrics,
    editor: &Editor,
    theme: &Theme,
    char_width: f64,
    line_height: f64,
) {
    draw_editor_with_options(
        cr,
        layout,
        font_metrics,
        editor,
        theme,
        char_width,
        line_height,
        EditorPaintOptions::default(),
    )
}

/// Paint context threaded through per-section helpers. Private —
/// an internal decomposition aid, not a new public shape.
struct EditorPaintCtx<'a> {
    cr: &'a Context,
    layout: &'a pango::Layout,
    font_metrics: &'a pango::FontMetrics,
    editor: &'a Editor,
    theme: &'a Theme,
    char_width: f64,
    line_height: f64,
    rect: &'a crate::Rect,
    gutter_width: f64,
    text_x_offset: f64,
    editor_geom: EditorLayout,
    text_v_offset: f64,
}

/// Vertical distance from a row's top edge to the top of the glyph cell
/// that centres `font_metrics`'s own natural line height inside
/// `line_height` — GTK's counterpart to
/// [`crate::macos::editor::text_v_offset`] (same formula, Pango units
/// instead of Core Text's). A host sets the editor's row pitch
/// (`line_height`) independently of the font's natural ascent +
/// descent — vimcode's VS Code-style 18px rows over a smaller editor
/// font leaves slack below a glyph painted straight at `cr.move_to`'s
/// row-top origin. Every text paint inside one row — gutter glyphs,
/// body text, ghost continuation, inline annotation, the code-action
/// lightbulb — adds this offset, so they share a baseline and the row
/// reads centred like VS Code, matching the diagnostic-dot centring
/// ([`paint_gutter_diagnostic_or_lightbulb`]) that already used
/// `line_height * 0.5` for its own, unrelated reason.
///
/// Negative when `line_height` is tighter than the font's natural
/// height — see `text_v_offset`'s macOS doc for why that's left
/// unclamped.
fn text_v_offset(font_metrics: &pango::FontMetrics, line_height: f64) -> f64 {
    let natural_height =
        (font_metrics.ascent() + font_metrics.descent()) as f64 / pango::SCALE as f64;
    (line_height - natural_height) / 2.0
}

/// [`draw_editor`], plus [`EditorPaintOptions`] a host can set to
/// override otherwise-automatic paint decisions — currently just
/// `suppress_v_scrollbar` (see the module doc's "Minimap
/// interaction" section).
///
/// Equivalent to [`draw_editor_with_options_and_v_scrollbar_w`] with
/// `v_scrollbar_w: None` (a `char_width`-wide scrollbar column).
#[allow(clippy::too_many_arguments)]
pub fn draw_editor_with_options(
    cr: &Context,
    layout: &pango::Layout,
    font_metrics: &pango::FontMetrics,
    editor: &Editor,
    theme: &Theme,
    char_width: f64,
    line_height: f64,
    options: EditorPaintOptions,
) {
    draw_editor_with_options_and_v_scrollbar_w(
        cr,
        layout,
        font_metrics,
        editor,
        theme,
        char_width,
        line_height,
        options,
        None,
    )
}

/// [`draw_editor_with_options`], plus a host-settable vertical scrollbar
/// width in pixels — see [`Editor::layout_with_options_and_v_scrollbar_w`]
/// for the geometry. `None` sizes the column at `char_width`.
/// `GtkBackend::draw_editor` calls this with the width set through
/// [`crate::Backend::set_editor_v_scrollbar_width`].
#[allow(clippy::too_many_arguments)]
pub fn draw_editor_with_options_and_v_scrollbar_w(
    cr: &Context,
    layout: &pango::Layout,
    font_metrics: &pango::FontMetrics,
    editor: &Editor,
    theme: &Theme,
    char_width: f64,
    line_height: f64,
    options: EditorPaintOptions,
    v_scrollbar_w: Option<f32>,
) {
    let rect = &editor.rect;
    let gutter_width = editor.gutter_char_width as f64 * char_width;
    let h_scroll_offset = editor.scroll_left as f64 * char_width;
    let text_x_offset = rect.x as f64 + gutter_width - h_scroll_offset;
    // Computed once up front (rather than after painting text, as a
    // prior revision of this function did) so the content clip below
    // can be narrowed by the same reserved scrollbar column the
    // scrollbar paint and `EditorLayout::hit_test` already agree on —
    // see the module doc's "Scrollbars" section.
    let editor_geom = editor.layout_with_options_and_v_scrollbar_w(
        *rect,
        char_width as f32,
        line_height as f32,
        options,
        v_scrollbar_w,
    );

    let text_v_offset = text_v_offset(font_metrics, line_height);

    let ctx = EditorPaintCtx {
        cr,
        layout,
        font_metrics,
        editor,
        theme,
        char_width,
        line_height,
        rect,
        gutter_width,
        text_x_offset,
        editor_geom,
        text_v_offset,
    };

    paint_window_background(&ctx);
    paint_line_backgrounds(&ctx);
    paint_selection_overlays(&ctx);
    paint_gutter(&ctx);

    // ── Clip to text area (excludes gutter AND the reserved vertical
    // scrollbar column, when present) ───────────────────────────────────
    //
    // Narrowed to `editor_geom.text_bounds.width` rather than the full
    // `rect.width - gutter_width`, mirroring `tui::editor::draw_editor`'s
    // `viewport_cols` narrowing — text/indent-guides/color-columns/
    // diagnostic+spell underlines/bracket-match stop short of the
    // scrollbar column instead of painting glyphs that the scrollbar
    // then overlays.
    cr.save().ok();
    cr.rectangle(
        rect.x as f64 + gutter_width,
        rect.y as f64,
        ctx.editor_geom.text_bounds.width as f64,
        rect.height as f64,
    );
    cr.clip();

    paint_text_lines(&ctx);

    cr.restore().ok();

    // Scrollbars are painted last among the "content" layers — after
    // text/selections, before the cursor — mirroring
    // `tui::editor::draw_editor`'s z-order; see module doc for the
    // shared-geometry rationale and the minimap boundary. The content
    // clip above already reserved this column, so this paints into
    // pixels no glyph touched, not over them.
    paint_scrollbars(&ctx);
    paint_primary_cursor(&ctx);
    paint_ai_ghost_text(&ctx);
    paint_secondary_cursors(&ctx);
}

// ── Window background ────────────────────────────────────────────────
fn paint_window_background(ctx: &EditorPaintCtx) {
    let EditorPaintCtx {
        cr, editor, theme, ..
    } = ctx;
    let rect = ctx.rect;
    let bg = if editor.show_active_bg {
        theme.editor_active_background
    } else {
        theme.background
    };
    let (br, bg_g, bb) = cairo_rgb(bg);
    cr.set_source_rgb(br, bg_g, bb);
    cr.rectangle(
        rect.x as f64,
        rect.y as f64,
        rect.width as f64,
        rect.height as f64,
    );
    cr.fill().ok();
}

// ── Cursorline / Diff / DAP stopped-line backgrounds ────────────────────
fn paint_line_backgrounds(ctx: &EditorPaintCtx) {
    let EditorPaintCtx {
        cr,
        editor,
        theme,
        line_height,
        ..
    } = ctx;
    let (cr, editor, theme, line_height) = (*cr, *editor, *theme, *line_height);
    let rect = ctx.rect;
    // Stop short of the reserved vertical scrollbar column, mirroring the
    // text clip below — `text_bounds.x + text_bounds.width` already
    // excludes `v_scrollbar_bounds` when present, so the fill never
    // bleeds under the scrollbar.
    let bg_right = ctx.editor_geom.text_bounds.x as f64 + ctx.editor_geom.text_bounds.width as f64;
    let bg_width = (bg_right - rect.x as f64).max(0.0);
    for (view_idx, rl) in editor.lines.iter().enumerate() {
        let y = rect.y as f64 + view_idx as f64 * line_height;
        let bg_color = if rl.is_dap_current {
            Some(theme.dap_stopped_bg)
        } else if let Some(diff_status) = rl.diff_status {
            match diff_status {
                DiffLine::Added => Some(theme.diff_added_bg),
                DiffLine::Removed => Some(theme.diff_removed_bg),
                DiffLine::Padding => Some(theme.diff_padding_bg),
                DiffLine::Same => None,
            }
        } else if rl.is_current_line && editor.is_active && editor.cursorline {
            Some(theme.cursorline_bg)
        } else {
            None
        };
        if let Some(color) = bg_color {
            let (dr, dg, db) = cairo_rgb(color);
            cr.set_source_rgb(dr, dg, db);
            cr.rectangle(rect.x as f64, y, bg_width, line_height);
            cr.fill().ok();
        }
    }
}

// ── Selection overlays (drawn before text so text is on top) ────────────
fn paint_selection_overlays(ctx: &EditorPaintCtx) {
    let EditorPaintCtx {
        cr,
        layout,
        editor,
        theme,
        line_height,
        text_x_offset,
        ..
    } = ctx;
    let (cr, layout, editor, theme, line_height, text_x_offset) =
        (*cr, *layout, *editor, *theme, *line_height, *text_x_offset);
    let rect = ctx.rect;
    if let Some(sel) = &editor.selection {
        draw_visual_selection(
            cr,
            layout,
            sel,
            &editor.lines,
            rect,
            line_height,
            text_x_offset,
            theme.selection,
            theme.selection_alpha as f64,
        );
    }
    for esel in &editor.extra_selections {
        draw_visual_selection(
            cr,
            layout,
            esel,
            &editor.lines,
            rect,
            line_height,
            text_x_offset,
            theme.selection,
            theme.selection_alpha as f64,
        );
    }
    if let Some(yh) = &editor.yank_highlight {
        draw_visual_selection(
            cr,
            layout,
            yh,
            &editor.lines,
            rect,
            line_height,
            text_x_offset,
            theme.yank_highlight_bg,
            theme.yank_highlight_alpha as f64,
        );
    }
}

// ── Gutter (bp + git + line numbers right-aligned + diag/lightbulb) ─────
fn paint_gutter(ctx: &EditorPaintCtx) {
    let EditorPaintCtx {
        editor,
        line_height,
        ..
    } = ctx;
    let (editor, line_height) = (*editor, *line_height);

    if editor.gutter_char_width == 0 {
        return;
    }

    for (view_idx, rl) in editor.lines.iter().enumerate() {
        let y = ctx.rect.y as f64 + view_idx as f64 * line_height;
        paint_gutter_row_number(ctx, rl, y);
        paint_gutter_diagnostic_or_lightbulb(ctx, rl, y);
    }
}

/// Breakpoint marker, git marker, and right-aligned line number for one
/// gutter row — the three columns that share the gutter `layout`'s
/// running `char_offset`.
fn paint_gutter_row_number(ctx: &EditorPaintCtx, rl: &EditorLine, y: f64) {
    let EditorPaintCtx {
        cr,
        layout,
        editor,
        theme,
        char_width,
        gutter_width,
        ..
    } = ctx;
    let (cr, layout, editor, theme, char_width, gutter_width) =
        (*cr, *layout, *editor, *theme, *char_width, *gutter_width);
    let rect = ctx.rect;
    // Every glyph painted by this function is text, so it shares the
    // row's `text_v_offset` — see that function's doc.
    let y = y + ctx.text_v_offset;
    let mut char_offset = 0usize;

    // Breakpoint column (leftmost when has_breakpoints).
    if editor.has_breakpoints {
        let bp_ch: String = rl.gutter_text.chars().take(1).collect();
        let bp_color = if rl.is_dap_current || rl.is_breakpoint {
            theme.diagnostic_error
        } else {
            theme.line_number_fg
        };
        layout.set_text(&bp_ch);
        layout.set_attributes(None);
        let (br, bg_c, bb) = cairo_rgb(bp_color);
        cr.set_source_rgb(br, bg_c, bb);
        cr.move_to(rect.x as f64 + 3.0, y);
        super::painted_text::show_layout(cr, layout);
        char_offset += 1;
    }

    // Git marker column.
    if editor.has_git_diff {
        let git_ch: String = rl.gutter_text.chars().skip(char_offset).take(1).collect();
        let git_color = match rl.git_diff {
            Some(GitLineStatus::Added) => theme.git_added,
            Some(GitLineStatus::Modified) => theme.git_modified,
            Some(GitLineStatus::Deleted) => theme.git_deleted,
            None => theme.line_number_fg,
        };
        layout.set_text(&git_ch);
        layout.set_attributes(None);
        let (gr, gg, gb) = cairo_rgb(git_color);
        cr.set_source_rgb(gr, gg, gb);
        cr.move_to(rect.x as f64 + char_offset as f64 * char_width + 3.0, y);
        super::painted_text::show_layout(cr, layout);
        char_offset += 1;

        // Fold + line numbers portion right-aligned.
        let rest: String = rl.gutter_text.chars().skip(char_offset).collect();
        layout.set_text(&rest);
        layout.set_attributes(None);
    } else if char_offset > 0 {
        let rest: String = rl.gutter_text.chars().skip(char_offset).collect();
        layout.set_text(&rest);
        layout.set_attributes(None);
    } else {
        layout.set_text(&rl.gutter_text);
        layout.set_attributes(None);
    }

    let (num_width, _) = layout.pixel_size();
    let num_x = rect.x as f64 + gutter_width - num_width as f64 - char_width + 3.0;

    let num_color = if editor.is_active && rl.is_current_line {
        theme.line_number_active_fg
    } else {
        theme.line_number_fg
    };
    let (nr, ng, nb) = cairo_rgb(num_color);
    cr.set_source_rgb(nr, ng, nb);
    cr.move_to(num_x, y);
    super::painted_text::show_layout(cr, layout);
}

/// Diagnostic gutter dot (overrides the lightbulb when both apply), or
/// the code-action lightbulb glyph, for one gutter row.
fn paint_gutter_diagnostic_or_lightbulb(ctx: &EditorPaintCtx, rl: &EditorLine, y: f64) {
    let EditorPaintCtx {
        cr,
        layout,
        editor,
        theme,
        line_height,
        ..
    } = ctx;
    let (cr, layout, editor, theme, line_height) = (*cr, *layout, *editor, *theme, *line_height);
    let rect = ctx.rect;

    if let Some(severity) = editor.diagnostic_gutter.get(&rl.line_idx) {
        let diag_color = match severity {
            DiagnosticSeverity::Error => theme.diagnostic_error,
            DiagnosticSeverity::Warning => theme.diagnostic_warning,
            DiagnosticSeverity::Information => theme.diagnostic_info,
            DiagnosticSeverity::Hint => theme.diagnostic_hint,
        };
        let (dr, dg, db) = cairo_rgb(diag_color);
        cr.set_source_rgb(dr, dg, db);
        let dot_r = line_height * 0.2;
        let dot_cx = rect.x as f64 + 3.0 + dot_r;
        let dot_cy = y + line_height * 0.5;
        cr.arc(dot_cx, dot_cy, dot_r, 0.0, 2.0 * std::f64::consts::PI);
        cr.fill().ok();
    } else if !rl.is_wrap_continuation
        && editor.code_action_lines.contains(&rl.line_idx)
        && editor.lightbulb_glyph != '\0'
    {
        let (lr, lg, lb) = cairo_rgb(theme.lightbulb);
        cr.set_source_rgb(lr, lg, lb);
        let bulb_layout = layout.clone();
        bulb_layout.set_text(&editor.lightbulb_glyph.to_string());
        // Text glyph, unlike the diagnostic dot above (which centres
        // itself via `line_height * 0.5`) — shares the row's
        // `text_v_offset`, same as the gutter number.
        cr.move_to(rect.x as f64 + 1.0, y + ctx.text_v_offset);
        super::painted_text::show_layout(cr, &bulb_layout);
    }
}

// ── Render each visible line (text, ghost, annotation, indent guides,
// color columns, bracket match, diagnostic + spell underlines) ─────────
fn paint_text_lines(ctx: &EditorPaintCtx) {
    let EditorPaintCtx {
        editor,
        line_height,
        ..
    } = ctx;
    let (editor, line_height) = (*editor, *line_height);

    for (view_idx, rl) in editor.lines.iter().enumerate() {
        let y = ctx.rect.y as f64 + view_idx as f64 * line_height;
        paint_line_text_ghost_and_annotation(ctx, rl, y);
        paint_line_indent_guides_and_colorcolumns(ctx, rl, y);
        paint_line_bracket_match(ctx, view_idx, y);

        // Restore layout to match rendered text (needed for correct
        // index_to_pos when font_scale != 1.0, e.g. markdown headings) —
        // the guides/colorcolumns/bracket-match painters above don't
        // touch `layout`'s text, but keeping this reset here (rather
        // than trusting that) matches the pre-split behaviour exactly.
        ctx.layout.set_text(&rl.raw_text);
        let line_attrs = build_pango_attrs(&rl.spans);
        ctx.layout.set_attributes(Some(&line_attrs));

        paint_line_diagnostic_underlines(ctx, rl, y);
        paint_line_spell_underlines(ctx, rl, y);
    }
}

/// Base syntax-highlighted text, ghost continuation (full line in ghost
/// colour), and inline annotation (e.g. git blame) — the three overlays
/// that share `layout`'s just-set `raw_text` + span attributes.
fn paint_line_text_ghost_and_annotation(ctx: &EditorPaintCtx, rl: &EditorLine, y: f64) {
    let EditorPaintCtx {
        cr,
        layout,
        theme,
        char_width,
        text_x_offset,
        ..
    } = ctx;
    let (cr, layout, theme, char_width, text_x_offset) =
        (*cr, *layout, *theme, *char_width, *text_x_offset);
    // Every glyph painted by this function is text, so it shares the
    // row's `text_v_offset` — see that function's doc.
    let y = y + ctx.text_v_offset;

    layout.set_text(&rl.raw_text);
    let attrs = build_pango_attrs(&rl.spans);
    layout.set_attributes(Some(&attrs));

    let (fr, fg_g, fb) = cairo_rgb(theme.foreground);
    cr.set_source_rgb(fr, fg_g, fb);
    cr.move_to(text_x_offset, y);
    super::painted_text::show_layout(cr, layout);

    // Ghost continuation lines — full line in ghost colour.
    if rl.is_ghost_continuation {
        if let Some(ghost) = &rl.ghost_suffix {
            let (gr, gg, gb) = cairo_rgb(theme.ghost_text_fg);
            cr.set_source_rgb(gr, gg, gb);
            cr.move_to(text_x_offset, y);
            layout.set_text(ghost);
            layout.set_attributes(None);
            super::painted_text::show_layout(cr, layout);
        }
    }

    // Inline annotation / virtual text (e.g. git blame).
    if let Some(ann) = &rl.annotation {
        let text_pixel_width = layout.pixel_size().0 as f64;
        let ann_x = text_x_offset + text_pixel_width + char_width * 2.0;
        let (ar, ag, ab) = cairo_rgb(theme.annotation_fg);
        cr.set_source_rgb(ar, ag, ab);
        cr.move_to(ann_x, y);
        layout.set_text(ann);
        layout.set_attributes(None);
        super::painted_text::show_layout(cr, layout);
    }
}

/// Indent guides (thin vertical lines) and color columns (tinted
/// background rects) for one line.
fn paint_line_indent_guides_and_colorcolumns(ctx: &EditorPaintCtx, rl: &EditorLine, y: f64) {
    let EditorPaintCtx {
        cr,
        editor,
        theme,
        char_width,
        line_height,
        text_x_offset,
        ..
    } = ctx;
    let (cr, editor, theme, char_width, line_height, text_x_offset) = (
        *cr,
        *editor,
        *theme,
        *char_width,
        *line_height,
        *text_x_offset,
    );

    // Indent guides: thin vertical lines at each guide column.
    if !rl.indent_guides.is_empty() {
        cr.set_line_width(1.0);
        for &guide_col in &rl.indent_guides {
            let is_active = editor.active_indent_col == Some(guide_col);
            let (gr, gg, gb) = if is_active {
                cairo_rgb(theme.indent_guide_active_fg)
            } else {
                cairo_rgb(theme.indent_guide_fg)
            };
            cr.set_source_rgb(gr, gg, gb);
            let gx = text_x_offset + guide_col as f64 * char_width;
            cr.move_to(gx, y);
            cr.line_to(gx, y + line_height);
            cr.stroke().ok();
        }
    }

    // Color columns: tinted background rectangle at each column.
    if !rl.colorcolumns.is_empty() {
        let (cr2, cg, cb) = cairo_rgb(theme.colorcolumn_bg);
        cr.set_source_rgb(cr2, cg, cb);
        for &cc_col in &rl.colorcolumns {
            let cx = text_x_offset + cc_col as f64 * char_width;
            cr.rectangle(cx, y, char_width, line_height);
            cr.fill().ok();
        }
    }
}

/// Bracket-match highlighting (semi-transparent rect) for one line.
fn paint_line_bracket_match(ctx: &EditorPaintCtx, view_idx: usize, y: f64) {
    let EditorPaintCtx {
        cr,
        editor,
        theme,
        char_width,
        line_height,
        text_x_offset,
        ..
    } = ctx;
    let (cr, editor, theme, char_width, line_height, text_x_offset) = (
        *cr,
        *editor,
        *theme,
        *char_width,
        *line_height,
        *text_x_offset,
    );

    for &(bm_view_line, bm_col) in &editor.bracket_match_positions {
        if bm_view_line == view_idx {
            let (br, bg_c, bb) = cairo_rgb(theme.bracket_match_bg);
            cr.set_source_rgba(br, bg_c, bb, 0.6);
            let bx = text_x_offset + bm_col as f64 * char_width;
            cr.rectangle(bx, y, char_width, line_height);
            cr.fill().ok();
        }
    }
}

/// Diagnostic underlines (wavy squiggle) for one line. Caller has
/// already reset `layout` to `rl.raw_text` so `index_to_pos` resolves
/// correctly.
fn paint_line_diagnostic_underlines(ctx: &EditorPaintCtx, rl: &EditorLine, y: f64) {
    let EditorPaintCtx {
        cr,
        layout,
        theme,
        line_height,
        text_x_offset,
        ..
    } = ctx;
    let (cr, layout, theme, line_height, text_x_offset) =
        (*cr, *layout, *theme, *line_height, *text_x_offset);

    for dm in &rl.diagnostics {
        let diag_color = match dm.severity {
            DiagnosticSeverity::Error => theme.diagnostic_error,
            DiagnosticSeverity::Warning => theme.diagnostic_warning,
            DiagnosticSeverity::Information => theme.diagnostic_info,
            DiagnosticSeverity::Hint => theme.diagnostic_hint,
        };
        let (dr, dg, db) = cairo_rgb(diag_color);
        cr.set_source_rgb(dr, dg, db);
        cr.set_line_width(1.0);

        let start_byte = rl
            .raw_text
            .char_indices()
            .nth(dm.start_col)
            .map(|(i, _)| i)
            .unwrap_or(rl.raw_text.len());
        let end_byte = rl
            .raw_text
            .char_indices()
            .nth(dm.end_col)
            .map(|(i, _)| i)
            .unwrap_or(rl.raw_text.len());

        let start_pos = layout.index_to_pos(start_byte as i32);
        let end_pos = layout.index_to_pos(end_byte as i32);
        let x0 = text_x_offset + start_pos.x() as f64 / pango::SCALE as f64;
        let x1 = text_x_offset + end_pos.x() as f64 / pango::SCALE as f64;
        let underline_y = y + line_height - 2.0;

        let wave_h = 1.5;
        let wave_len = 4.0;
        cr.move_to(x0, underline_y);
        let mut wx = x0;
        let mut up = true;
        while wx < x1 {
            let next_x = (wx + wave_len).min(x1);
            let cy = if up {
                underline_y - wave_h
            } else {
                underline_y + wave_h
            };
            cr.curve_to(
                wx + (next_x - wx) * 0.5,
                cy,
                wx + (next_x - wx) * 0.5,
                cy,
                next_x,
                underline_y,
            );
            wx = next_x;
            up = !up;
        }
        cr.stroke().ok();
    }
}

/// Spell error underlines (dotted) for one line. Caller has already
/// reset `layout` to `rl.raw_text` so `index_to_pos` resolves correctly.
fn paint_line_spell_underlines(ctx: &EditorPaintCtx, rl: &EditorLine, y: f64) {
    let EditorPaintCtx {
        cr,
        layout,
        theme,
        line_height,
        text_x_offset,
        ..
    } = ctx;
    let (cr, layout, theme, line_height, text_x_offset) =
        (*cr, *layout, *theme, *line_height, *text_x_offset);

    for sm in &rl.spell_errors {
        let (sr, sg, sb) = cairo_rgb(theme.spell_error);
        cr.set_source_rgb(sr, sg, sb);
        cr.set_line_width(1.0);

        let start_byte = rl
            .raw_text
            .char_indices()
            .nth(sm.start_col)
            .map(|(i, _)| i)
            .unwrap_or(rl.raw_text.len());
        let end_byte = rl
            .raw_text
            .char_indices()
            .nth(sm.end_col)
            .map(|(i, _)| i)
            .unwrap_or(rl.raw_text.len());

        let start_pos = layout.index_to_pos(start_byte as i32);
        let end_pos = layout.index_to_pos(end_byte as i32);
        let x0 = text_x_offset + start_pos.x() as f64 / pango::SCALE as f64;
        let x1 = text_x_offset + end_pos.x() as f64 / pango::SCALE as f64;
        let underline_y = y + line_height - 2.0;

        let dot_spacing = 3.0;
        let mut dx = x0;
        while dx < x1 {
            cr.rectangle(dx, underline_y, 1.0, 1.0);
            dx += dot_spacing;
        }
        cr.fill().ok();
    }
}

// ── Scrollbars ───────────────────────────────────────────────────────
fn paint_scrollbars(ctx: &EditorPaintCtx) {
    let EditorPaintCtx {
        cr,
        editor,
        theme,
        line_height,
        editor_geom,
        ..
    } = ctx;
    let (cr, editor, theme, line_height) = (*cr, *editor, *theme, *line_height);

    if let Some(v_track) = editor_geom.v_scrollbar_bounds {
        let sb = Scrollbar::vertical(
            "gtk:editor:v_scrollbar",
            v_track,
            editor.scroll_top as f32,
            editor.total_lines as f32,
            editor_geom.visible_lines as f32,
            line_height as f32,
        );
        let mut raw = super::surface::CairoSurface {
            cr,
            layout: None,
            translucent_fill: true,
        };
        crate::primitives::scrollbar::native_surface_paint::paint(&sb, &mut raw, theme);
    }
    if let Some(h_track) = editor_geom.h_scrollbar_bounds {
        let sb = Scrollbar::horizontal(
            "gtk:editor:h_scrollbar",
            h_track,
            editor.scroll_left as f32,
            editor.max_col as f32,
            editor_geom.visible_cols as f32,
            line_height as f32,
        );
        let mut raw = super::surface::CairoSurface {
            cr,
            layout: None,
            translucent_fill: true,
        };
        crate::primitives::scrollbar::native_surface_paint::paint(&sb, &mut raw, theme);
    }
}

// ── Cursor (Block alpha rect / Bar 2px / Underline 12% line height) ────
fn paint_primary_cursor(ctx: &EditorPaintCtx) {
    let EditorPaintCtx {
        cr,
        layout,
        font_metrics,
        editor,
        theme,
        line_height,
        text_x_offset,
        ..
    } = ctx;
    let (cr, layout, font_metrics, editor, theme, line_height, text_x_offset) = (
        *cr,
        *layout,
        *font_metrics,
        *editor,
        *theme,
        *line_height,
        *text_x_offset,
    );
    let rect = ctx.rect;

    let Some(cursor) = &editor.cursor else {
        return;
    };
    let Some(rl) = editor.lines.get(cursor.pos.view_line) else {
        return;
    };

    layout.set_text(&rl.raw_text);
    let cursor_attrs = build_pango_attrs(&rl.spans);
    layout.set_attributes(Some(&cursor_attrs));

    let render_col = if !editor.extra_selections.is_empty() && cursor.shape == CursorShape::Bar {
        cursor.pos.col + 1
    } else {
        cursor.pos.col
    };
    let byte_offset: usize = rl
        .raw_text
        .char_indices()
        .nth(render_col)
        .map(|(i, _)| i)
        .unwrap_or(rl.raw_text.len());

    let pos = layout.index_to_pos(byte_offset as i32);
    let cursor_x = text_x_offset + pos.x() as f64 / pango::SCALE as f64;
    let raw_w = pos.width() as f64 / pango::SCALE as f64;
    let cursor_y = rect.y as f64 + cursor.pos.view_line as f64 * line_height;

    let (cr_r, cr_g, cr_b) = cairo_rgb(theme.cursor);
    let char_w = if raw_w > 0.0 {
        raw_w
    } else {
        font_metrics.approximate_char_width() as f64 / pango::SCALE as f64
    };
    match cursor.shape {
        CursorShape::Block => {
            cr.set_source_rgba(cr_r, cr_g, cr_b, theme.cursor_normal_alpha as f64);
            cr.rectangle(cursor_x, cursor_y, char_w, line_height);
            cr.fill().ok();
        }
        CursorShape::Bar => {
            cr.set_source_rgb(cr_r, cr_g, cr_b);
            cr.rectangle(cursor_x, cursor_y, 2.0, line_height);
            cr.fill().ok();
        }
        CursorShape::Underline => {
            cr.set_source_rgb(cr_r, cr_g, cr_b);
            let bar_h = (line_height * 0.12).max(2.0);
            cr.rectangle(cursor_x, cursor_y + line_height - bar_h, char_w, bar_h);
            cr.fill().ok();
        }
    }
}

// ── AI ghost text (after cursor on cursor line) ─────────────────────────
fn paint_ai_ghost_text(ctx: &EditorPaintCtx) {
    let EditorPaintCtx {
        cr,
        layout,
        editor,
        theme,
        line_height,
        text_x_offset,
        ..
    } = ctx;
    let (cr, layout, editor, theme, line_height, text_x_offset) =
        (*cr, *layout, *editor, *theme, *line_height, *text_x_offset);
    let rect = ctx.rect;

    let Some(cursor) = &editor.cursor else {
        return;
    };
    let Some(rl) = editor.lines.get(cursor.pos.view_line) else {
        return;
    };
    let Some(ghost) = &rl.ghost_suffix else {
        return;
    };

    layout.set_text(&rl.raw_text);
    let ghost_line_attrs = build_pango_attrs(&rl.spans);
    layout.set_attributes(Some(&ghost_line_attrs));
    let byte_offset: usize = rl
        .raw_text
        .char_indices()
        .nth(cursor.pos.col)
        .map(|(i, _)| i)
        .unwrap_or(rl.raw_text.len());
    let pos = layout.index_to_pos(byte_offset as i32);
    let ghost_x = text_x_offset + pos.x() as f64 / pango::SCALE as f64;
    let ghost_y = rect.y as f64 + cursor.pos.view_line as f64 * line_height + ctx.text_v_offset;
    let (gr, gg, gb) = cairo_rgb(theme.ghost_text_fg);
    cr.set_source_rgb(gr, gg, gb);
    cr.move_to(ghost_x, ghost_y);
    layout.set_text(ghost);
    layout.set_attributes(None);
    super::painted_text::show_layout(cr, layout);
}

// ── Secondary cursors (multi-cursor) ─────────────────────────────────────
fn paint_secondary_cursors(ctx: &EditorPaintCtx) {
    let EditorPaintCtx {
        cr,
        layout,
        font_metrics,
        editor,
        theme,
        line_height,
        text_x_offset,
        ..
    } = ctx;
    let (cr, layout, font_metrics, editor, theme, line_height, text_x_offset) = (
        *cr,
        *layout,
        *font_metrics,
        *editor,
        *theme,
        *line_height,
        *text_x_offset,
    );
    let rect = ctx.rect;

    let extra_cursor_shape = editor
        .cursor
        .as_ref()
        .map(|c| c.shape)
        .unwrap_or(CursorShape::Bar);
    let has_extra_sels = !editor.extra_selections.is_empty();
    let fallback_char_w = font_metrics.approximate_char_width() as f64 / pango::SCALE as f64;
    let (cr_r, cr_g, cr_b) = cairo_rgb(theme.cursor);
    for extra_pos in &editor.extra_cursors {
        if let Some(rl) = editor.lines.get(extra_pos.view_line) {
            layout.set_text(&rl.raw_text);
            let extra_attrs = build_pango_attrs(&rl.spans);
            layout.set_attributes(Some(&extra_attrs));
            let render_col = if has_extra_sels && extra_cursor_shape == CursorShape::Bar {
                extra_pos.col + 1
            } else {
                extra_pos.col
            };
            let byte_offset: usize = rl
                .raw_text
                .char_indices()
                .nth(render_col)
                .map(|(i, _)| i)
                .unwrap_or(rl.raw_text.len());
            let pos = layout.index_to_pos(byte_offset as i32);
            let ex = text_x_offset + pos.x() as f64 / pango::SCALE as f64;
            let ew = {
                let w = pos.width() as f64 / pango::SCALE as f64;
                if w > 0.0 {
                    w
                } else {
                    fallback_char_w
                }
            };
            let ey = rect.y as f64 + extra_pos.view_line as f64 * line_height;
            match extra_cursor_shape {
                CursorShape::Bar => {
                    cr.set_source_rgb(cr_r, cr_g, cr_b);
                    cr.rectangle(ex, ey, 2.0, line_height);
                    cr.fill().ok();
                }
                CursorShape::Block => {
                    cr.set_source_rgba(cr_r, cr_g, cr_b, theme.cursor_normal_alpha as f64);
                    cr.rectangle(ex, ey, ew, line_height);
                    cr.fill().ok();
                }
                CursorShape::Underline => {
                    cr.set_source_rgb(cr_r, cr_g, cr_b);
                    let bar_h = (line_height * 0.12).max(2.0);
                    cr.rectangle(ex, ey + line_height - bar_h, ew, bar_h);
                    cr.fill().ok();
                }
            }
        }
    }
}

// ─── Private helpers ────────────────────────────────────────────────────

/// Same shape as `quadraui::gtk::cairo_rgb`, kept as a local helper so
/// this module's call sites stay terse.
fn cairo_rgb(c: Color) -> (f64, f64, f64) {
    (c.r as f64 / 255.0, c.g as f64 / 255.0, c.b as f64 / 255.0)
}

/// Convert a `quadraui::Color` into the 16-bit (0..65535) values
/// expected by Pango's `AttrColor` constructors.
fn pango_u16(c: Color) -> (u16, u16, u16) {
    (c.r as u16 * 257, c.g as u16 * 257, c.b as u16 * 257)
}

/// Build a Pango `AttrList` from the editor primitive's byte-range
/// spans. Mirrors `vimcode::gtk::draw::build_pango_attrs`.
fn build_pango_attrs(spans: &[EditorStyledSpan]) -> AttrList {
    let attrs = AttrList::new();
    for span in spans {
        let (fr, fg_g, fb) = pango_u16(span.style.fg);
        let mut fg_attr = AttrColor::new_foreground(fr, fg_g, fb);
        fg_attr.set_start_index(span.start_byte as u32);
        fg_attr.set_end_index(span.end_byte as u32);
        attrs.insert(fg_attr);

        if let Some(bg) = span.style.bg {
            let (br, bg_g, bb) = pango_u16(bg);
            let mut bg_attr = AttrColor::new_background(br, bg_g, bb);
            bg_attr.set_start_index(span.start_byte as u32);
            bg_attr.set_end_index(span.end_byte as u32);
            attrs.insert(bg_attr);
        }
        if span.style.bold {
            let mut w = pango::AttrInt::new_weight(pango::Weight::Bold);
            w.set_start_index(span.start_byte as u32);
            w.set_end_index(span.end_byte as u32);
            attrs.insert(w);
        }
        if span.style.italic {
            let mut s = pango::AttrInt::new_style(pango::Style::Italic);
            s.set_start_index(span.start_byte as u32);
            s.set_end_index(span.end_byte as u32);
            attrs.insert(s);
        }
        if (span.style.font_scale - 1.0).abs() > f32::EPSILON {
            let mut sc = pango::AttrFloat::new_scale(span.style.font_scale as f64);
            sc.set_start_index(span.start_byte as u32);
            sc.set_end_index(span.end_byte as u32);
            attrs.insert(sc);
        }
    }
    attrs
}

/// Resolve `x` (absolute/surface-space) to a character column within
/// `line.raw_text`, inverting the **exact** glyph geometry
/// [`draw_editor`] painted the line with.
///
/// `pango_layout`'s text and attributes are overwritten by this call
/// (`set_text` + [`build_pango_attrs`], mirroring `draw_editor`'s own
/// per-line setup) — pass a layout carrying the same font family/size
/// `draw_editor` painted with (the frame-scoped layout while still
/// inside `enter_frame_scope`, or the cached last-painted clone when
/// called at click-time outside any frame scope).
///
/// `editor_layout` supplies `text_bounds.x`, `scroll_left`, and
/// `cell_width` — the same values `draw_editor` used to compute
/// `text_x_offset`. Horizontal scroll is resolved in the *layout's*
/// local coordinate space (the Pango layout holds the line's full,
/// unscrolled `raw_text`; scrolling only changes where `draw_editor`
/// positions that layout on screen), so the returned column already
/// reflects `scroll_left` — do not add it again.
pub fn editor_col_at_x(
    pango_layout: &pango::Layout,
    line: &EditorLine,
    editor_layout: &EditorLayout,
    x: f32,
) -> usize {
    pango_layout.set_text(&line.raw_text);
    let attrs = build_pango_attrs(&line.spans);
    pango_layout.set_attributes(Some(&attrs));

    let cell_width = editor_layout.cell_width as f64;
    let local_x = (x as f64 - editor_layout.text_bounds.x as f64)
        + editor_layout.scroll_left as f64 * cell_width;
    let x_pango = (local_x.max(0.0) * pango::SCALE as f64).round() as i32;
    let (_inside, byte_index, _trailing) = pango_layout.xy_to_index(x_pango, 0);
    // Pango should only ever return a UTF-8 char-boundary-aligned index for
    // valid input, but we don't fully control its internals across
    // versions/locales — snap defensively rather than trust it blindly and
    // risk a panic on a non-boundary `byte_index`.
    let clamped =
        crate::text_util::snap_to_char_boundary(&line.raw_text, byte_index.max(0) as usize);
    line.raw_text[..clamped].chars().count() + line.segment_col_offset
}

/// Paint a visual selection range (Char / Line / Block) onto `cr`. Each
/// visual segment of a wrapped buffer line is highlighted independently
/// (one rectangle per matching view row). Column math — including
/// ghost-continuation / diff-padding row skipping and wrapped-segment
/// offsetting — comes from [`EditorSelection::cols_on`]; this
/// function only converts the returned columns to pixel positions.
/// Mirrors `vimcode::gtk::draw::draw_visual_selection`.
#[allow(clippy::too_many_arguments)]
fn draw_visual_selection(
    cr: &Context,
    layout: &pango::Layout,
    sel: &EditorSelection,
    lines: &[EditorLine],
    rect: &crate::event::Rect,
    line_height: f64,
    text_x_offset: f64,
    color: Color,
    alpha: f64,
) {
    let (sr, sg, sb) = cairo_rgb(color);
    cr.set_source_rgba(sr, sg, sb, alpha);

    for (view_idx, rl) in lines.iter().enumerate() {
        let Some(cols) = sel.cols_on(rl) else {
            continue;
        };

        let y = rect.y as f64 + view_idx as f64 * line_height;

        if sel.kind == SelectionKind::Line {
            let highlight_width = rect.width as f64 - (text_x_offset - rect.x as f64);
            cr.rectangle(text_x_offset, y, highlight_width, line_height);
            continue;
        }

        let line_text = &rl.raw_text;
        layout.set_text(line_text);
        layout.set_attributes(None);

        let start_byte = line_text
            .char_indices()
            .nth(cols.start)
            .map(|(i, _)| i)
            .unwrap_or(line_text.len());
        let start_pos = layout.index_to_pos(start_byte as i32);
        let start_x = text_x_offset + start_pos.x() as f64 / pango::SCALE as f64;

        if cols.extends_beyond {
            let (line_width, _) = layout.pixel_size();
            cr.rectangle(
                start_x,
                y,
                (text_x_offset + line_width as f64 - start_x).max(0.0),
                line_height,
            );
        } else {
            let end_byte = line_text
                .char_indices()
                .nth(cols.end)
                .map(|(i, _)| i)
                .unwrap_or(line_text.len());
            let end_pos = layout.index_to_pos(end_byte as i32);
            let end_x = text_x_offset + end_pos.x() as f64 / pango::SCALE as f64;
            cr.rectangle(start_x, y, end_x - start_x, line_height);
        }
    }
    cr.fill().ok();
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::event::Rect;
    use crate::primitives::editor::{Editor, Style};
    use crate::types::Color;
    use pangocairo::cairo::{Context, Format, ImageSurface};
    use std::collections::{HashMap, HashSet};

    /// A line with three differently-styled spans (bold / italic /
    /// `font_scale`) so its painted glyph advances are *not* uniform —
    /// the exact case where the monospace `EditorLayout::col_at_x`
    /// fallback drifts from what `draw_editor` actually painted.
    fn styled_line() -> EditorLine {
        let plain = Style {
            fg: Color::rgb(220, 220, 220),
            bg: None,
            bold: false,
            italic: false,
            font_scale: 1.0,
        };
        EditorLine {
            raw_text: "let x = width; // note".into(),
            gutter_text: "  1".into(),
            spans: vec![
                EditorStyledSpan {
                    start_byte: 0,
                    end_byte: 3,
                    style: Style {
                        bold: true,
                        ..plain
                    },
                }, // "let"
                EditorStyledSpan {
                    start_byte: 8,
                    end_byte: 13,
                    style: Style {
                        italic: true,
                        ..plain
                    },
                }, // "width"
                EditorStyledSpan {
                    start_byte: 15,
                    end_byte: 22,
                    style: Style {
                        font_scale: 1.8,
                        ..plain
                    },
                }, // "// note"
            ],
            line_idx: 0,
            is_current_line: false,
            is_fold_header: false,
            folded_line_count: 0,
            git_diff: None,
            diff_status: None,
            diagnostics: Vec::new(),
            spell_errors: Vec::new(),
            is_breakpoint: false,
            is_conditional_bp: false,
            is_dap_current: false,
            is_wrap_continuation: false,
            segment_col_offset: 0,
            annotation: None,
            ghost_suffix: None,
            is_ghost_continuation: false,
            indent_guides: Vec::new(),
            colorcolumns: Vec::new(),
        }
    }

    fn headless_pango_layout() -> pango::Layout {
        let surface = ImageSurface::create(Format::ARgb32, 900, 60).expect("create ImageSurface");
        let cr = Context::new(&surface).expect("Context::new");
        let ctx = pangocairo::functions::create_context(&cr);
        ctx.set_font_description(&pango::FontDescription::from_string("Monospace 12"));
        pango::Layout::new(&ctx)
    }

    /// Paint a styled, horizontally-scrolled line, then assert
    /// `editor_col_at_x` resolves every visible glyph's own painted x
    /// position back to its own column. A naive uniform-monospace
    /// resolver fails this for any glyph painted after the bold/italic/
    /// `font_scale` spans, since their advances differ from a
    /// plain-glyph cell width.
    #[test]
    fn editor_col_at_x_round_trips_styled_line_with_scroll() {
        // Two independent `pango::Layout`s from the same font context —
        // mirrors production, where the "ground truth" paint layout
        // (`draw_editor`'s frame-scoped layout) and the click-time probe
        // layout (`editor_col_at_x`'s argument, possibly the cached
        // clone) are distinct GObjects. Using one shared, mutable layout
        // for both would let `editor_col_at_x`'s internal `set_text` /
        // `set_attributes` calls silently overwrite the "ground truth"
        // measurements taken later in the loop — which is exactly what
        // happened when this test was first written with one shared
        // layout: it kept passing even with `set_attributes(None)`
        // hard-coded into `editor_col_at_x`, because the corrupted
        // shared state made "expected" and "actual" agree for the wrong
        // reason. Two layouts closes that hole.
        let truth_layout = headless_pango_layout();
        let probe_layout = headless_pango_layout();
        let line = styled_line();
        let editor = Editor {
            id: "ed".into(),
            rect: Rect::new(0.0, 0.0, 900.0, 60.0),
            lines: vec![line.clone()],
            cursor: None,
            extra_cursors: Vec::new(),
            selection: None,
            extra_selections: Vec::new(),
            yank_highlight: None,
            scroll_top: 0,
            scroll_left: 3,
            total_lines: 1,
            max_col: 30,
            gutter_char_width: 4,
            is_active: true,
            show_active_bg: false,
            has_git_diff: false,
            has_breakpoints: false,
            diagnostic_gutter: HashMap::new(),
            code_action_lines: HashSet::new(),
            bracket_match_positions: Vec::new(),
            active_indent_col: None,
            tabstop: 4,
            cursorline: true,
            lightbulb_glyph: '!',
        };

        let cell_width = 9.0_f32;
        let line_height = 18.0_f32;
        let viewport = Rect::new(0.0, 0.0, 900.0, 60.0);
        let editor_layout = editor.layout(viewport, cell_width, line_height);

        // Pass 1 — paint with attrs (identical setup to `draw_editor`'s
        // per-line loop) into `truth_layout` and record every glyph's
        // real painted x position *before* touching `probe_layout` at
        // all, so nothing later can contaminate these measurements.
        truth_layout.set_text(&line.raw_text);
        let attrs = build_pango_attrs(&line.spans);
        truth_layout.set_attributes(Some(&attrs));

        let text_x_offset =
            editor_layout.text_bounds.x as f64 - editor.scroll_left as f64 * cell_width as f64;

        let glyph_click_xs: Vec<(usize, char, f64)> = line
            .raw_text
            .char_indices()
            .enumerate()
            .map(|(char_idx, (byte_idx, ch))| {
                let pos = truth_layout.index_to_pos(byte_idx as i32);
                let glyph_left_x = text_x_offset + pos.x() as f64 / pango::SCALE as f64;
                let glyph_width = (pos.width() as f64 / pango::SCALE as f64).max(2.0);
                // Click a quarter-glyph past the leading edge — solidly
                // inside the glyph, clear of boundary-rounding ambiguity.
                (char_idx, ch, glyph_left_x + glyph_width * 0.25)
            })
            .collect();

        // Pass 2 — resolve each recorded click through the function
        // under test, which owns (and mutates) `probe_layout`.
        for (char_idx, ch, click_x) in glyph_click_xs {
            let resolved = editor_col_at_x(&probe_layout, &line, &editor_layout, click_x as f32);
            assert_eq!(
                resolved, char_idx,
                "glyph '{ch}' (char {char_idx}) at x={click_x} resolved to col {resolved}"
            );
        }
    }

    #[test]
    fn editor_col_at_x_adds_segment_col_offset_for_wrap_continuation() {
        let pango_layout = headless_pango_layout();
        let mut line = styled_line();
        line.is_wrap_continuation = true;
        line.segment_col_offset = 12;

        let editor = Editor {
            id: "ed".into(),
            rect: Rect::new(0.0, 0.0, 900.0, 60.0),
            lines: vec![line.clone()],
            cursor: None,
            extra_cursors: Vec::new(),
            selection: None,
            extra_selections: Vec::new(),
            yank_highlight: None,
            scroll_top: 0,
            scroll_left: 0,
            total_lines: 1,
            max_col: 30,
            gutter_char_width: 4,
            is_active: true,
            show_active_bg: false,
            has_git_diff: false,
            has_breakpoints: false,
            diagnostic_gutter: HashMap::new(),
            code_action_lines: HashSet::new(),
            bracket_match_positions: Vec::new(),
            active_indent_col: None,
            tabstop: 4,
            cursorline: true,
            lightbulb_glyph: '!',
        };

        let cell_width = 9.0_f32;
        let viewport = Rect::new(0.0, 0.0, 900.0, 60.0);
        let editor_layout = editor.layout(viewport, cell_width, 18.0);

        // Click exactly at the text origin (col 0 of the visual segment)
        // — the resolved buffer column must be the segment offset.
        let resolved = editor_col_at_x(
            &pango_layout,
            &line,
            &editor_layout,
            editor_layout.text_bounds.x,
        );
        assert_eq!(resolved, 12);
    }

    /// When `editor_col_at_x`'s clamped byte index lands mid-character
    /// in a multibyte line (é / CJK / emoji), it must be snapped to a
    /// char boundary. Sweep the full width of a multibyte line and
    /// confirm every probe resolves without panicking.
    #[test]
    fn editor_col_at_x_multibyte_line_does_not_panic() {
        let pango_layout = headless_pango_layout();
        let mut line = styled_line();
        line.raw_text = "café 🎉 中文 done".into();
        line.spans = Vec::new();

        let editor = Editor {
            id: "ed".into(),
            rect: Rect::new(0.0, 0.0, 900.0, 60.0),
            lines: vec![line.clone()],
            cursor: None,
            extra_cursors: Vec::new(),
            selection: None,
            extra_selections: Vec::new(),
            yank_highlight: None,
            scroll_top: 0,
            scroll_left: 0,
            total_lines: 1,
            max_col: 30,
            gutter_char_width: 4,
            is_active: true,
            show_active_bg: false,
            has_git_diff: false,
            has_breakpoints: false,
            diagnostic_gutter: HashMap::new(),
            code_action_lines: HashSet::new(),
            bracket_match_positions: Vec::new(),
            active_indent_col: None,
            tabstop: 4,
            cursorline: true,
            lightbulb_glyph: '!',
        };

        let cell_width = 9.0_f32;
        let viewport = Rect::new(0.0, 0.0, 900.0, 60.0);
        let editor_layout = editor.layout(viewport, cell_width, 18.0);

        // Sweep x from before the line start to well past its end —
        // every probe must resolve without panicking.
        let mut x = editor_layout.text_bounds.x - 5.0;
        while x < editor_layout.text_bounds.x + 300.0 {
            let _ = editor_col_at_x(&pango_layout, &line, &editor_layout, x);
            x += 1.0;
        }
    }

    // ── Scrollbar paint ─────────────────────────────────────────────────
    //
    // "State-derived paint geometry" (quadraui/docs/TESTING.md coverage
    // taxonomy row 3): set `total_lines`/`max_col` to a known overflow (or
    // non-overflow) state, paint into a headless Cairo `ImageSurface`, and
    // assert the scrollbar track's translucent tint is present (or absent)
    // at the exact pixel `Editor::layout`'s own geometry predicts — the
    // same geometry `EditorLayout::hit_test` uses, so paint and click can't
    // drift apart. Mirrors `gtk/data_table.rs`'s pixel-readback harness.

    const SCROLL_TEST_W: i32 = 200;
    const SCROLL_TEST_H: i32 = 80;
    const SCROLL_TEST_CHAR_W: f64 = 8.0;
    const SCROLL_TEST_LINE_H: f64 = 16.0;

    fn rgb(c: Color) -> (u8, u8, u8) {
        (c.r, c.g, c.b)
    }

    /// Read an RGB triple from an ARgb32 surface at pixel (x, y). Same
    /// byte layout as `gtk/data_table.rs`'s test helper and `GtkDriver::pixel`.
    fn scroll_test_pixel(data: &[u8], stride: usize, x: i32, y: i32) -> (u8, u8, u8) {
        let off = y as usize * stride + x as usize * 4;
        (data[off + 2], data[off + 1], data[off])
    }

    fn blank_line(line_idx: usize) -> EditorLine {
        EditorLine {
            raw_text: String::new(),
            gutter_text: String::new(),
            spans: Vec::new(),
            line_idx,
            is_current_line: false,
            is_fold_header: false,
            folded_line_count: 0,
            git_diff: None,
            diff_status: None,
            diagnostics: Vec::new(),
            spell_errors: Vec::new(),
            is_breakpoint: false,
            is_conditional_bp: false,
            is_dap_current: false,
            is_wrap_continuation: false,
            segment_col_offset: 0,
            annotation: None,
            ghost_suffix: None,
            is_ghost_continuation: false,
            indent_guides: Vec::new(),
            colorcolumns: Vec::new(),
        }
    }

    /// Editor fixture at `SCROLL_TEST_W`x`SCROLL_TEST_H` (matching the
    /// surface size the tests below paint into) with no gutter, so the
    /// only geometry in play is the scrollbar reservation itself.
    fn scroll_test_editor(total_lines: usize, max_col: usize, num_lines: usize) -> Editor {
        Editor {
            id: "ed".into(),
            rect: Rect::new(0.0, 0.0, SCROLL_TEST_W as f32, SCROLL_TEST_H as f32),
            lines: (0..num_lines).map(blank_line).collect(),
            cursor: None,
            extra_cursors: Vec::new(),
            selection: None,
            extra_selections: Vec::new(),
            yank_highlight: None,
            scroll_top: 0,
            scroll_left: 0,
            total_lines,
            max_col,
            gutter_char_width: 0,
            is_active: true,
            show_active_bg: false,
            has_git_diff: false,
            has_breakpoints: false,
            diagnostic_gutter: HashMap::new(),
            code_action_lines: HashSet::new(),
            bracket_match_positions: Vec::new(),
            active_indent_col: None,
            tabstop: 4,
            cursorline: false,
            lightbulb_glyph: '\0',
        }
    }

    /// Paint `editor` into a fresh `theme.background`-filled surface and
    /// return the raw pixel buffer + stride. Mirrors `gtk/data_table.rs`'s
    /// identical test harness.
    fn scroll_test_paint(editor: &Editor, theme: &Theme) -> (Vec<u8>, i32) {
        let mut surface = ImageSurface::create(Format::ARgb32, SCROLL_TEST_W, SCROLL_TEST_H)
            .expect("create ImageSurface");
        {
            let cr = Context::new(&surface).expect("Context::new");
            let (br, bg, bb) = cairo_rgb(theme.background);
            cr.set_source_rgb(br, bg, bb);
            cr.paint().ok();

            let pango_layout = pangocairo::functions::create_layout(&cr);
            let pango_ctx = pango_layout.context();
            pango_ctx.set_font_description(&pango::FontDescription::from_string("Monospace 12"));
            let metrics = pango_ctx.metrics(None, None);

            draw_editor(
                &cr,
                &pango_layout,
                &metrics,
                editor,
                theme,
                SCROLL_TEST_CHAR_W,
                SCROLL_TEST_LINE_H,
            );
        }
        surface.flush();
        let stride = surface.stride();
        let data = surface.data().expect("surface data").to_vec();
        (data, stride)
    }

    /// [`scroll_test_paint`], but through [`draw_editor_with_options`] so
    /// tests can exercise [`EditorPaintOptions`].
    fn scroll_test_paint_with_options(
        editor: &Editor,
        theme: &Theme,
        options: EditorPaintOptions,
    ) -> (Vec<u8>, i32) {
        scroll_test_paint_with_v_scrollbar_w(editor, theme, options, None)
    }

    /// [`scroll_test_paint_with_options`], plus a scrollbar-width
    /// override via [`draw_editor_with_options_and_v_scrollbar_w`].
    fn scroll_test_paint_with_v_scrollbar_w(
        editor: &Editor,
        theme: &Theme,
        options: EditorPaintOptions,
        v_scrollbar_w: Option<f32>,
    ) -> (Vec<u8>, i32) {
        let mut surface = ImageSurface::create(Format::ARgb32, SCROLL_TEST_W, SCROLL_TEST_H)
            .expect("create ImageSurface");
        {
            let cr = Context::new(&surface).expect("Context::new");
            let (br, bg, bb) = cairo_rgb(theme.background);
            cr.set_source_rgb(br, bg, bb);
            cr.paint().ok();

            let pango_layout = pangocairo::functions::create_layout(&cr);
            let pango_ctx = pango_layout.context();
            pango_ctx.set_font_description(&pango::FontDescription::from_string("Monospace 12"));
            let metrics = pango_ctx.metrics(None, None);

            draw_editor_with_options_and_v_scrollbar_w(
                &cr,
                &pango_layout,
                &metrics,
                editor,
                theme,
                SCROLL_TEST_CHAR_W,
                SCROLL_TEST_LINE_H,
                options,
                v_scrollbar_w,
            );
        }
        surface.flush();
        let stride = surface.stride();
        let data = surface.data().expect("surface data").to_vec();
        (data, stride)
    }

    /// `gtk::draw_editor` must paint scrollbars when a buffer is taller
    /// than the viewport — a vertical scrollbar track in the reserved
    /// rightmost `char_width`-wide column; a buffer that fits must not
    /// tint that column at all.
    #[test]
    fn draw_editor_paints_vertical_scrollbar_when_buffer_overflows() {
        let theme = Theme::default();

        let overflowing = scroll_test_editor(50, 0, 5);
        let (data, stride) = scroll_test_paint(&overflowing, &theme);
        // Solidly inside the reserved v-scrollbar column (x in [192,200))
        // and mid-track vertically — see `Editor::layout`'s
        // `v_scrollbar_bounds` formula for why this pixel is in-track.
        let px = scroll_test_pixel(&data, stride as usize, 198, 40);
        assert_ne!(
            px,
            rgb(theme.background),
            "vertical scrollbar track should tint this pixel when total_lines overflows the viewport"
        );

        let fits = scroll_test_editor(3, 0, 3);
        let (data2, stride2) = scroll_test_paint(&fits, &theme);
        let px2 = scroll_test_pixel(&data2, stride2 as usize, 198, 40);
        assert_eq!(
            px2,
            rgb(theme.background),
            "no vertical scrollbar should paint when the buffer fits the viewport"
        );
    }

    /// The content clip must be **narrowed** by the reserved v-scrollbar
    /// column width, not merely overlaid afterwards — otherwise a
    /// translucent scrollbar track paints on top of glyphs the
    /// (unnarrowed) text loop already rendered underneath it, which is
    /// visible wherever the track/thumb isn't fully opaque. Fill every
    /// visible line with far more text than fits the viewport (so glyphs
    /// would reach all the way to the true right edge without the fix)
    /// and assert the reserved column's pixel is identical whether or
    /// not that text is present — the only way that can hold is if the
    /// text never reaches that column at all (narrowed out), since the
    /// scrollbar itself paints identically in both cases.
    #[test]
    fn draw_editor_scrollbar_column_unaffected_by_overflowing_text() {
        let theme = Theme::default();

        let mut with_text = scroll_test_editor(50, 0, 5);
        for line in with_text.lines.iter_mut() {
            // Comfortably wider than SCROLL_TEST_W under any reasonable
            // font metrics — text that would overflow past the reserved
            // scrollbar column if the clip were not narrowed.
            line.raw_text = "M".repeat(60);
        }
        let blank = scroll_test_editor(50, 0, 5);

        let (data_text, stride) = scroll_test_paint(&with_text, &theme);
        let (data_blank, stride2) = scroll_test_paint(&blank, &theme);
        assert_eq!(stride, stride2);

        // Same pixel the tests above assert is scrollbar-tinted.
        let px_text = scroll_test_pixel(&data_text, stride as usize, 198, 40);
        let px_blank = scroll_test_pixel(&data_blank, stride as usize, 198, 40);
        assert_eq!(
            px_text, px_blank,
            "scrollbar column pixel must be identical regardless of overflowing text — \
             the text loop should narrow around the reserved column instead of painting \
             glyphs the scrollbar then overlays (#968)"
        );
    }

    /// `paint_line_backgrounds` must narrow the cursorline/diff/DAP row
    /// fill to `text_bounds`, the same way the text clip is narrowed —
    /// otherwise the fill reaches the reserved v-scrollbar column and
    /// bleeds through the translucent scrollbar track. Paint a buffer
    /// with the cursorline active on the row under the scrollbar's
    /// mid-track pixel and assert that pixel is identical to the same
    /// pixel with no cursorline active at all: the only way a translucent
    /// track composited over two different row colours produces the same
    /// result is if neither row colour actually reaches that pixel.
    #[test]
    fn draw_editor_cursorline_background_does_not_bleed_into_scrollbar_column() {
        let theme = Theme::default();
        assert_ne!(
            theme.cursorline_bg, theme.background,
            "fixture assumption: cursorline_bg must differ from background for this test to \
             be meaningful"
        );

        let mut with_cursorline = scroll_test_editor(50, 0, 5);
        // Line at view index 2 covers y in [32, 48) — pixel y=40 below is
        // the same mid-track pixel the other scrollbar tests sample.
        with_cursorline.cursorline = true;
        with_cursorline.lines[2].is_current_line = true;

        let blank = scroll_test_editor(50, 0, 5);

        let (data_cursorline, stride) = scroll_test_paint(&with_cursorline, &theme);
        let (data_blank, stride2) = scroll_test_paint(&blank, &theme);
        assert_eq!(stride, stride2);

        let px_cursorline = scroll_test_pixel(&data_cursorline, stride as usize, 198, 40);
        let px_blank = scroll_test_pixel(&data_blank, stride as usize, 198, 40);
        assert_eq!(
            px_cursorline, px_blank,
            "scrollbar column pixel must be identical regardless of the cursorline background \
             on the row underneath it — the row fill should narrow around the reserved column \
             instead of bleeding into it"
        );
    }

    /// Passing `EditorPaintOptions { suppress_v_scrollbar: true, .. }`
    /// through `draw_editor_with_options` must stop the vertical
    /// scrollbar from painting at all, even though the buffer still
    /// overflows the viewport — this is the opt-out a host running a
    /// `Minimap`-as-scrollbar passes to avoid a redundant second
    /// affordance beside it. `draw_editor` (no options) must remain
    /// unaffected.
    #[test]
    fn draw_editor_with_options_suppress_v_scrollbar_paints_no_column() {
        let theme = Theme::default();
        let overflowing = scroll_test_editor(50, 0, 5);

        // Baseline: plain `draw_editor` still paints the column.
        let (data0, stride0) = scroll_test_paint(&overflowing, &theme);
        assert_ne!(
            scroll_test_pixel(&data0, stride0 as usize, 198, 40),
            rgb(theme.background)
        );

        let (data, stride) = scroll_test_paint_with_options(
            &overflowing,
            &theme,
            EditorPaintOptions {
                suppress_v_scrollbar: true,
            },
        );
        let px = scroll_test_pixel(&data, stride as usize, 198, 40);
        assert_eq!(
            px,
            rgb(theme.background),
            "suppress_v_scrollbar should stop the vertical scrollbar from painting even \
             though total_lines overflows the viewport"
        );
    }

    /// The GTK rasteriser's vertical scrollbar column honours a
    /// `v_scrollbar_w` override end-to-end — a wider override paints
    /// further out, matching the layout-level assertions in
    /// `primitives::editor`'s own tests.
    ///
    /// Viewport is `SCROLL_TEST_W` = 200px, `SCROLL_TEST_CHAR_W` = 8.0.
    /// The default column spans `[192, 200)`; a 14px override spans
    /// `[186, 200)`. `x = 188` falls in the gap between those two spans
    /// — plain text-area background at baseline, inside the track once
    /// widened.
    #[test]
    fn draw_editor_v_scrollbar_w_widens_painted_column() {
        let theme = Theme::default();
        let overflowing = scroll_test_editor(50, 0, 5);

        let (data0, stride0) = scroll_test_paint(&overflowing, &theme);
        let baseline_px = scroll_test_pixel(&data0, stride0 as usize, 188, 40);
        assert_eq!(
            baseline_px,
            rgb(theme.background),
            "x=188 sits outside the default 8px-wide column, [192, 200)"
        );

        let (data, stride) = scroll_test_paint_with_v_scrollbar_w(
            &overflowing,
            &theme,
            EditorPaintOptions::default(),
            Some(14.0),
        );
        let widened_px = scroll_test_pixel(&data, stride as usize, 188, 40);
        assert_ne!(
            widened_px,
            rgb(theme.background),
            "a Some(14.0) v_scrollbar_w should widen the painted track to cover x=188 ([186, 200))"
        );
    }

    /// Horizontal-overflow counterpart of the vertical scrollbar test:
    /// a line wider than the viewport must paint a horizontal scrollbar
    /// track in the reserved bottom `line_height`-tall row; a buffer
    /// whose longest line fits must not tint that row at all.
    #[test]
    fn draw_editor_paints_horizontal_scrollbar_when_line_overflows() {
        let theme = Theme::default();

        let overflowing = scroll_test_editor(3, 40, 3);
        let (data, stride) = scroll_test_paint(&overflowing, &theme);
        // Solidly inside the reserved h-scrollbar row (y in [64,80)) —
        // no v-scrollbar column here (total_lines fits), so the full
        // width is available for the horizontal track.
        let px = scroll_test_pixel(&data, stride as usize, 100, 70);
        assert_ne!(
            px,
            rgb(theme.background),
            "horizontal scrollbar track should tint this pixel when max_col overflows the viewport"
        );

        let fits = scroll_test_editor(3, 5, 3);
        let (data2, stride2) = scroll_test_paint(&fits, &theme);
        let px2 = scroll_test_pixel(&data2, stride2 as usize, 100, 70);
        assert_eq!(
            px2,
            rgb(theme.background),
            "no horizontal scrollbar should paint when every line fits the viewport"
        );
    }

    // ── Selection column math via `EditorSelection::cols_on` ────────────

    fn text_line(line_idx: usize, raw_text: &str) -> EditorLine {
        EditorLine {
            raw_text: raw_text.into(),
            ..blank_line(line_idx)
        }
    }

    /// One `Char` selection spanning buffer lines `[0, 2]` painted
    /// across a plain row, a wrapped-segment row, a ghost-continuation
    /// row, and a diff-padding row — the exact matrix
    /// `tests/conformance/editor.rs` proves against
    /// `EditorSelection::cols_on` directly, proven again here through a
    /// real Cairo paint so the backend's own call site is covered too.
    #[test]
    fn draw_editor_selection_respects_wrapped_ghost_and_diff_padding_rows() {
        let theme = Theme::default();

        let lines = vec![
            // Row 0: buffer line 0, plain, selection's own start line.
            text_line(0, "0123456789"),
            // Row 1: a wrap-continuation segment of buffer line 1,
            // starting at buffer column 5 — its own text is only 5
            // chars, entirely inside the selection.
            EditorLine {
                segment_col_offset: 5,
                is_wrap_continuation: true,
                ..text_line(1, "abcde")
            },
            // Row 2: the AI-ghost continuation of buffer line 1 — same
            // `line_idx` as row 1, but virtual, must never be selected.
            EditorLine {
                ghost_suffix: Some("ai suggestion".into()),
                ..text_line(1, "")
            },
            // Row 3: buffer line 2 (the selection's own end line), but a
            // diff-padding filler row — must never be selected either.
            EditorLine {
                diff_status: Some(DiffLine::Padding),
                ..text_line(2, "")
            },
        ];

        let mut editor = scroll_test_editor(4, 0, 4);
        editor.lines = lines;
        editor.selection = Some(EditorSelection {
            kind: SelectionKind::Char,
            start_line: 0,
            start_col: 0,
            end_line: 2,
            end_col: 10,
        });

        let (data, stride) = scroll_test_paint(&editor, &theme);
        let stride = stride as usize;
        let sample_x = 2; // just past the left text edge on every row
        let row_y = |row: i32| row * SCROLL_TEST_LINE_H as i32 + (SCROLL_TEST_LINE_H as i32 / 2);

        assert_ne!(
            scroll_test_pixel(&data, stride, sample_x, row_y(0)),
            rgb(theme.background),
            "row 0 (plain, selection's start line) should be tinted"
        );
        assert_ne!(
            scroll_test_pixel(&data, stride, sample_x, row_y(1)),
            rgb(theme.background),
            "row 1 (wrapped segment of a fully-selected line) should be tinted"
        );
        assert_eq!(
            scroll_test_pixel(&data, stride, sample_x, row_y(2)),
            rgb(theme.background),
            "row 2 (ghost continuation) must never be tinted by a selection"
        );
        assert_eq!(
            scroll_test_pixel(&data, stride, sample_x, row_y(3)),
            rgb(theme.diff_padding_bg),
            "row 3 (diff padding) must show only its diff background, not a selection tint"
        );
    }

    // ── Text/gutter vertical centring within a host-set row pitch ──────
    //
    // Mirrors `macos::editor::tests::body_text_centred_in_row_and_shares_baseline_with_gutter`:
    // paints the same digit glyph as both the gutter number and the
    // body text at two row pitches, and checks the ink shifts down by
    // half the pitch's slack over the font's own natural height, with
    // gutter and body sharing a baseline once the offset is applied.

    const CENTRE_TEST_W: i32 = 200;
    const CENTRE_TEST_ROW_PITCH: f64 = 24.0;

    /// `(ascent + descent, measured "7" width)` for "Monospace 12" —
    /// the real font metrics every `centre_test_paint` call below also
    /// resolves (same family/size), used here only to size the fixture.
    fn centre_test_metrics() -> (f64, f64) {
        let surface =
            ImageSurface::create(Format::ARgb32, CENTRE_TEST_W, 40).expect("create ImageSurface");
        let cr = Context::new(&surface).expect("Context::new");
        let pango_layout = pangocairo::functions::create_layout(&cr);
        let pango_ctx = pango_layout.context();
        pango_ctx.set_font_description(&pango::FontDescription::from_string("Monospace 12"));
        let metrics = pango_ctx.metrics(None, None);
        let natural_pitch = (metrics.ascent() + metrics.descent()) as f64 / pango::SCALE as f64;
        pango_layout.set_text("7");
        let char_w = pango_layout.pixel_size().0 as f64;
        (natural_pitch, char_w)
    }

    /// Paint a one-line editor (raw + gutter text both `"7"`) at row
    /// pitch `pitch`, returning the painted ARGB32 buffer + stride.
    fn centre_test_paint(pitch: f64, gutter_chars: usize) -> (Vec<u8>, i32) {
        let theme = Theme::default();
        let mut surface = ImageSurface::create(Format::ARgb32, CENTRE_TEST_W, pitch.ceil() as i32)
            .expect("create ImageSurface");
        {
            let cr = Context::new(&surface).expect("Context::new");
            let (br, bg, bb) = cairo_rgb(theme.background);
            cr.set_source_rgb(br, bg, bb);
            cr.paint().ok();

            let pango_layout = pangocairo::functions::create_layout(&cr);
            let pango_ctx = pango_layout.context();
            pango_ctx.set_font_description(&pango::FontDescription::from_string("Monospace 12"));
            let metrics = pango_ctx.metrics(None, None);
            pango_layout.set_text("7");
            let char_w = pango_layout.pixel_size().0 as f64;

            let mut line = blank_line(0);
            line.raw_text = "7".into();
            line.gutter_text = "7".into();
            let mut editor = scroll_test_editor(1, 1, 1);
            editor.lines = vec![line];
            editor.gutter_char_width = gutter_chars;
            editor.rect = Rect::new(0.0, 0.0, CENTRE_TEST_W as f32, pitch as f32);

            draw_editor_with_options_and_v_scrollbar_w(
                &cr,
                &pango_layout,
                &metrics,
                &editor,
                &theme,
                char_w,
                pitch,
                EditorPaintOptions::default(),
                None,
            );
        }
        surface.flush();
        let stride = surface.stride();
        let data = surface.data().expect("surface data").to_vec();
        (data, stride)
    }

    /// Scan `data` for the vertical extent of non-background ink inside
    /// `[x_start, x_end) × [y_start, y_end)` — GTK's counterpart to
    /// `macos::editor::tests::ink_vertical_extent`. `None` if the window
    /// contains no ink.
    fn centre_test_ink_extent(
        data: &[u8],
        stride: i32,
        x_start: i32,
        x_end: i32,
        y_start: i32,
        y_end: i32,
        bg: Color,
    ) -> Option<(i32, i32)> {
        const TOL: i32 = 24;
        let mut extent: Option<(i32, i32)> = None;
        for y in y_start..y_end {
            let has_ink = (x_start..x_end).any(|x| {
                let (r, g, b) = scroll_test_pixel(data, stride as usize, x, y);
                (r as i32 - bg.r as i32).abs() > TOL
                    || (g as i32 - bg.g as i32).abs() > TOL
                    || (b as i32 - bg.b as i32).abs() > TOL
            });
            if has_ink {
                extent = Some(match extent {
                    Some((top, _)) => (top, y),
                    None => (y, y),
                });
            }
        }
        extent
    }

    /// The AI ghost suggestion painted after the cursor sits on the same
    /// centred baseline as the typed text before it on that row.
    #[test]
    fn ai_ghost_text_after_cursor_shares_body_text_baseline() {
        use crate::primitives::editor::{CursorPos, CursorShape, EditorCursor};

        let mut theme = Theme::default();
        theme.ghost_text_fg = theme.foreground;
        let pitch = CENTRE_TEST_ROW_PITCH;
        let mut surface = ImageSurface::create(Format::ARgb32, CENTRE_TEST_W, pitch.ceil() as i32)
            .expect("create ImageSurface");
        let char_w;
        {
            let cr = Context::new(&surface).expect("Context::new");
            let (br, bg, bb) = cairo_rgb(theme.background);
            cr.set_source_rgb(br, bg, bb);
            cr.paint().ok();

            let pango_layout = pangocairo::functions::create_layout(&cr);
            let pango_ctx = pango_layout.context();
            pango_ctx.set_font_description(&pango::FontDescription::from_string("Monospace 12"));
            let metrics = pango_ctx.metrics(None, None);
            pango_layout.set_text("7");
            char_w = pango_layout.pixel_size().0 as f64;

            let mut line = blank_line(0);
            line.raw_text = "7".into();
            line.ghost_suffix = Some("7".into());
            let mut editor = scroll_test_editor(1, 1, 1);
            editor.lines = vec![line];
            editor.gutter_char_width = 0;
            editor.cursor = Some(EditorCursor {
                pos: CursorPos {
                    view_line: 0,
                    col: 1,
                },
                shape: CursorShape::Bar,
            });
            editor.rect = Rect::new(0.0, 0.0, CENTRE_TEST_W as f32, pitch as f32);

            draw_editor_with_options_and_v_scrollbar_w(
                &cr,
                &pango_layout,
                &metrics,
                &editor,
                &theme,
                char_w,
                pitch,
                EditorPaintOptions::default(),
                None,
            );
        }
        surface.flush();
        let stride = surface.stride();
        let data = surface.data().expect("surface data").to_vec();

        let body = centre_test_ink_extent(
            &data,
            stride,
            0,
            char_w.round() as i32 - 1,
            0,
            pitch as i32,
            theme.background,
        )
        .expect("typed glyph should paint ink");
        // Skip the 2px bar cursor at the start of the ghost cell.
        let ghost = centre_test_ink_extent(
            &data,
            stride,
            char_w.round() as i32 + 3,
            (2.0 * char_w).round() as i32,
            0,
            pitch as i32,
            theme.background,
        )
        .expect("ghost glyph should paint ink");
        assert!(
            (ghost.0 - body.0).abs() <= 1 && (ghost.1 - body.1).abs() <= 1,
            "ghost suggestion ink {ghost:?} should share the typed glyph's vertical extent {body:?}"
        );
    }

    #[test]
    fn draw_editor_body_text_centred_in_row_and_shares_baseline_with_gutter() {
        let theme = Theme::default();
        let (natural_pitch, char_w) = centre_test_metrics();
        assert!(
            natural_pitch < CENTRE_TEST_ROW_PITCH,
            "fixture needs a font natural line height ({natural_pitch}) shorter than the \
             row pitch ({CENTRE_TEST_ROW_PITCH}) to leave any slack to centre in",
        );

        let gutter_chars = 2usize;
        let gutter_w = gutter_chars as f64 * char_w;

        let (natural_data, natural_stride) = centre_test_paint(natural_pitch, gutter_chars);
        let natural = centre_test_ink_extent(
            &natural_data,
            natural_stride,
            gutter_w.round() as i32,
            (gutter_w + char_w).round() as i32,
            0,
            natural_pitch.ceil() as i32,
            theme.background,
        )
        .expect("body glyph should paint some ink at the natural pitch");

        let (wide_data, wide_stride) = centre_test_paint(CENTRE_TEST_ROW_PITCH, gutter_chars);
        let wide = centre_test_ink_extent(
            &wide_data,
            wide_stride,
            gutter_w.round() as i32,
            (gutter_w + char_w).round() as i32,
            0,
            CENTRE_TEST_ROW_PITCH as i32,
            theme.background,
        )
        .expect("body glyph should paint some ink at the wide pitch");

        let expected_shift = (CENTRE_TEST_ROW_PITCH - natural_pitch) / 2.0;
        let top_shift = wide.0 as f64 - natural.0 as f64;
        let bottom_shift = wide.1 as f64 - natural.1 as f64;
        assert!(
            (top_shift - expected_shift).abs() <= 2.0
                && (bottom_shift - expected_shift).abs() <= 2.0,
            "widening the row pitch from {natural_pitch} to {CENTRE_TEST_ROW_PITCH} should \
             move the body glyph down by half the added slack ({expected_shift}px), got top \
             {top_shift}px / bottom {bottom_shift}px (ink {natural:?} -> {wide:?})"
        );

        let gutter = centre_test_ink_extent(
            &wide_data,
            wide_stride,
            0,
            gutter_w.round() as i32,
            0,
            CENTRE_TEST_ROW_PITCH as i32,
            theme.background,
        )
        .expect("gutter glyph should paint some ink");
        assert_eq!(
            gutter, wide,
            "gutter number and body text (same glyph, \"7\") should share a baseline, got \
             gutter={gutter:?}, body={wide:?}"
        );
    }
}