Add CodeMirror editor signals (selection, focus, viewport, geometry) and reveal_line

[Jepson2k]

Motivation

Hosts that embed ui.codemirror as an in-app editor often need feedback about the editor's state — cursor line / column, focus, the visible line range, and editor geometry. None of this is exposed through the Python API today, and there's no programmatic way to scroll a specific line into view.

Implementation

• reveal_line(line_number) — scrolls a 1-indexed line into view via EditorView.scrollIntoView.
• Four typed signal handlers: on_selection_change(line, column, from_line, to_line, empty), on_focus_change(focused), on_viewport_change(from_line, to_line), on_geometry_change(width, height, content_height).

A single JS ViewPlugin emits per-signal events. A signal is only computed and sent while a listener for its event is registered, whether through on_*_change or a plain editor.on('selection-change', ...), so unsubscribed signals cost nothing on the wire. Payloads are deduped against the last one sent, so an update that leaves a signal unchanged never reaches the socket either.

viewport-change reports the first and last line shown in the editor's scroll area. CodeMirror's own view.viewport is the rendered range (visible plus a margin of about 500 px on each side), so the event measures the scroller instead, triggered by its scroll event and by geometry changes.

reveal_line uses y: "nearest" with a margin of half the visible height. y: "center" would also re-center the window whenever the editor cannot scroll far enough itself. CodeMirror applies the margin to every scrollable ancestor, so it is taken from the smallest one, the window included: half the editor height would push the line out of sight whenever the editor is more than twice as tall as what it scrolls in, e.g. an auto-height editor in a scrolling page. ※

Rate limiting is Element.on(..., throttle=...), passed by the four registrars with per-signal defaults of 30 ms / none / 100 ms / 100 ms — the same approach slider, range, knob and splitter take with throttle=0.05. An earlier revision carried a bespoke ui.codemirror.handler(cb, debounce_ms=...) factory for this; it was removed in favour of the existing mechanism, which is per-listener rather than per-element and delivers the first event of a burst immediately.

No test covers the throttling itself: tests/test_events.py already exercises throttle / leading_events / trailing_events, and a per-element re-test would only be a slower, timing-dependent copy of it.

geometry-change reads the editor's size through requestMeasure rather than in ViewPlugin.update, which CodeMirror rules out: geometryChanged is set by every document change, so a registered geometry handler forced a layout on every keystroke. The isConnected guard in the write phase is load-bearing — beforeUnmount does not destroy the view, so a queued measure can outlive the editor's DOM and would otherwise report a 0×0 geometry. One consequence: the event now lands in a later measure cycle rather than in synchronous plugin-update order. No test covers the unmount path — reaching "view alive, DOM detached" needs scaffolding that mirrors the implementation, so test_geometry_change_event remains the coverage for the events themselves.

Progress

• The PR title is a short phrase starting with a verb like "Add ...", "Fix ...", "Update ...", "Remove ...", etc.
• The implementation is complete.
• This PR does not address a security issue.
• Pytests have been added.
• Documentation has been added.
• No breaking changes to the public API.

[falkoschindler]

Hi @Jepson2k, this branch has drifted out of sync with main: the conflicts are in codemirror.js, codemirror.py and codemirror_documentation.py, and they come mostly from your own line-anchor work — #5988 landed in 3.16, the follow-up #6282 moved the on_anchor_change dispatch to Python, and the "Added in" annotations were standardized in between — so the CodeMirror element has seen quite some motion since this branch was cut. Could you merge current main into the branch and resolve the conflicts (no rebase/force-push needed)?

Since #5984, #5985 and #5986 all touch the same spots, I'd suggest doing them one at a time rather than keeping all three in sync: pick the one you want to land first, bring it up to date, mark it "ready for review", and once it is merged, do the same for the next. That also keeps you well within the three-ready-PRs limit Evan mentioned. Note that #5991 (decoration API) is planned for 3.17 and lands in the same files, so the first one may need one more small update after that — sorry about the churn.

Until then I'm assigning this to you and marking it as draft; flip it back to "ready for review" whenever it is green and I'll take it from there. ※

[evnchn]

Drafted by Claude Code working with @evnchn.

I see you added ui.codemirror.handler(cb, debounce_ms=...) and CodeMirrorHandlerSpec to rate-limit the new events, but Element.on(..., throttle=, leading_events=, trailing_events=) already does this for every event in seconds, and in my eyes it covers everything yours does (checked: with the JS debounce at 0, throttle=0.2, leading_events=False coalesced 10 cursor moves at 30 ms into 2 events carrying the latest payload). If you agree, please remove it; if not, let's discuss.

[Jepson2k]

Posted by Claude Code on @Jepson2k's behalf.

All three taken, plus the geometry one.

• reveal_line — one word changed: is not an integer in [1, N], since 2.5 genuinely is in [1, 3].
• selection-change on set_value — as written.
• Code-point column — as written. The real bug of the three.
• The 0.27 ms — taken too, isConnected guard included. The forced layout only exists because this PR adds geometry-change, so it's ours to fix rather than inherit. The measure-cycle ordering change is in the commit message.

