Skip to content

editor: Land next in main (line decorations, mirrored gutters, spacers, gutter hit testing) - #3969

Closed
glani wants to merge 24 commits into
longbridge:mainfrom
glani:land-next
Closed

glani wants to merge 24 commits into
longbridge:mainfrom
glani:land-next

Conversation

@glani

@glani glani commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Description

This lands the next branch in main. next holds eight pull requests that were
reviewed and merged there between 2026-10-07 and 2026-10-19. None of them has shipped:
next was created for #3359, "targeted for the 0.8.0 milestone, where the
InputEditorStyle API break can be handled", but 0.8.0 to 0.9.1 were all released from
main, and the 0.8.0 milestone is still open.

This PR is next rebased onto current main, one commit per original PR:

Commit Original PR
input: Add line decorations with row backgrounds and gutter markers #3359
scrollbar: Let the vertical scrollbar sit on the left side #3416
editor: Support mirrored gutters for side-by-side diffs #3417
editor: Clip the text to its own side of the gutter #3426
editor: Expose read-only access to the display map #3465
editor: Add spacer rows to the display map #3466
editor: Add hit_test and gutter_bounds to the input state #3520
editor: Tell a custom context menu whether it was opened on the gutter #3521

Please merge with "Rebase and merge", not squash, so each commit stays linked to its
reviewed PR. Every commit builds on its own. The only changes to the reviewed code are
the ones needed to fit what main gained since next branched off (8d8cc67,
2026-10-05). They are listed below.

How the gutter is shared with #3704

#3704 added a strip of gutter decorations at the outer edge of the gutter. #3359 added a
marker slot next to the line numbers. #3417 models the gutter as columns ordered from the
text outward (gutter_order), and mirrors them when the gutter is on the right. The strip
becomes a fourth column, GutterColumn::Decorations, and is last in the default order.
The default layout is therefore the same as on main today:

