Skip to content

Scroll API: getScrollInfo, all scrollIntoView forms, rect helper (Refs #54) - #83

Draft
DJAscendance wants to merge 4 commits into
masterfrom
feat/scroll-api
Draft

DJAscendance wants to merge 4 commits into
masterfrom
feat/scroll-api

Conversation

@DJAscendance

@DJAscendance DJAscendance commented Oct 29, 2026 •

Copy link
Copy Markdown
Member

Refs #54

Ledger rows: 472 scrollTo, 473 getScrollInfo, 474 scrollIntoView (method), 659 scrollIntoView(cm, rect) helper. Also checked, but unchanged here: 657 maybeScrollWindow.

Base: 7d917785a1b65259b238f35a3fad98343d8a6d02 (master, merged in); parent PR head a4a6293496d23fce990c73a899a0b823e574e6cb
Head: 2919bd97af2043426f40b1d3558340e9bcf56959

Integration: Stacked on #81 (a4a6293); merge in order #81, #83, #86, #89, #90, #91, #92. Until the PR below it merges, this PR's diff against master includes that PR.

This branch is independent of #81 (coordinate systems). Both edit the pub use editor::{...} line in lib.rs, so whichever merges second has a one-line conflict to resolve.

What this adds

  • Editor::get_scroll_info() -> ScrollInfo { left, top, height, width, client_height, client_width }. height/width are the content size (max scroll + client size). The client sizes are displayHeight and displayWidth, gutters included.
  • Editor::scroll_into_view_target(target, margin) covers every range form of cm.scrollIntoView:
    • ScrollTarget::Cursor (null): the primary head, with cursorScrollMargin when the margin is None.
    • Line(n): Pos(n, 0).
    • Pos and Range(from, to).
    • Coords(rect) and CoordsRange(a, b): local coordinates, through a new scroll_to_coords_range (scrollToCoordsRange).
    • margin || 0: None and NaN become 0.
    • From impls exist for i64, Pos and Rect. The existing scroll_into_view(from, to, margin) stays.
  • Editor::scroll_rect_into_view(rect) is the rect helper scrollIntoView(cm, rect). It runs calculateScrollPos and then the thresholded updateScrollTop / setScrollLeft at once, so changes under 2 px are dropped. It runs as an operation, so the rendered range follows.
  • scrollTo: no code change. The recording confirms that it resolves a pending scrollToPos (a later scrollTo overrides it) and that null axes are left alone. The ledger note "does not resolve a pending scrollToPos" was stale.

Upstream refs (pinned 4ca3d05)

src/edit/methods.js:364-390; src/display/scrolling.js:70-75 (rect helper), 82-114 (calculateScrollPos), 125-157 (scrollToCoords, scrollToRange, resolveScrollToPos, scrollToCoordsRange), 161-185 (updateScrollTop, setScrollLeft thresholds).

Tests and evidence

  • crates/cm-view/tests/scroll_api.rs, against tests/data/cm5-scroll-api.json. That file was recorded by the new oracle/cm5-scroll-api.mjs from CM5 5.65.21 in headless Chromium.
    • get_scroll_info_matches_cm5: 8 editors (long, scrolled, short, wide, at max, line numbers, wrapped).
    • scroll_into_view_forms_match_cm5: 26 cases. They cover every form, margins, cursorScrollMargin, top/bottom snap, rects taller than the view, and scrollTo/scrollIntoView/setCursor sequences inside one operation.
    • rect_helper_is_immediate_and_thresholded (unit test; no CM5 API exposes the helper).
  • Strict, on the top of the stack (Cursor drawing: showCursorWhenSelecting, cursorHeight, fat cursor, overwriteToggle (Refs #51) #92 0b167ad, which contains this PR and every PR below it): cargo test --workspace --no-fail-fast gave 834 passed, 0 failed, 0 ignored. The same under xvfb-run -a: 834 passed, 0 failed. tools/web-test.sh: all 5 browser profiles passed 63/63.
  • cm-web is not touched, so the browser run was not repeated.

Known differences

Coverage change

  • 472, 473, 474: PARTIAL → PORTED
  • 659: NOT_PORTED → PORTED

CI: pending (Actions cannot start: billing)

)

cursorCoords/charCoords/coordsChar/lineAtHeight/heightAtLine method forms
(cursor_coords_in, char_coords_in, coords_char_in, line_at_height_in,
height_at_line_in) with page and window modes over a host-supplied
window origin and page scroll, start=null/true/false, clipPos, LineHandle
arguments, includeWidgets (no widgets yet) and the end-of-document
adjustment; intoCoordSystem/fromCoordSystem ported with CM5's div
(viewOffset) semantics. The port's internal document-y frame is now
CoordSys::Doc. Checked against a CM5 recording (cm5-coord-systems.json).
… (Refs #54)

get_scroll_info() returns CM5's {left, top, height, width, clientHeight,
clientWidth}; scroll_into_view_target takes null (cursor plus
cursorScrollMargin), a line number, a position, a range, a coordinate box
or a box range (scrollToCoordsRange); scroll_rect_into_view is the
immediate, thresholded scrollIntoView(cm, rect) helper. Checked against a
CM5 recording (cm5-scroll-api.json), including scrollTo and scrollIntoView
inside one operation.
into_coord_system honors include_widgets as CM5 does: without it the box
moves below the widgets above the line (widgetTopHeight), before the
"line" early return; master's into_coords path is the include_widgets =
false case. Exports keep both sides' items. New test
into_coord_system_include_widgets.
@github-actions

Copy link
Copy Markdown

MiniMax-M3.1-Flash QA

Review findings

1. Display gains required public fields, breaking existing struct literals

Severity: Medium — likely a breaking change for downstream users.

Display is public and the PR adds:

pub window_origin: (f64, f64),
pub page_scroll: (f64, f64),

Any downstream code constructing Display with a struct literal will stop compiling. This is particularly relevant because Display appears to be part of the public host integration API.

Possible mitigations:

  • Add #[non_exhaustive] now and introduce the fields in a deliberately breaking release.
  • Provide a constructor or builder for Display.
  • Otherwise, document this as an intentional breaking change and bump the crate version appropriately.

The defaults in Editor::new are correct, but they do not preserve source compatibility for external struct literals.


2. The new coordinate-system API is not covered for non-default window_origin and page_scroll in all relevant paths

Severity: Medium

The oracle test does exercise different wrapper/page offsets, but the Rust test currently relies on the recorded environment and only sets:

cm.display.window_origin = ...
cm.display.page_scroll = ...

The implementation has several separate transformations involving these values:

  • into_coord_system
  • from_coord_system
  • line_space_origin
  • coords_char_in
  • line_at_height_in
  • height_at_line_in

The current round-trip test covers most of these for one nonzero configuration, but it does not explicitly assert the expected absolute values independently of the inverse operation. A pair of transformations can be mutually wrong and still round-trip successfully.

For example, add assertions for a known editor origin/page scroll that verify:

  • cursor_coords_in(..., Page) equals Window plus page_scroll.
  • cursor_coords_in(..., Window) contains window_origin.
  • coords_char_in converts a page coordinate back to the expected document position.
  • height_at_line_in differs between Page, Window, Local, Div, and Doc by the documented offsets.

This is especially valuable because the public API exposes these values directly and host implementations can set them incorrectly.


3. scroll_into_view_target has ambiguous and potentially incorrect operation semantics for coordinate targets

Severity: Medium

The documentation says:

a box form computes the scroll position now (scrollToCoordsRange) and sets op.scrollLeft/op.scrollTop.

But the implementation immediately calls:

ScrollTarget::Coords(r) => return cm.scroll_to_coords_range(r, r, margin),
ScrollTarget::CoordsRange(a, b) => return cm.scroll_to_coords_range(a, b, margin),

This happens inside run_op, but the method does not visibly set op.scrollLeft or op.scrollTop. Instead, it relies on scroll_to_coords_range/scroll_to_coords to do so indirectly.

That distinction is important because the PR itself documents two different behaviors:

  • scroll_rect_into_view uses thresholded update_scroll_top/update_scroll_left.
  • The method-operation coordinate form is supposed to use op.scrollLeft/op.scrollTop.

Please verify that scroll_to_coords_range actually updates the operation fields rather than mutating the current scroll state directly. If it mutates the current state directly, coordinate targets will behave differently inside and outside run_op, and the documented method-operation ordering will be incorrect.

A focused test should cover:

cm.run_op(|cm| {
    cm.scroll_into_view_target(coords, None);
    cm.scroll_to(Some(...), Some(...));
});

and verify that the coordinate request participates in the same operation ordering as the other scroll forms.


4. The new ScrollTarget API does not represent the CM5 “range with only from” form distinctly

Severity: Low

The oracle includes:

"range_from_only": {
  ...
}

and the Rust test maps it to:

ScrollTarget::Pos(Pos::new(50, 0))

This is semantically equivalent for the current implementation, but it means the public Rust API does not distinguish:

  • scrollIntoView({from: pos})
  • scrollIntoView(pos)

That may be acceptable, but the documentation currently describes ScrollTarget::Range(Pos, Pos) only and does not explicitly explain that a position is the Rust equivalent of CM5’s {from}-only range form. If preserving the CM5 API shape is important, add a dedicated variant or document the equivalence clearly.


5. The new public API uses several CM5-specific names without clarifying the local/internal distinction

Severity: Low

CoordSys::Doc is public and exported, but it is described as an internal frame:

The port's internal frame: document y without the top padding (CM5 "div" with a viewOffset of 0).

At the same time, the existing cursor_coords, char_coords, coords_char, line_at_height, and height_at_line methods accept CoordSys directly, so callers can now pass Doc to APIs that historically used Div. This is useful internally, but it makes the public enum represent both CM5-compatible coordinate systems and a port-specific coordinate system.

Please make the distinction explicit in the public API documentation, for example by stating:

  • which enum variants are CM5-compatible public modes;
  • that Doc is primarily for internal renderer/movement calculations;
  • whether callers should prefer Div for CM5-compatible behavior.

Otherwise, users may use Doc where Div is expected and get different results when view_offset is nonzero.


Positive observations

  • The change replaces internal uses of CoordSys::Div with CoordSys::Doc consistently in movement, rendering, visual tests, and web-frame generation.
  • The CM5 oracle recordings and Rust comparison tests are valuable and cover a broad range of coordinate-system combinations.
  • The deleted-line-handle behavior and widget inclusion behavior are explicitly tested.
  • The implementation correctly attempts to preserve CM5-specific behaviors such as:
    • defaulting to "page";
    • clipping positions;
    • treating NaN margins as zero;
    • preserving the one-pixel distinction between method-operation and rect-helper scrolling.

Overall assessment

The implementation appears well tested against CM5 and the coordinate-system changes are internally consistent. The main concerns are API compatibility and making sure the coordinate-target scroll form truly follows the documented method-operation behavior. I would request clarification or changes for the Display struct-literal compatibility issue and for the scroll_to_coords_range operation semantics before merging.

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.

1 participant