No test for the unmount path: it needs the view alive with its DOM detached, which the public API doesn't expose without scaffolding that mirrors the implementation. Reason is in Implementation.

Each of the three regression tests was verified to fail with its fix reverted. Four commits, one per item.

[evnchn]

TL;DR: where the host thinks the cursor is and where it actually is must never desync.
The emitting gate I asked for desyncs them, and nothing corrects it until the user happens to
move the cursor themselves. Three ways out below, none mine to pick.

Cursor on line 3, server inserts a line above it:

	events emitted	host believes	cursor actually on
2f7acc51 parent	1	line 4	line 4	in sync
1792efe3 head	0	line 3	line 4	desynced

A later real cursor move does resync it. Until then nothing can: on_selection_change is the
only channel reporting the cursor, and there is no Python-side getter to read instead.

What decides it: is a host meant to track the cursor across a set_value? If no, A is enough.
If yes, only B or C close the desync.

Diffs folded so the three read side by side, and not suggestion blocks on purpose: three
Commit buttons on a decision point is a way to decide by accident.

A. Keep the gate, reword the docstring. codemirror.py L138. Cheapest, and leaves the
desync in place.

diff

-        Fires on selection moves and on document edits that shift the cursor line or column.
+        Fires on selection moves and on user edits that shift the cursor line or column.
+        A server-driven ``set_value`` does not emit, even when it moves the cursor.

B. Keep the gate, add programmatic: bool and emit again. Echo-ignorers filter on it,
cursor-trackers stay in sync. Untested, and it joins _maybeEmit's whole-payload comparison.

diff

--- a/nicegui/elements/codemirror/codemirror.js
-            if (self.selectionTrackingEnabled && (u.selectionSet || (u.docChanged && self.emitting))) {
+            if (self.selectionTrackingEnabled && (u.selectionSet || u.docChanged)) {
               const sel = u.state.selection.main;
               const line = u.state.doc.lineAt(sel.head);
               this._maybeEmit("selection-change", {
                 line: line.number,
+                programmatic: u.docChanged && !self.emitting,

--- a/nicegui/events.py
 class CodeMirrorSelectionChangeEventArguments(UiEventArguments):
     line: int
     column: int
+    programmatic: bool

--- a/nicegui/elements/codemirror/codemirror.py
             empty=e.args['empty'],
+            programmatic=e.args['programmatic'],
         )), throttle=0.03)

C. Emit on a document edit only when the selection payload changed. The only one I built,
and my first attempt was wrong: comparing the head offset misses a column change when ab
becomes 😎, and a to_line change when a backward selection loses its middle line. Comparing
the whole payload against u.startState handles both. 27 passed, table back to in-sync, and
both counterexamples now emit correctly.

diff

-            if (self.selectionTrackingEnabled && (u.selectionSet || (u.docChanged && self.emitting))) {
-              const sel = u.state.selection.main;
-              const line = u.state.doc.lineAt(sel.head);
-              this._maybeEmit("selection-change", {
-                line: line.number,
-                column: Array.from(u.state.doc.sliceString(line.from, sel.head)).length + 1,
-                from_line: u.state.doc.lineAt(sel.from).number,
-                to_line: u.state.doc.lineAt(sel.to).number,
-                empty: sel.empty,
-              });
+            if (self.selectionTrackingEnabled && (u.selectionSet || u.docChanged)) {
+              const payload = (state) => {
+                const sel = state.selection.main;
+                const line = state.doc.lineAt(sel.head);
+                return {
+                  line: line.number,
+                  column: Array.from(state.doc.sliceString(line.from, sel.head)).length + 1,
+                  from_line: state.doc.lineAt(sel.from).number,
+                  to_line: state.doc.lineAt(sel.to).number,
+                  empty: sel.empty,
+                };
+              };
+              const now = payload(u.state);
+              if (u.selectionSet || JSON.stringify(now) !== JSON.stringify(payload(u.startState))) {
+                this._maybeEmit("selection-change", now);
+              }
             }

the two cases that killed my first attempt

Head-offset comparison. Both emit nothing, both leave the host wrong:

	host believed	truth after the edit	emitted
ab before the cursor becomes 😎	column 3	column 2	0
backward selection over 3 lines, middle one deleted	to_line 3	to_line 2	0

The head offset is UTF-16 so it does not change in the first, and the head does not move at all
in the second. With the payload comparison both emit, (1, 2, 1, 1, True) and
(1, 1, 1, 2, False).

I asked for the gate, so which one lands is your call and @falkoschindler's.

One dead end, in case you try the same thing

Dropping && self.emitting and leaning on the existing _maybeEmit dedupe looks like C for
free. It fails your test with assert 2 == (0 + 1): _last["selection-change"] is still empty
there, so the first echo has nothing to dedupe against. The comparison has to be against
u.startState.

The probe, run on both trees

def test_cursor_after_set_value(screen: Screen):
    events, editor = [], None

    @ui.page('/')
    def page():
        nonlocal editor
        editor = ui.codemirror('L1\nL2\nL3',
                               on_selection_change=lambda e: events.append(e.line))

    screen.open('/')
    screen.should_contain('L3')
    screen.selenium.execute_script(
        f'const el = getElement({editor.id});'
        'el.editor.dispatch({selection: {anchor: el.editor.state.doc.line(3).from}});')
    screen.wait_for(lambda: 3 in events)
    before = len(events)

    editor.set_value('NEW\nL1\nL2\nL3')
    screen.should_contain('NEW')
    time.sleep(1.0)                      # give any echo time to arrive

    actual = screen.selenium.execute_script(
        f'const el = getElement({editor.id});'
        'const s = el.editor.state; return s.doc.lineAt(s.selection.main.head).number;')
    print(f'emitted={len(events) - before} host={events[-1]} actual={actual}')

parent: emitted=1 host=4 actual=4 · head: emitted=0 host=3 actual=4

CI has not run since 2f7acc51, so today's four commits have not been through it. I merged
main locally to check the above, and both conflicts are keep-both, in case it saves you a look:

• the docstring paragraph that landed beside the Decorations one
• Fix CodeMirror line anchors and tooltips set together with a new value #6336 moving the Line Anchors demo to the end of the file

---

_{Colophon: drafted by Claude Code working with @evnchn. Figures are medians of repeated runs
through the repo's screen fixture, head 1792efe3 against parent 2f7acc51. I have moved the
attribution to the foot so the first line can be about the work. Adopt it or not, no rule here.}

[Jepson2k]

Posted by Claude Code on @Jepson2k's behalf.

C, pushed as 32b44c22. You were right both times — the echo was real, and so was the desync the gate traded it for. The payload-vs-startState comparison is the thing that answers the actual question; emitting only ever meant "the server already knows the text".

test_set_value_emits_only_when_the_cursor_actually_moves pins it from both sides: it fails against the gate on the remap, and against the ungated original on the echo. Your two counterexamples are why it compares payloads rather than the head offset.

Also merged main — both conflicts keep-both, as you said. CI is running on these five commits now.

[Jepson2k]

Posted by Claude Code on @Jepson2k's behalf.

Both in.

content_height — this is a real bug in the API this PR adds, not a nitpick. Fixed as suggested, and test_geometry_change_event now pins it: a CSS transform changes neither the document nor the space it is laid out in, so all three numbers have to sit still. It fails assert 14 == 28 without the divide.

Array.from — taken. Worth noting your measurement understates it now: C builds the payload twice per update to compare against startState, so the cost had doubled since you timed it. The surrogate check is exact where it needs to be, and a lone high surrogate taking the slow branch costs nothing.

Two commits, green on the codemirror and events suites.

[evnchn]

Approving. I checked that the new test fails without the divide (assert 14 == 28) and that the value holds at scale(0.5), scale(2), scale(1.7), scaleY(0.25) and a scaled parent. The two suggestions are optional, resolve them if you would rather not take them.

※

[falkoschindler]

@Jepson2k, a question about the selection-change payload: what made you go with line, column, from_line, to_line and empty instead of following CodeMirror's own selection model?

CodeMirror describes a selection range by two document offsets, anchor and head, and derives everything else from them. The current payload mixes two things: the cursor position (line, column) and a line-granular span (from_line, to_line). This leads to a few quirks:

• line always equals either from_line or to_line, yet the payload doesn't tell which end the cursor is on.
• The span has no columns, so a partial selection within a line can't be reconstructed. empty only tells you that something is selected.
• column is 1-based and counts code points. That's neither CodeMirror's notion (UTF-16 offset from the line start) nor a Python index (line_text[column - 1]).
• Only selection.main is reported, while basicSetup enables multiple selections. Moving a secondary cursor goes unnoticed.

I couldn't find a rationale in the discussion or the commits. 4bde004 says the span lets "hosts act on multi-line selections without a client round trip", but doesn't name a concrete use case. Did you have one in mind that needs exactly this shape?

Otherwise I'd suggest staying close to CodeMirror: report anchor and head as code-point offsets into value, so they can be used directly as Python string indices. line/column of the head could stay as a convenience for status bars. That would be lossless, and from_line, to_line and empty would follow from it. ※

[falkoschindler]

@Jepson2k, following up on my question about the selection-change payload: it's the one thing holding this PR back. The other signals and reveal_line are ready (I pushed two fixes for scaled and auto-height editors), but I'd rather not ship an event shape we'd have to break later.

Thinking about it more, the right shape depends on who uses the event and for what. A status bar needs the cursor's line and column. Acting on the selected text needs both ends with character precision. Commenting out the selected lines needs the line span. Each of these suggests different fields, and I don't want to guess.

So two questions:

1. What do you use on_selection_change for in your app? A concrete example would settle it.
2. Would it be okay to move on_selection_change into a follow-up PR? Then the rest could go into the next release, and we design the selection event around your use case without time pressure.

※