gutter on the left (default):   [strip] gap [marker] [line numbers] [fold icons] | text
gutter on the right (#3417):    text | [fold icons] [line numbers] [marker] gap [strip]

The two features stay independent collections, as in #3040:

gutter_order can move the strip next to the text, as in VS Code or IntelliJ:
.gutter_order([GutterColumn::Decorations]).

Changes against main made while rebasing

Related: #3737 (GutterStyle, open) changes the same gutter geometry.

Public API

gpui-base (gpui_kit::base::input, re-exported by gpui_kit::component::input)

Line decorations (#3359):

  • #[non_exhaustive] pub enum GutterMarker { DiffAdded, DiffRemoved, DiffChanged, Conflict, Bookmark, Breakpoint, Custom { icon: SharedString, color: Hsla } }: the meaning of a gutter marker. Custom is an SVG asset path and a color, painted as given.
  • pub struct LineDecoration: a background, a marker, or both for one zero-based buffer row. new(row), with_background(color), with_marker(marker); readers row(), background(), marker().
  • pub trait LineDecorationProvider { fn line_decorations(&self, rows: Range<usize>, cx: &App) -> Vec<LineDecoration>; }: supplies the decorations of the visible rows, and is asked every frame.
  • pub struct LineDecorationCollection: one owner's handle, with set_provider, clear, dispose and has_provider.
  • EditorState::create_line_decorations_collection(&mut self, provider: Rc<dyn LineDecorationProvider>, cx: &mut Context<Self>) -> LineDecorationCollection: creates an independent collection.
  • InputBaseState::row_bounds(&self, row: usize) -> Option<Bounds<Pixels>>: the window-space band a laid-out buffer row occupies, across its soft wraps and below inline-completion ghost lines.
  • pub type GutterMarkerRenderer = Rc<dyn Fn(&GutterMarker) -> AnyElement>.
  • InputEditorStyle::{with_gutter_marker_renderer, gutter_marker_renderer, with_gutter_marker_size, gutter_marker_size, with_gutter_marker_gap, gutter_marker_gap}: how markers are presented. Size and gap default to zero, which reserves no slot.
  • InputExtras::line_decorations and InputExtras::has_line_decorations: defaulted.

Scrollbar placement (#3416):

  • ScrollbarPlacement { BottomRight, BottomLeft, TopRight, TopLeft }: defaults to BottomRight; is_left(), is_top().
  • Scrollbar::placement(self, placement: ScrollbarPlacement) -> Self.
  • InputBaseState::scrollbar_placement(self, placement) -> Self and set_scrollbar_placement(&mut self, placement, cx): where the editor's scrollbars sit.
  • New in this rebase: EditorScrollbarContext::placement(&self) -> ScrollbarPlacement: the placement, for a scrollbar supplied with set_scrollbar_renderer.

Mirrored gutters (#3417):

  • InputBaseState::gutter_side(self, side: Side) -> Self and set_gutter_side(&mut self, side: Side, cx): which side of the text the gutter is on; defaults to Side::Left.
  • InputPresentation::gutter_side(&self) -> Side.
  • #[non_exhaustive] pub enum GutterColumn { FoldIcons, LineNumbers, Markers, Decorations }: a column of the gutter. New in this rebase: Decorations, the strip of editor: Add gutter and overview ruler decorations #3704, and #[non_exhaustive].
  • InputBaseState::gutter_order(self, columns: impl IntoIterator<Item = GutterColumn>) -> Self and set_gutter_order(&mut self, columns, cx): the columns from the text outward. Defaults to [FoldIcons, LineNumbers, Markers, Decorations], the current layout.

Display map (#3465, #3466):

  • DisplayMap::version(&self) -> usize: an equality-comparable invalidation version. (InputBaseState::display_map() is already on main.)
  • Spacer::below(line, rows) and Spacer::above(line, rows); Spacer::with_background(color); readers line, rows, is_above, background: blank rows above or below a buffer line.
  • trait SpacerProvider { fn spacers(&self, lines: Range<usize>, cx: &App) -> Vec<Spacer>; }.
  • InputBaseState<EditorMode>::set_spacer_provider(&mut self, provider: Option<Rc<dyn SpacerProvider>>, cx) and refresh_spacers(&mut self, cx).
  • DisplayMap::is_spacer_row(&self, row: usize) -> bool.

Hit testing and the gutter menu (#3520, #3521):

  • InputBaseState::hit_test(&self, position: Point<Pixels>) -> Option<InputHit>: what a window point is over, as last painted.
  • InputBaseState::gutter_bounds(&self) -> Option<Bounds<Pixels>>: the gutter's painted bounds.
  • pub struct InputHit: area(), row(), is_spacer(), offset(), is_gutter(), gutter_column().
  • #[non_exhaustive] pub enum InputHitArea { Text { offset: usize }, Gutter { column: Option<GutterColumn> } }.
  • InputBaseState::gutter_context_menu_moves_cursor(self, moves: bool) -> Self and set_gutter_context_menu_moves_cursor: true by default. With false, the selection is kept while the gutter's menu is open.
  • #[doc(hidden)] InputBaseState::on_context_menu_with_hit(...): how Input hands the hit to its builder.

gpui-component (gpui_kit::component::input)

  • Re-exports GutterMarker, LineDecoration, LineDecorationCollection, LineDecorationProvider, GutterColumn, Spacer, SpacerProvider, InputHit, InputHitArea, InputContextMenuCapabilities. Input and Editor project a themed marker renderer: the marker is 90% of the font size and the gap 30%.
  • ScrollbarPlacement is also available from gpui_kit::component::scroll.
  • Input::context_menu_with(self, f: impl Fn(NativeMenu, InputContextMenuCapabilities, Option<InputHit>, &mut Window, &mut App) -> NativeMenu + 'static) -> Self and Editor::context_menu_with: a menu builder that knows what was right-clicked. context_menu keeps its signature.
  • default_context_menu(menu: NativeMenu, capabilities: InputContextMenuCapabilities) -> NativeMenu: the built-in items, for the clicks a custom builder leaves alone.

Breaking Changes

InputEditorStyle is now #[non_exhaustive] (#3359), and its gutter marker settings are
private fields behind builders. Outside gpui-base, struct literals no longer compile,
including those that end in ..Default::default():

-let style = InputEditorStyle {
-    foreground,
-    caret,
-    ..Default::default()
-};
+let mut style = InputEditorStyle::default();
+style.foreground = foreground;
+style.caret = caret;

Reading and assigning the existing fields is unchanged.

Layout:

  • While a line decoration collection has a provider and line numbers are shown, the
    styled editor's gutter is wider by the marker slot (120% of its font size), and the text
    starts that much further right.
  • Line numbers are placed by their shaped width instead of being padded with spaces
    (editor: Support mirrored gutters for side-by-side diffs #3417). In proportional fonts they now line up against the text.

Editors that use none of these features keep their current layout. InputExtras gains
only defaulted methods.

How to Test

Run on Linux (aarch64). The first four were run again on the current head (7597f792,
main at c0992262 merged in, Rust 1.98.0); the rest were run on the head before that
merge (cef53ccb, Rust 1.95.0):

  • cargo check --locked -p gpui-base --all-targets
  • cargo check --locked -p gpui-component -p example-editor-spacers -p example-editor-gutter-menu
  • cargo test --locked -p gpui-base --lib: 1815 passed.
  • cargo test --locked -p gpui-component --lib --features test-support: 819 passed.
  • RUSTFLAGS="-D warnings" cargo test --locked -p gpui-component-story --features gpui-component-story/test-support --lib: 29 passed.
  • RUSTFLAGS="-D warnings" and the CI test command with --no-run (workspace, --features gpui-component-story/test-support, examples excluded): builds.
  • typos on the changed files.
  • node examples/js_story/fixtures/verify-coverage.mjs
  • python3 script/check-ai docs
  • cargo fmt --all --check: clean except crates/base/examples/showcase/components/text_view.rs, which is also unformatted on main.

Each commit was also checked to parse and to be formatted on its own.

In the story (cargo run):

  • Editor › Decorations: editor: Add gutter and overview ruler decorations #3704's strip, the line markers and the row backgrounds side by
    side, with the strip outermost.
  • Editor Diff: mirrored gutters, spacers and the left scrollbar with its overview ruler.
  • cargo run -p example-editor-spacers and cargo run -p example-editor-gutter-menu.

Checklist

  • I have read the CONTRIBUTING document and followed the guidelines.
  • Reviewed the changes in this PR and confirmed AI generated code (If any) is accurate.
  • Passed cargo run for story tests related to the changes. (Not yet run after the rebase; to be checked on macOS before this leaves draft.)
  • Tested macOS, Windows and Linux platforms performance (if the change is platform-specific): not platform-specific.

cc @huacnlee, who created next and reviewed these. cc @bcl-dev, author of #3704, which
now shares the gutter with this.

glani and others added 2 commits November 13, 2026 21:10
…e#3416)

The vertical scrollbar is hard-coded to the right edge and the
horizontal one to the bottom. In a side-by-side diff the left pane's
scrollbar belongs on its outer (left) edge, so the two panes mirror each
other.

This adds `ScrollbarPlacement`, one value for both axes, set with one
call — `Scrollbar::placement`, and `scrollbar_placement` /
`set_scrollbar_placement` on the editor state:

| | vertical | horizontal |
| --- | --- | --- |
| `BottomRight` (default, unchanged) | right | bottom |
| `BottomLeft` | left | bottom |
| `TopRight` | right | top |
| `TopLeft` | left | top |

Each axis follows its half of the placement: the track sits on that
edge, the thumb and its hit area are anchored to it, and the bar slides
in from that edge. When both bars show, the vertical one keeps its full
height and the horizontal one stops short of it — at its start when the
vertical bar is on the left, at its end when it is on the right. A
single-axis scrollbar uses only its own half. The editor reserves no
room for its horizontal bar at the bottom today, so at the top it
overlays the first line the same way. Nothing changes by default.

Targets `next`: it is the first half of a mirrored side-by-side diff
whose second half, longbridge#3417, builds on longbridge#3359's gutter markers, which are on
`next`.

| Before | After |
| ------ | ----- |
| <img width="800" alt="before"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/before.png"
/> | <img width="800" alt="scrollbar-left"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/scrollbar-left.png"
/> |

The four placements (`ScrollbarMode::Always`); the story switches
Dataset and Placement from one Options menu (`d8057f92`):

<img width="1000" alt="scrollbar placements, light"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/scrollbar-placement-light.png"
/>

<img width="1000" alt="scrollbar placements, dark"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/scrollbar-placement-dark.png"
/>

`gpui_base` (re-exported by `gpui_component`, also from
`gpui_component::scroll`):

- `ScrollbarPlacement { BottomRight, BottomLeft, TopRight, TopLeft }` —
default `BottomRight`; `is_left()` (vertical bar on the left),
`is_top()` (horizontal bar at the top).
- `Scrollbar::placement(mut self, placement: ScrollbarPlacement) ->
Self`.
- `InputBaseState::scrollbar_placement(mut self, placement:
ScrollbarPlacement) -> Self` — builder for the editor's scrollbars.
- `InputBaseState::set_scrollbar_placement(&mut self, placement:
ScrollbarPlacement, cx: &mut Context<Self>)` — replaces the whole
placement at runtime.

- `cargo test -p gpui-base --lib scrollbar`: the `Scrollbar` harness
clicks and drags on each placement — the vertical track and thumb on the
left, the horizontal track and thumb at the top, the horizontal track
starting after a left bar and ending before a right one with both bars
at the top, a thumb drag and a track click moving the offset the right
way — and `visibility_translation_moves_toward_the_nearest_edge` covers
all four placements on both axes; an editor layout test for `TopLeft`.
Each fails with its code reverted.
- `cargo run -p gpui-component-story -- scrollbar`, then Options →
Placement.

- [x] I have read the [CONTRIBUTING](../CONTRIBUTING.md) document and
followed the guidelines.
- [x] Reviewed the changes in this PR and confirmed AI generated code
(If any) is accurate.
- [x] Passed `cargo run` for story tests related to the changes.
- [x] Tested macOS, Windows and Linux platforms performance (if the
change is platform-specific)

---------

Co-authored-by: Jason Lee <huacnlee@gmail.com>
@glani
glani marked this pull request as ready for review November 13, 2026 21:25
@huacnlee

Copy link
Copy Markdown
Member

💡 Needs the owner's call: lands eight already-reviewed next PRs, but it is a breaking change (InputEditorStyle becomes #[non_exhaustive]) and needs "Rebase and merge".

Reviewed head 2f52ea0 (8 commits on top of current main, one per original PR #3359, #3416, #3417, #3426, #3465, #3466, #3520, #3521).

What I checked

For the owner to decide

  • Timing: the InputEditorStyle break fits the biweekly minor release, not a patch.
  • Merge method: the description asks for rebase-merge to keep each commit linked to its reviewed PR; the repo normally squashes.
  • Not verified here: story/visual run after the rebase (the author also notes it is pending on macOS). Test matrix CI was still running at review time.

🤖 Noop (reviewer) · AI agent acting for @huacnlee

glani and others added 6 commits November 13, 2026 21:41
)

Builds on longbridge#3416 (`ScrollbarPlacement`, merged into `next`) and longbridge#3359's
gutter markers.

In a side-by-side diff, both gutters can face the center, so the line
numbers of corresponding lines sit next to each other across the divider
and can be compared directly. The editor's gutter is always on the left
of the text today, so the left pane cannot do that.

This adds `gutter_side(Side)` / `set_gutter_side` to the editor state
for the left pane of such a diff, default `Side::Left` (unchanged). On
the right the gutter is mirrored: the same columns, in the same order
counted from the text, with the line numbers aligned toward it. The text
and gutter x offsets are computed once per layout and used for painting,
hit testing, IME bounds and scroll-into-view. A scrollbar on the
gutter's side stays outermost. With the gutter on the right and the
scrollbar on the left — the left pane's outer edge — the text keeps
clear of the scrollbar's whole track: its effective width, the active
thumb included, less the editor's left padding, at least the usual 10 px
margin; that one reservation sets the text origin, width, wrap width and
scroll size.

Line numbers are placed by their shaped width rather than padded with
spaces: in a proportional font a space is about a third of a digit, so
the default left gutter left right-aligned numbers ragged and 6–11 px
short of the text; they now line up against it on either side. `Editor`
puts its narrow padding on the gutter's side.

`gutter_order([GutterColumn])` orders the gutter's columns from the text
outward, on either side: the default is `[FoldIcons, LineNumbers,
Markers]` (unchanged); `[FoldIcons, Markers, LineNumbers]` puts a diff's
change markers between the text and the line numbers, as IntelliJ's diff
does. A column left out follows the listed ones in its default order.

The **Editor Diff** story (`70b271ad`, @huacnlee) shows original and
modified source with change markers; its Options menu switches between
both gutters on the left and center-facing gutters, and optionally puts
the markers before the line numbers. The two panes scroll together, by
wheel and by dragging either scrollbar. The ordinary Editor story is
unchanged.

| Before | After |
| ------ | ----- |
| <img width="800" alt="scrollbar-left"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/scrollbar-left.png"
/> | <img width="800" alt="mirrored"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/mirrored.png"
/> |

A side-by-side diff with changed lines marked; the left pane uses
`.scrollbar_placement(ScrollbarPlacement::BottomLeft).gutter_side(Side::Right)`,
mirrored:

| Both gutters on the left | Mirrored |
| ------------------------ | -------- |
| <img width="800" alt="both gutters on the left"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/gutter-before.png"
/> | <img width="800" alt="mirrored"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/gutter-mirrored.png"
/> |

The columns in IntelliJ's order,
`.gutter_order([GutterColumn::FoldIcons, GutterColumn::Markers,
GutterColumn::LineNumbers])` on both panes — without and with folding
(an empty fold column here):

| IntelliJ's order | With folding |
| ---------------- | ------------ |
| <img width="800" alt="IntelliJ's order"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/gutter-intellij.png"
/> | <img width="800" alt="IntelliJ's order with folding"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/gutter-intellij-fold.png"
/> |

`gpui_base` (re-exported by `gpui_component`):

- `InputBaseState::gutter_side(mut self, side: Side) -> Self` — builder:
which side of the text the gutter is drawn on; default `Side::Left`,
`Side::Right` for the left pane of a side-by-side diff.
- `InputBaseState::set_gutter_side(&mut self, side: Side, cx: &mut
Context<Self>)` — the same, at runtime.
- `InputPresentation::gutter_side(&self) -> Side` — the side the
editor's gutter sits on.
- `GutterColumn { FoldIcons, LineNumbers, Markers }` — a column of the
gutter.
- `InputBaseState::gutter_order(mut self, columns: impl
IntoIterator<Item = GutterColumn>) -> Self` / `set_gutter_order(&mut
self, columns, cx: &mut Context<Self>)` — the columns from the text
outward; default `[FoldIcons, LineNumbers, Markers]`; a column left out
follows in its default order, a repeat is ignored.

- `cargo test -p gpui-base --lib`: new tests for the text and gutter
origins with an unchanged wrap width, the mirrored fold icons and
columns, the scrollbar staying outermost (left/left, right/left,
right/right), clicks in the text and in the gutter on both sides, caret
/ IME / `range_to_bounds` / selection-path x including a long line
scrolled clear of the gutter, a right-side case in the existing
gutter-bounds test, every gutter column — markers included — mirrored to
0.01 px for all six orders with folding on and off, the order normalised
and counted from the text on both sides, clicks on the fold icon and the
line number in every side/order combination, `Editor` keeping its
gutter-side padding, and the text clear of the whole track of a left
scrollbar with zero padding and with a wider themed track. Each fails
with its code reverted.
- `cargo test -p gpui-component-story --lib editor_diff`: layout
switching keeps both sources, and the panes stay aligned on wheel input
and while either scrollbar is dragged.
- `cargo run -p gpui-component-story -- 'Editor Diff'`, then Options.

- [x] I have read the [CONTRIBUTING](../CONTRIBUTING.md) document and
followed the guidelines.
- [x] Reviewed the changes in this PR and confirmed AI generated code
(If any) is accurate.
- [x] Passed `cargo run` for story tests related to the changes.
- [x] Tested macOS, Windows and Linux platforms performance (if the
change is platform-specific)

---------

Co-authored-by: Jason Lee <huacnlee@gmail.com>
The editor's gutter is painted over the horizontally scrolling text, and
its background is what hides the text underneath. That background is not
always opaque: a disabled editor paints the editor background at half
opacity, and a theme may give `editor.background` or
`editor.gutter.background` an alpha. The text then shows through the
gutter, under the line numbers.

With the gutter on the right (longbridge#3417) every line longer than the pane
runs under the gutter, so in a side-by-side diff it shows on most rows.
With a gutter on the left it shows once the text is scrolled
horizontally.

This clips what belongs to the text area to its own side of the gutter —
glyph backgrounds, indent guides, range decorations, selections and
search matches, the hover highlight, document colors, the text and its
ghost lines, inline elements, the carets and the inline completion
suffix — instead of relying on the gutter's background to cover it. Only
the edge facing the gutter moves; the other edges stay those of the
current content mask. Line decoration backgrounds and the active line
keep spanning the gutter, and the gutter keeps its background. Nothing
changes for an editor without line numbers.

A side-by-side diff in a dark theme, the left pane with
`.gutter_side(Side::Right)`:

| Before | After |
| ------ | ----- |
| <img width="620" alt="before: the text shows through the gutter"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/clip-text-before.png"
/> | <img width="620" alt="after: the text ends at the gutter"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/clip-text-after.png"
/> |

- `cargo test -p gpui-base --lib
the_text_is_clipped_to_its_side_of_the_gutter`: a decorated text
scrolled under the gutter, for a gutter on the left and on the right
with either scrollbar placement; it reads what was painted
(`painted_quads`, `painted_underlines`) and fails without the clip.
- In an editor with `.gutter_side(Side::Right)` whose editor background
is not opaque (for example a disabled one), type a line longer than the
pane: the line numbers sit on the gutter's background, not over the
text.

- [x] I have read the [CONTRIBUTING](../CONTRIBUTING.md) document and
followed the guidelines.
- [x] Reviewed the changes in this PR and confirmed AI generated code
(If any) is accurate.
- [x] Passed `cargo run` for story tests related to the changes.
- [x] Tested macOS, Windows and Linux platforms performance (if the
change is platform-specific)

---------

Co-authored-by: Jason Lee <huacnlee@gmail.com>
Applications building synchronized editors, minimaps, or custom
coordinate-based views need access to the editor's complete text
projection, including lines outside the viewport.
`InputBaseState::display_map()` now returns a shared reference to the
editor-owned `DisplayMap`, exposing its existing public buffer/display
coordinate and row queries while the state owns all updates.

`DisplayMap::version()` changes on edits, rewrapping, and fold changes.
Consumers can compare versions on the same map to invalidate cached
queries without adding an `InputEvent` variant. Queries stay on
`DisplayMap`; the four proposed state-level forwarding methods are
omitted.

The map reflects the whole prepared buffer using the latest prepared
layout parameters. It excludes inline completion ghost lines: multi-line
inline completion shifts painted rows without changing the text map or
its version. Use `row_bounds` for the actual geometry of visible lines.
Base and Component documentation explain these semantics in English and
Chinese.

Both types are already re-exported through `gpui_kit::base::input` and
`gpui_kit::component::input`.

- `InputBaseState::display_map(&self) -> &DisplayMap` — read-only access
to the state-owned map for row queries and buffer/display coordinate
conversions.
- `DisplayMap::version(&self) -> usize` — an equality-comparable
invalidation version for the same map; it may wrap.

```sh
cargo test -p gpui-base --lib the_display_row_map_is_what_the_layout_draws
cargo test -p gpui-base --lib rows_below_a_multiline_inline_completion_are_bounded_where_painted
cargo fmt -p gpui-base --check
```

All three commands passed locally, along with `git diff --check`.

The mapping test exercises the public accessor, coordinate round trips,
wrapped and folded lines, offscreen queries, and version changes on
rewrapping, folding, and edits while staying stable on scroll. The
inline completion test verifies that ghost lines move painted row bounds
while the text map and its version remain unchanged.

AI-assisted: follow-up API, documentation, and test changes made with
Codex.

---------

Co-authored-by: Jason Lee <huacnlee@gmail.com>
Two editors shown side by side stay level only while no line wraps: with
soft wrap on, the same paragraph takes more rows on one side than on the
other, and every pair below it drifts. This adds **spacer rows** to the
display map — blank rows above or below a buffer line, with no line
number, no caret and no decoration, as Zed's side-by-side diff has them
(`Block::Spacer`) — and a provider to say where they go. Builds on longbridge#3465
(`display_map() -> &DisplayMap`, a public `DisplayMap::version()`), now
in `next`; the spacer rows are read through that map.

They are a layer of the display map above folding, its inverse, so every
row keeps one line height and the scroll height, `scroll_to` and
`row_bounds` count them. Selections, search matches, document colours,
range decorations, line decoration bands and markers, fold icons, indent
guides and inline tokens pass them by; the caret steps over them; a
click on one lands on the row of text beside it; a block selection skips
them. The text, the glyph backgrounds, the line numbers and the active
line are now painted at `row_extents()`, the one place spacers and ghost
lines are accounted for, instead of each keeping a running sum — the
same tops when there are no spacers. Ghost lines of an inline completion
stand right below the cursor row's text, before the spacers below it,
and the spacer backgrounds move down with them.

On that public `DisplayMap`, spacer rows are display rows:
`display_row_count()` counts them,
`buffer_line_to_display_row_range(line)` holds only the rows of the
line's text, `display_row_to_buffer_line(row)` and
`display_pos_to_buffer_pos` read a spacer row as the line it stands
beside, and `is_spacer_row(row)` tells the two apart. `version()` moves
when the spacers change, so a cache of rows keyed on it stays valid; an
answer equal to the spacers already shown leaves it as it was. The
editor asks the provider again by the rows alone (an edit, a rewrap, a
fold, or `refresh_spacers`), so an answer never asks anew, and
refreshing whenever the other side's version changes settles.

The Editor Diff story gains a "Wrap long lines" option that pads both
sides level, and `examples/editor_spacers` shows two versions of a prose
text padded level, a paragraph only one has standing beside a filled
block.

This changes Base: the display map and the editor's layout live there.

The Editor Diff story with Options › Wrap long lines: line 38 wraps to
three rows on the left and seven on the right.

| Soft wrap alone | With spacer rows |
| --------------- | ---------------- |
| <img width="620" alt="soft wrap alone: below line 38 the right side
runs four rows lower"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/spacer-rows-story-before.png"
/> | <img width="620" alt="with spacer rows: every line starts level on
both sides"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/spacer-rows-story-after.png"
/> |

`examples/editor_spacers`, at 900 and at 640 pixels wide:

| 900 px | 640 px |
| ------ | ------ |
| <img width="620" alt="the example at 900 pixels: paragraphs padded
level"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/spacer-rows-example.png"
/> | <img width="440" alt="the example at 640 pixels: rewrapped and
still level"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/spacer-rows-example-narrow.png"
/> |

`gpui_kit::component::input`)

- `Spacer::below(line: usize, rows: usize) -> Spacer` /
`Spacer::above(line: usize, rows: usize) -> Spacer` — blank rows below
or above a zero-based buffer line.
- `Spacer::with_background(self, color: Hsla) -> Spacer` — fill the
rows, gutter included; `Spacer::line`, `rows`, `is_above`, `background`
read them back.
- `trait SpacerProvider { fn spacers(&self, lines: Range<usize>, cx:
&App) -> Vec<Spacer>; }` — asked for every line when the rows move and
on `refresh_spacers`.
- `InputBaseState<EditorMode>::set_spacer_provider(&mut self, provider:
Option<Rc<dyn SpacerProvider>>, cx: &mut Context<Self>)`.
- `InputBaseState<EditorMode>::refresh_spacers(&mut self, cx: &mut
Context<Self>)` — ask again at the next layout, when something the
answer depends on changed elsewhere (another editor's rows).
- `DisplayMap::is_spacer_row(&self, row: usize) -> bool` — on the map
`InputBaseState::display_map()` returns.

- `cargo test -p gpui-base --lib spacer`
(`spacers_are_asked_for_when_the_rows_move` also covers the version) and
the four tests named for the caret, bands, ranges and gutters
(`the_caret_and_a_click_never_stand_on_a_spacer_row`,
`bands_markers_and_fold_icons_stand_on_text_rows_only`,
`ranges_are_laid_out_on_text_rows_only`,
`spacers_beside_a_right_gutter_and_a_left_scroll_bar`), each with soft
wrap on and off; `cargo test -p gpui-component-story --lib
wrapped_sides_are_padded_level`.
- `cargo run`, Editor Diff, Options › Wrap long lines: narrow the
window; every pair of lines starts level, the line numbers only beside
text.
- `cargo run -p example-editor-spacers`.

- [x] I have read the [CONTRIBUTING](../CONTRIBUTING.md) document and
followed the guidelines.
- [x] Reviewed the changes in this PR and confirmed AI generated code
(If any) is accurate.
- [ ] Passed `cargo run` for story tests related to the changes.
- [ ] Tested macOS, Windows and Linux platforms performance (if the
change is platform-specific)

---------

Co-authored-by: Jason Lee <huacnlee@gmail.com>
…#3520)

An application that puts something of its own in the editor's gutter — a
menu for a line, a bookmark or breakpoint toggle, a tooltip over a
marker — has to know what a point is over: the gutter or the text, which
column of the gutter, and which buffer row. Today it can only re-derive
the gutter's layout. This adds two read-only queries on the input state,
`hit_test` and `gutter_bounds`.

`InputHit` keeps its fields private, as `InputContextMenuCapabilities`
does, so more can be told about a point later without breaking its
readers.

Nothing an input does changes: no handler reads them. It follows the
shape `row_bounds` and `display_map()` set — the state answers, the
application decides. Both are exported from `gpui_kit::base::input` and
`gpui_kit::component::input`; the editor page has a paragraph and an
example, in English and Chinese.

`row()` and `is_spacer()` follow the spacer rows of longbridge#3466, now in
`next`; in the gutter, the ghost lines of an inline completion, which
stand between a row's text and the spacers below it, are beside no row.

`gpui_kit::component::input`)

- `InputBaseState::hit_test(&self, position: Point<Pixels>) ->
Option<InputHit>` — what a point in window coordinates is over, as last
painted; `None` before the first paint and outside the input. On every
input state (`InputState`, `TextareaState`, `EditorState`).
- `InputBaseState::gutter_bounds(&self) -> Option<Bounds<Pixels>>` — the
gutter's painted bounds, from the text's margin to the outer edge of the
padding; `None` before the first paint and without a gutter.
- `pub struct InputHit` (`Clone, Copy, Debug, PartialEq, Eq`; fields
private) — what a point is over, read through:
- `InputHit::area(&self) -> InputHitArea` — the text or the gutter,
below;
- `InputHit::row(&self) -> Option<usize>` — the buffer row beside the
point; in the gutter `None` above the first row and below the last;
- `InputHit::is_spacer(&self) -> bool` — the point is on one of that
row's spacer rows (longbridge#3466), read as a click reads it;
- `InputHit::offset(&self) -> Option<usize>`,
`InputHit::is_gutter(&self) -> bool`, `InputHit::gutter_column(&self) ->
Option<GutterColumn>` — shorthands.
- `#[non_exhaustive] pub enum InputHitArea { Text { offset: usize },
Gutter { column: Option<GutterColumn> } }` — `Text { offset }`, the
offset a click there places the caret at, or `Gutter { column }`, `None`
in the margin or padding.

- `hit_test_tells_the_gutter_from_the_text` — each column of the gutter
on either side (longbridge#3417), the margin, below the last row, the text at the
caret's offset, outside the input, before the first paint.
- `hit_test_puts_a_spacer_row_beside_its_line` — above and below a row,
in the gutter and in the text, and below the ghost lines of an inline
completion.

Each goes red with its protection removed: the gutter bounds not stored
(both), the spacer rows, or the ghost lines, left out of `row_at` (the
second), no column found (the first).

- `cargo test -p gpui-base --lib -- input::` (361 passed)
- `cargo clippy -p gpui-base --lib --tests -- -D warnings`, nothing in
the files touched

- [x] I have read the [CONTRIBUTING](../CONTRIBUTING.md) document and
followed the guidelines.
- [x] Reviewed the changes in this PR and confirmed AI generated code
(If any) is accurate.
- [ ] Passed `cargo run` for story tests related to the changes.
- [x] Tested macOS, Windows and Linux platforms performance (if the
change is platform-specific)

---------

Co-authored-by: Jason Lee <huacnlee@gmail.com>
longbridge#3521)

A right-click on a line number opens the text's menu today — Cut, Copy,
Paste — and moves the caret there. An editor that wants a menu about the
line clicked — bookmark it, toggle a breakpoint, accept a change in a
diff — has no way to tell that the click was on the gutter, nor which
row. This tells the menu, and keeps every existing builder working as it
does.

`examples/editor_gutter_menu` shows it: a line number's menu bookmarks
(a `GutterMarker::Bookmark` through a line decoration provider), selects
or copies the line, and the text keeps the usual menu. The input page
and the editor page describe it, in English and Chinese.

Stacked on longbridge#3520 (`hit_test`), whose two commits the diff here still
shows; the diff to review is the last three commits. Once longbridge#3520 lands it
will be rebased onto `next`.

| a line number's menu, the selection kept | after Bookmark Line 6 | the
text's menu |
|---|---|---|
| <img width="420" alt="a line number's menu, the selection kept"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/gutter-menu-on-a-line-number.png"
/> | <img width="420" alt="a bookmark beside line 6 after Bookmark Line
6"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/gutter-menu-bookmark-added.png"
/> | <img width="420" alt="the text's usual menu"
src="https://raw.githubusercontent.com/GigLaboCom/gpui-component/pr-assets/screenshots/gutter-menu-on-the-text.png"
/> |

Drawn headless on Linux, where the native menu falls back to the drawn
popup.

- `Input::context_menu_with(self, f: impl Fn(NativeMenu,
InputContextMenuCapabilities, Option<InputHit>, &mut Window, &mut App)
-> NativeMenu + 'static) -> Self` and `Editor::context_menu_with`, the
same — a builder that receives the capabilities and what the right-click
was over, from `hit_test` (longbridge#3520): the text at an offset, or a row of
the gutter in a column. `context_menu` keeps its signature and is now
the builder that ignores them.
- `default_context_menu(menu: NativeMenu, capabilities:
InputContextMenuCapabilities) -> NativeMenu` — the built-in items,
public, for the clicks a custom builder leaves alone.
- `InputContextMenuCapabilities` — re-exported from `gpui-base`, for the
two signatures above.

`gpui_kit::component::input`)

- `InputBaseState::gutter_context_menu_moves_cursor(self, moves: bool)
-> Self` / `InputBaseState::set_gutter_context_menu_moves_cursor(&mut
self, moves: bool)` — `true` by default, as now; `false` keeps the
selection while the gutter's menu is open (and skips the
hover-definition lookup for it).
- `#[doc(hidden)] InputBaseState::on_context_menu_with_hit(&mut self,
handler: Rc<dyn Fn(NativeMenu, InputContextMenuCapabilities,
Option<InputHit>, Point<Pixels>, &mut Window, &mut App)>)` — how `Input`
hands the hit to its builder, as `set_editor_paddings` hands over the
paddings; `on_context_menu` keeps its signature.

- `a_right_click_on_the_gutter_tells_the_menu_its_row` (base) — the
gutter's row and column reach the menu; by default the caret moves to
the row, with the flag off the selection stays, and the text moves the
caret either way.
- `a_menu_built_with_its_target_knows_the_row_of_the_gutter` (component)
— through `Editor::context_menu_with` the builder sees the gutter's row
and the text's, and `context_menu` still opens.

Each goes red with its protection removed: the hit left out of the
menu's handler, the flag ignored, the hit dropped between `Input` and
the builder.

- `cargo test -p gpui-base --lib -- input::` (362 passed), `cargo test
-p gpui-component --lib -- input::` (45 passed)
- `cargo run -p example-editor-gutter-menu` — drawn headless,
screenshots above

- [x] I have read the [CONTRIBUTING](../CONTRIBUTING.md) document and
followed the guidelines.
- [x] Reviewed the changes in this PR and confirmed AI generated code
(If any) is accurate.
- [ ] Passed `cargo run` for story tests related to the changes.
- [x] Tested macOS, Windows and Linux platforms performance (if the
change is platform-specific)

---------

Co-authored-by: Jason Lee <huacnlee@gmail.com>
@glani

glani commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Thanks. The Linux/macOS test failure was the deprecated ScrollWheelEvent in the Editor Diff story (now ScrollEvent); it's fixed in the #3417 commit. Locally, with -D warnings as in CI, the story crate passes its tests and the workspace test build succeeds.

On the merge method: rebase-merge keeps each commit linked to its reviewed PR, but squash is fine too if that's simpler; the table in the description keeps the links. Agreed on timing: this is for the next minor release.

glani and others added 7 commits November 14, 2026 12:56
@huacnlee

Copy link
Copy Markdown
Member

Merged current main into this branch in 4ea717e, resolving crates/base/src/input/base/element.rs and crates/base/src/input/editor/display_map/text_wrapper.rs. Preserved gutter markers, spacer row placement and the wrapping version used to invalidate spacer positions, alongside main's width caches, batched rewrapping and compact line-number storage.

Validation: 1,802 gpui-base library tests passed, including spacer positioning, gutter hit testing, wrapping and decoration coverage. The two unchanged exhaustive fractional-width tests were excluded here after passing in the #3737 maintenance validation. The style-builder test was rerun after removing its redundant clone, preserving the original-versus-resolved renderer assertion. Strict all-target Clippy passed for Base and Component with test-support. Native rendering was not run: this execution context cannot access the macOS Pasteboard service, as confirmed by the #3737 renderer launch. This maintenance merge does not approve or change the existing public-API/release decision.

🤖 Noop (rust-maintainer) · AI agent acting for @huacnlee

Resolves the conflicts with longbridge#4022, which keeps `bounds.origin.y` unscrolled
and makes `visible_top` viewport-local.

- Rows are still placed by walking `row_extents()` from `visible_top`, so
  spacer rows and ghost lines keep their place; `visible_top` is now small,
  so the walk has no f32 drift. `local_row_y` is only used by its test.
- The anchor display row is above the first visible line's spacers, as
  `visible_top` was.
- `resolve_vertical_scroll_f64` counts spacer rows in the scroll height,
  as the layout does, so a caret below spacers is revealed.
- Spacer backgrounds are placed with `display_row_y`, so they follow the
  scroll; `a_spacer_background_stays_on_its_rows_when_scrolled`.
- Two spacer tests read positions from the unscrolled origin and the
  caret as painted.
@glani

glani commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Merged current main (c0992262) into this branch in 7597f79. The conflicts were with #4022, which keeps bounds.origin.y unscrolled and makes visible_top viewport-local:

  • Rows are still placed by walking row_extents() from visible_top, so spacer rows and ghost lines keep their place. visible_top is now small, so the walk has no f32 drift past 2^24 px. local_row_y is used only by editor: Preserve f64 vertical coordinates past 2^24 px and allow 9-digit line numbers #4022's test.
  • The anchor display row is the first visible line's start less the spacers above it, as visible_top was before.
  • resolve_vertical_scroll_f64 counts spacer rows in the scroll height, as prepaint does. Without that, a caret below spacers was not revealed (spacer_rows_are_display_rows_that_push_every_row_below_them).
  • Spacer backgrounds are placed with display_row_y, so they follow the scroll. New test: a_spacer_background_stays_on_its_rows_when_scrolled, red with the old placement.
  • Two spacer tests now measure against the unscrolled origin and the caret as painted.

The merge before it (7456cb3) adapted the paint calls to #4016's row_x.

Validation on Linux (Rust 1.98.0):

  • cargo test --locked -p gpui-base --lib: 1815 passed.
  • cargo test --locked -p gpui-component --lib --features test-support: 819 passed.
  • The story crate with -D warnings: 29 passed.
  • Strict clippy on gpui-base and gpui-component: clean, except clippy::drop_non_drop on drop(wrap_line) in text_wrapper.rs. That line is on main (editor: Speed up soft wrap for large and non-ASCII documents #3974), and the lint fires with clippy 1.98.

Not run: the story visually.

glani and others added 3 commits November 18, 2026 19:24
Preserve line decorations, spacer rows and mirrored gutter columns alongside the new GutterStyle renderer. Carry the resolved gap into column placement and hit testing, with coverage for both gutter sides and every column order.

Agent: rust-maintainer
@huacnlee

Copy link
Copy Markdown
Member

Merged main (a9d53719) in 6d112bfd, resolving crates/base/src/input/base/{element,state}.rs, crates/component/src/input/{editor,input}.rs, and crates/story/src/stories/editor_story.rs. Preserved line decorations, spacer rows, mirrored/reordered gutter columns and context menus alongside main's GutterStyle renderer.

The resolved gutter gap now follows the layout into column placement and hit testing, including mirrored gutters; the new regression covers gaps of 0/12/24 px on both sides and all six existing column orders. Both sides' tests are retained. Also fixed the single closure-formatting failure reported by nightly fmt.

Linux validation:

  • Base library: 1,823 tests passed, plus the new combined-gap regression passed separately.
  • Component library with test-support: 847 tests passed.
  • Story test targets: cargo check passed.
  • Base and Component all-target Clippy with test-support and -D warnings: passed.
  • cargo +nightly fmt --all -- --check: passed.

Native rendering was not exercised. This maintenance merge does not change the existing API/release decision for the PR.

🤖 Noop (rust-maintainer) · AI agent acting for @huacnlee

@huacnlee huacnlee closed this Nov 22, 2026
@huacnlee

Copy link
Copy Markdown
Member

Thank you for the substantial work on this, @glani. The line decorations, mirrored gutters, spacers and gutter hit testing are well thought out, and we appreciate the time it took to bring next up to date with main.

After looking at it again, we've decided not to accept this PR. At roughly 7.5k added lines across 48 files, the change is larger than we can safely review and maintain as a single landing, so the PR has been closed.

If you'd like to continue, smaller focused PRs that each add one capability (for example, line decorations alone) with a clear use case would be much easier for us to evaluate. Thanks again for contributing to GPUI Kit.

🤖 Noop (reviewer) · AI agent acting for @huacnlee

@glani

glani commented Nov 22, 2026

Copy link
Copy Markdown
Contributor Author

In the whole story I don't understand. Why did you push it originally to the "next". Because we were doing exactly the same review one feature step by step and now it became the largest one that we could not merge.
I will think how to split it to small features.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants