Skip to content

Let a host suspend the gesture-free marker-settle clocks (unblocks PT-4611) - #25

Merged
timothy-mccormack merged 10 commits into
mainfrom
pt-4611-settle-pause
Oct 19, 2026
Merged

timothy-mccormack merged 10 commits into
mainfrom
pt-4611-settle-pause

Conversation

@timothy-mccormack

@timothy-mccormack timothy-mccormack commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Unblocks PT-4611 / paranext-core#2870, where it is a review checklist item.

Why

A host that opens a surface of its own over the editor — Platform.Bible's Standard-view marker palettes — needs the document to stop reformatting underneath it while that surface is open. Three settle clocks fire without the host asking for them, and all three break such a surface the same way:

a settle commits dirty nodes → Lexical re-asserts the DOM selection on any such commit → it focuses the editor root whenever focus has left it (updateDOMSelection) → focus leaves the surface → a surface that dismisses itself on focus loss closes.

  • The idle debounce fires one markerSettleDelayMs after the last change, closing a palette the user is still reading. Confirmed in the host on Windows: type \, nd, \ to commit and reopen — the reopened palette closes itself about a second later.
  • The blur clock fires the instant the surface takes focus. Its existing caret-node exception already protects the literal the palette is about to consume, so what remains is every other pending node — and settling one of those is what produces the commit.
  • The caret-departure clock is keyed off every commit, not off a user gesture. So a commit the host or a display-run sync makes while the surface is open does the same thing with nobody typing — the host's own debounced pre-save being the likeliest source.

What

EditorRef.setMarkerSettleSuspended(suspended: boolean), dispatching a new SET_MARKER_SETTLE_SUSPENDED_COMMAND that the marker-edit engine reads at all three clocks. MarginalRef forwards it like the rest of EditorRef.

Suspending cancels an already-armed idle timer. That is the part a delay change cannot do: markerSettleDelayMs is read when the clock is next armed, so a timer armed before the host changed it still fires.

Resuming settles what the suspension held — everything pending except the node under the caret, the same exception the blur and departure clocks use — and then re-arms the idle clock. Resume is the moment Paratext 9 reformats (MarkerDropdownControl.InternalClose), so held edits do not wait out another idle delay, and they still settle when the idle clock is turned off entirely (markerSettleDelayMs: -1), where there is no clock to re-arm. The caret's own node stays pending so a palette's apply can still consume it.

Suspend synchronously, before focus moves. BLUR_COMMAND fires on the focus move itself, so a suspend that arrives after it cannot undo a settle that has already run. The TSDoc says so explicitly, along with the fact that this is a single flag rather than a reference count — a host with more than one such surface should drive it from one derived "any surface open" state.

A missed resume heals itself, on sustained focus rather than on focus alone. When the editor holds DOM focus continuously for about a second while still suspended, the suspension is lifted, held edits settle, and a warning is logged. A blur cancels it (a surface took focus back), and so does the host resuming.

Focus by itself is not evidence, which the running app showed: a host's commit path returns focus to the editor mid-session, on purpose, to apply what the user chose — the marker palette's commit-and-reopen does exactly that. An immediate lift there settles the document under a palette about to reappear, which is the failure this whole feature exists to prevent. What separates the two is how long the focus lasts: a legitimate one is brief, because a replacement surface retakes focus within a few hundred milliseconds or the host resumes.

Lifting late is harmless, which is what makes the wait acceptable: a suspension only protects a surface that HOLDS focus, and a settle can only steal focus that is somewhere else. If the editor has held focus for the whole window, a settle has nothing to take. Real DOM focus is re-checked when the timer fires, because FOCUS_COMMAND is a notification rather than proof.

What still settles, because the host or the user explicitly asked for it: Enter, commitPendingMarkerEdits, the settle-on-read inside getUsj, and resolution within the same update as the edit.

Tests

settleSuspension.test.tsx, 15 cases covering all three clocks in both directions, the already-armed cancellation, the resume settle with the idle clock both on and off, the forced-commit carve-out, and the focus safeguard with its blur gate.

Every case is mutation-checked: each guard was removed in turn and the test that covers it confirmed to fail. Two notes from doing that, since they are the kind of thing that looks like coverage and is not:

  • The blur cases need a pend with no caret in it. With the caret inside, both pass without the feature — the blur handler's existing caret-node exception holds the node, not the new code.
  • The departure guard was originally checked twice, at queue time and at run time. Removing the queue-time check alone fails nothing, because the run-time check catches the same cases; it only avoided scheduling a microtask that the second check discards. Consolidated to the single run-time guard, which two tests now kill.

Full packages/platform suite green (2361 passed, 3 pre-existing skips); typecheck and lint clean through nx.

🤖 Generated with Claude Code


This change is Reviewable

Adds `EditorRef.setMarkerSettleSuspended(suspended)`, for a host that
opens a surface of its own over the editor — Platform.Bible's Standard
view marker palettes — and needs the document to hold still while it is
open.

Two settle clocks fire with no user gesture, and both break such a
surface the same way: a settle updates the editor, an update moves the
selection, and moving the selection makes Lexical focus the editor root,
pulling focus out of the surface — which the host then dismisses on the
window blur that follows.

- The IDLE debounce fires about a second after the last change, closing a
  palette the user is still reading. Reproducible in the host as: type
  `\qt-s`, press `\` to commit and reopen, wait — the reopened palette
  closes itself.
- The BLUR clock fires the instant the surface takes focus. Its existing
  caret-node exception already protects the literal the palette is about
  to consume, so what remains is every OTHER pending node — and settling
  one of those is what produces the update.

Suspending CANCELS an already-armed idle timer. That is the part a delay
change cannot do: `markerSettleDelayMs` is read when the clock is next
armed, so a timer armed before the host changed it still fires. Resuming
re-arms a full delay rather than the remainder, so work left pending
through the suspension settles on the normal rhythm.

Deliberately narrow: settles driven by a real user gesture — caret
departure, Enter, an explicit `commitPendingMarkerEdits` — are untouched,
because a user asking for a settle is not what this protects against. A
test pins that.

`MarginalRef` forwards the new method, as it does the rest of `EditorRef`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ion idempotent

A self-review pass found that the caret-departure settle was never covered by
`setMarkerSettleSuspended`, which defeated the feature's own purpose. The PR
assumed the three remaining settle paths were gesture-driven; departure is not.
It is keyed off every COMMIT — the update listener says so itself — so while
suspended, any commit landing with a live RangeSelection queued a settle about a
tick later. The realistic trigger is the host's own debounced pre-save commit or
a display-run sync firing with the palette open, with no user involved: exactly
the commit whose focus side effect the suspension exists to prevent.

Guard the departure queue and its microtask, and re-check at the microtask since
a suspend can land between queueing and running.

Also in this round:

- Make the command idempotent. The resume branch re-arms a FULL delay, so a host
  driving this from an effect without a change guard would push the idle settle
  out on every render and starve the clock indefinitely — a failure whose symptom
  looks nothing like its cause.
- COMMAND_PRIORITY_CRITICAL -> LOW, matching the sibling host-dispatched
  COMMIT_PENDING_MARKERS_COMMAND. One handler, so priority decides nothing, and
  CRITICAL is reserved in this file for beating Lexical's built-ins on native
  commands.
- Correct the documented causal chain, which was wrong in five places: "an update
  moves the selection, and moving the selection makes Lexical focus the root".
  The rebuild deliberately leaves the selection untouched in exactly the case
  those comments describe, and Lexical needs no selection move anyway —
  updateDOMSelection runs on any dirty-node commit and focuses the root when
  focus has left it. Likewise the Editor.tsx claim that the dispatch is "not
  wrapped in editor.update": Lexical wraps every command listener in
  updateEditorSync regardless; nothing commits because the handler dirties
  nothing.
- Document what the contract actually is: not refcounted, nothing else clears it,
  what a missed resume costs, no-op outside editable marker modes, dropped when
  unmounted. Tagged EXPERIMENTAL like its sibling markerSettleDelayMs.
- Cover armIdleSettle's guard, which had none: it could be deleted with all six
  original tests still passing, though it is the line the useRef-over-local design
  rationale exists to serve. Ten tests now, each new one mutation-checked to fail
  without its guard.
- Regenerate the committed dist/ and etc/ api report, which were missing the new
  EditorRef member — CI's drift check was red and paranext-core could not see the
  method.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@timothy-mccormack

Copy link
Copy Markdown
Contributor Author

Self-review pass (5 analysis agents) — 1 critical defect found and fixed, 1 design question for you

I ran a multi-agent review over this branch before asking for a human read. It found one defect that defeated the feature's own purpose, and one alternative design that may make most of this PR unnecessary. Details below; the second point is the one I'd like your opinion on before this leaves draft.

The critical defect: the caret-departure settle was never suspended

The PR's premise was that the three remaining settle paths are gesture-driven and therefore safe to leave running. That is wrong for caret departure — it is keyed off every commit, not off a gesture, as the update listener's own comment says. So while suspended, any commit that lands with a live RangeSelection queued a settle about a tick later.

Proven, not theorised:

marker immediately after an ordinary commit while suspended: nd
after a microtask flush:                                     nd
after 1ms:                                                   wj   <-- settled, while suspended

The realistic trigger is the host's own debounced pre-save commitPendingMarkerEdits (~700ms) or a display-run sync firing with the palette open — no user involved. That is exactly the commit → focus-steal this feature exists to prevent.

Fixed by guarding the departure queue and its microtask, with a regression test. Also fixed in this round:

  • A redundant resume re-armed a full delay. A host driving this from an effect without a change guard would push the idle settle out on every render and starve the clock indefinitely. The handler is now idempotent.
  • COMMAND_PRIORITY_CRITICAL → LOW, matching the sibling host-dispatched COMMIT_PENDING_MARKERS_COMMAND. Single handler, so priority decides nothing; CRITICAL is reserved in this file for beating Lexical's built-ins on native commands and implied a contest that doesn't exist.
  • CI was red on the committed-output drift check — the new EditorRef member was in neither etc/platform-editor.api.md nor the committed dist/, so paranext-core couldn't actually see the method. Regenerated.
  • A comment that was factually wrong about Lexical. It claimed the dispatch is "deliberately not wrapped in editor.update". Lexical wraps every command listener in updateEditorSync regardless; the reason nothing commits is that the handler dirties nothing. The conclusion held, the stated mechanism didn't.
  • The documented causal chain was wrong in the same way, in five places: "an update moves the selection, and moving the selection makes Lexical focus the root". For the case these comments describe, the rebuild deliberately leaves the selection untouched — and Lexical doesn't need a selection move anyway. updateDOMSelection runs on any dirty-node commit and focuses the root when focus has left it. Restated once, accurately.
  • Tests: added coverage for armIdleSettle's guard, which had zero — it could be deleted and all 6 original tests still passed, even though it's the line the useRef-over-local design rationale exists to serve. Now 10 tests, and I mutation-tested each new one to confirm it actually fails without its guard.
  • Doc gaps now stated: not refcounted, nothing else clears it, what a missed resume costs, no-op outside editable marker modes, silently dropped when unmounted. Tagged EXPERIMENTAL: like its sibling markerSettleDelayMs.

The design question: Lexical has a tag for exactly this

SKIP_SELECTION_FOCUS_TAG and SKIP_DOM_SELECTION_TAG are real public exports in Lexical 0.43, and SKIP_SELECTION_FOCUS_TAG is read at the precise rootElement.focus({preventScroll: true}) call that steals focus. We use neither anywhere in the repo.

Every settle goes through one chokepoint — settlePendingNow's single editor.update(), the file's own "ONE deferred-settle computation". Tagging that update plausibly fixes the root cause for all clocks, including Enter and the forced commit, with no new public API, no host pairing obligation, and none of the leak risk this PR's boolean carries.

I could not verify it: jsdom doesn't reproduce the focus theft at all (the settle happens, focus stays put), so this needs a run in the real app. If it works, the right change is a few lines in the library and this PR's public method mostly goes away.

Known, unfixed, and deliberate

  • A leaked suspension has no release path. No timeout, no self-healing, no way to read the flag back, no log. Not data loss — getUsj() settles independently, and Enter and forced commit still settle — but it's an open-ended visible degradation. Notably, this file's other two suppressions both self-heal on purpose (appPlacedCaret releases on the next gesture; setTransientInput re-verifies and is cleared by setUsj). I did not add a watchdog or auto-release.
  • A remount silently resets the flag to false — <LexicalComposer key={viewOptions.verseLayout}> destroys the subtree, so a layout switch mid-palette drops the suspension and the symptom is the original bug. Both this and a resume dispatched while the handler is unregistered (markerMode !== "editable") are fixed by the same structural change: move ownership of the flag up to Editor and wire it like markerSettleDelayMs. I didn't do that unilaterally — it changes the shape of the PR.
  • The bare boolean. The suggested alternative is suspendMarkerSettle(): () => void returning a release, counted internally: "resume only what you suspended" becomes structurally true, double-release is harmless, and the release is the React cleanup value. Your call — I tagged the doc EXPERIMENTAL as the cheap escape hatch instead.
  • Not covered by tests: the EditorRef/MarginalRef wiring itself, and the re-registration-survival case the useRef comment exists to justify.
  • Pre-existing, separate ticket: the "pending literals serialize as literal bytes ParatextData parses" claim repeated in several comments is only true for a pend in a plain TextNode. A pend in a MarkerNode glyph isn't serialized at all — the adaptor skips MarkerNode as presentation-only — so the virtual settle is the only thing that saves it.

🤖 Generated with Claude Code

@timothy-mccormack
timothy-mccormack marked this pull request as ready for review October 12, 2026 12:28

@tjcouch-sil tjcouch-sil left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. This is the right shape, and cancelling the already-armed idle timer is the part a delay change could never do. On your open question: keep all three clocks suspended (idle, blur and caret departure). Suspending the blur clock is a better answer than a pre-open settle, and suspending departure keeps the document still while a palette is open.

One behaviour change, then docs.

1. Settle immediately on resume instead of re-arming a full idle delay

Paratext 9 doesn't reformat when its marker palette opens. It reformats when the palette closes (MarkerDropdownControl.cs, InternalClose). Re-arming a full delay instead leaves two gaps:

  • Edits made while suspended wait about a second after close. That includes the host's own typed commits (Space/*/\), which apply before the session ends. The reformat then happens about a second after the palette closes, which is surprising.
  • With the idle clock turned off (markerSettleDelayMs: -1, which a user can choose), resume arms nothing. Held edits then wait for the next keystroke or click (MEASURED: still pending 10 s after resume).

Suggestion: on resume, run one departure-style settle, i.e. everything pending except the node under the caret, the same exception the departure and blur clocks use. Then re-arm the idle clock as normal. That matches Paratext 9's reformat-on-close and closes both gaps. Please add tests for "blur-held edit settles on resume" and "idle off: held edit settles on resume".

2. TSDoc on setMarkerSettleSuspended

Say when to suspend. It has to be synchronously, before focus moves to the surface, e.g. in the trigger keydown. BLUR_COMMAND fires on the focus move, and a later suspend can't undo a settle that already ran. "Suspend when the surface opens" reads as if any time before the palette shows is fine.

Say how to drive it. It's a single flag, so the last call wins: a late resume from a surface that just closed lifts the hold for the one that just opened. Tell hosts to drive it from one derived "any surface open" state. A ref-counted token API would be safer, and it's cheap while this is experimental, but the docs are the minimum.

Smaller additions:

  • the flag resets when the Editor remounts;
  • what still settles while suspended: Enter, commitPendingMarkerEdits, settle-on-read in getUsj, and resolution within the same update;
  • "Note that a forced commit is not covered" is ambiguous: covered by the suspension, or protected by it?

3. Comments

Editor.tsx:578-585 says the dispatch "finds nothing to commit". That isn't always true. Dispatched outside an event (after an await or setTimeout), Lexical's $beginUpdate re-reads the DOM selection and can produce a selection-only commit. That commit runs updateDOMSelection, the focus-stealing path (MEASURED in jsdom). Please soften the claim. Optionally, avoid the command bus entirely: Editor owns the flag ref and hands it plus a re-arm callback to the plugin.

Stale or backward-facing comments:

  • MarkerEditPlugin.tsx:140-141 still describes "the two settle clocks". It's three now, including departure.
  • settleSuspension.test.tsx:217: "Regression test: before the guard this settled…" narrates history.
  • Editor.tsx:578-580 argues with a removed earlier version of the comment.

4. Tests

  • The departure guard is checked twice: when the microtask is queued (:1391) and again when it runs (:1397). Removing either one alone still passes all 10 tests, so the second check has no test of its own.
  • Nothing tests "blur held during the session, then resume, then it settles". It'll come naturally with 1.

5. PR description

It still describes the first commit:

  • it says caret-departure settles are untouched, but they're suspended now;
  • it says "two clocks" (three);
  • it says "six cases" (10 tests);
  • the blur guard is one line, not two.

Please update it and curate the squash message, since the first commit's message makes the same "departure untouched" claim.

@tjcouch-sil

Copy link
Copy Markdown
Member

One more suggestion: a safeguard so the editor can't get stuck with settling suspended.

If a host misses a resume, automatic settling stops. That could happen through a close path that skips it, an exception between suspend and resume, a missed unmount cleanup, or a palette whose show promise never settles. Nothing is lost when that happens, since getUsj settles on read, but pending marker text stays literal on screen until the user presses Enter.

Suggestion: when the editor regains focus (FOCUS_COMMAND) while suspended, lift the suspension and log a warning. The suspension exists to protect a surface that holds focus, and the editor only gets focus back once that surface is gone:

  • the palette was dismissed and focus restored;
  • the user clicked back into the text, which dismisses it;
  • or something took focus, which dismisses it too.

So the safeguard does nothing on a normal close (it fires right after the host's own resume), and it heals any missed resume at the next focus. It needs no timer, so a palette left open for a long time is unaffected.

Don't extend this to KEY_DOWN or CLICK, and keep your guard that stops them re-arming the idle clock. Some keys do reach the editor while a palette session is open, before the palette has focus: modifier and lock keys (e.g. Shift on the way to +), Dead, and IME keys. A KEY_DOWN lift would release the suspension just before the blur settle it exists to hold.

That said, the comment on the KEY_DOWN test overstates it: "The palette filters on keystrokes the editor still sees." In core, every key the table handles is claimed with stopPropagation in a capture-phase listener on window, so Lexical never sees the filter keystrokes. Only the pass-through keys above reach it. Worth rewording so nobody later "fixes" a problem that isn't there.

timothy-mccormack and others added 2 commits October 13, 2026 07:15
# Conflicts:
#	packages/platform/dist/index.js
#	packages/platform/dist/index.js.map
… resumed

Review feedback from tjcouch-sil on #25.

Resuming now settles what the suspension held — everything pending except the
node under the caret, the same exception the blur and departure clocks use —
before re-arming the idle clock. Paratext 9 reformats when its marker palette
CLOSES (MarkerDropdownControl.InternalClose), and resume is that moment. Merely
re-arming left two gaps: edits made while suspended, including the host's own
typed commits, reformatted an idle delay after the surface closed, which reads as
spontaneous; and with the idle clock turned off (markerSettleDelayMs: -1, which a
host may choose) nothing re-armed at all, so held edits stayed pending until the
next keystroke or click.

Add a safeguard for a host that misses a resume: when the editor regains focus
while still suspended, lift the suspension and log a warning. The editor only
gets focus back once the surface is gone, so this is a no-op on a normal close
and recovers a missed one at the next focus, with no timer involved. Gated on the
editor having actually LOST focus first, which the review did not call for but
testing made necessary: a host suspends synchronously before focus moves, so
there is a window where the suspension holds and the editor still has focus, and
any commit in it fires FOCUS_COMMAND and would otherwise release the suspension
on the very keystroke that armed it.

Deliberately not extended to KEY_DOWN or CLICK. Some keys do reach the editor
while a session is open, before the surface has focus — modifier and lock keys on
the way to a chord, Dead, and IME keys — and lifting on those would release the
suspension just before the blur settle it exists to hold.

Consolidate the departure guard to one site. It was checked both where the
microtask is queued and where it runs; removing the queue-time check alone fails
nothing, because the run-time check catches the same cases and the queue-time one
only avoided scheduling a microtask the other discards. The run-time check is the
load-bearing one — a suspend can land in the gap, since the host suspends in its
trigger keydown and a commit from that same keystroke can already have queued the
settle — and two tests now kill it.

Documentation, all of it asked for in the review:

- Say to suspend SYNCHRONOUSLY, before focus moves. BLUR_COMMAND fires on the
  focus move, so a later suspend cannot undo a settle that already ran, and
  "suspend when the surface opens" was not precise enough.
- Say it is a single flag, not a reference count, and that a host with more than
  one surface should drive it from one derived "any surface open" state.
- Say the flag resets when the Editor remounts, including on a verseLayout change.
- Say what still settles: Enter, commitPendingMarkerEdits, getUsj's settle-on-read,
  and resolution within the same update. Resolve the ambiguity in "a forced commit
  is not covered" — it is not held back.
- Soften the Editor.tsx claim that the dispatch finds nothing to commit. Dispatched
  outside an event, $beginUpdate re-reads the DOM selection and can produce a
  selection-only commit, which runs updateDOMSelection.
- Correct "the two settle clocks" to three, and cut the history narration the
  review flagged, here and in the tests.
- Reword the KEY_DOWN test comment: a host that claims filter keys with
  stopPropagation in a capture-phase listener never lets them reach Lexical, so
  the pass-through keys are what this test stands for.

Five new tests: the blur-held edit settling on resume, the same with the idle
clock off, a departure queued before a suspend and run after it, the focus
safeguard, and the focus-before-blur case the gate exists for. Each one was
mutation-checked against the guard it covers.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@timothy-mccormack

Copy link
Copy Markdown
Contributor Author

Thanks — all five points are in 42a816be. I also merged main first, since #15 had landed and touches Editor.tsx and Marginal.tsx.

1. Settle immediately on resume. Done. Resume now runs one departure-style settle — everything except the node under the caret — then re-arms. Both tests you asked for are in: settles a blur-held edit on RESUME, without waiting out an idle delay and settles a held edit on RESUME even with the idle clock turned off.

Worth noting why the existing tests didn't catch the gap: all three idle cases pend under the caret, which the resume settle excepts, so they passed unchanged after the behaviour change. The new cases use the no-caret pend shape.

2. TSDoc. Rewritten. It now says to suspend synchronously before focus moves, with BLUR_COMMAND firing on the focus move as the reason; that it's a single flag rather than a reference count, and that a host with more than one surface should drive it from one derived "any surface open" state; that the flag resets on an Editor remount, including a verseLayout change; and what still settles — Enter, commitPendingMarkerEdits, getUsj's settle-on-read, and resolution within the same update. The ambiguous sentence is gone: it now says plainly that a forced commit is not held back.

3. Comments. The Editor.tsx claim is softened to what you measured — dispatched outside an event, $beginUpdate re-reads the DOM selection and can produce a selection-only commit that runs updateDOMSelection — and it now points at synchronous dispatch as the reason that stays theoretical. "The two settle clocks" is three. Both bits of history narration are cut, along with two more of mine in the tests that the same rule catches.

4. The double departure guard — I found the inverse of what you measured, and removed a check rather than adding a test.

Removing the run-time check alone fails does not settle on an ordinary commit while suspended. Removing the queue-time check alone fails nothing, because the run-time check catches the same cases — the queue-time one only avoided scheduling a microtask that the other immediately discards, which no test can distinguish from scheduling it.

So I consolidated to the single run-time guard. That's the load-bearing one for the reason your review implies: the host suspends in its trigger keydown, and a commit from that same keystroke can already have queued the settle. There's now a test for exactly that interleaving — does not settle a departure queued before the suspend but run after it — which uses a discrete update so the listener queues the microtask before the suspend lands. Two tests kill the remaining guard.

5. PR description. Rewritten against the current state: three clocks, departure suspended, resume settling, 15 tests, the blur guard described accurately. I'll write a single unified squash message at merge rather than letting the first commit's "departure untouched" claim through.

Every new test is mutation-checked — I removed each guard in turn and confirmed the covering test fails. Details on the two that look like coverage and aren't are in the description.

Full packages/platform suite green (2361 passed, 3 pre-existing skips); typecheck and lint clean through nx.

🤖 Generated with Claude Code

@timothy-mccormack

Copy link
Copy Markdown
Contributor Author

Suggestion: when the editor regains focus (FOCUS_COMMAND) while suspended, lift the suspension and log a warning.

Implemented in 42a816be, with one addition your suggestion didn't call for. Testing made it necessary, and I think it's a real hole rather than a test artifact.

FOCUS_COMMAND alone fires too early. Your premise is that the editor only gets focus back once the surface is gone, and that holds — but there's a window at the start of a suspension where it hasn't left yet. A host suspends synchronously in the trigger keydown, before focus moves, exactly as the TSDoc now tells it to. In that window the editor still holds focus, and any commit can make Lexical re-assert the DOM selection and focus the root, which fires FOCUS_COMMAND. A safeguard keyed on focus alone lifts the suspension right there — on the very keystroke that armed it, before the surface has ever had focus.

This wasn't theoretical: adding the safeguard as suggested broke does not settle on an ordinary commit while suspended, which is the departure-leak regression test.

So the lift is gated on the editor having actually lost focus first. A flag set in the BLUR_COMMAND handler when it holds a settle, cleared on every suspension change. That keeps the safeguard firing in exactly the three cases you listed and nowhere else. Two tests: lifts a suspension the host never resumed, at the next editor focus (asserts the settle and the warning) and does not lift the suspension on a focus that arrives before the surface took it. Each is mutation-checked — removing the lift kills the first, removing the gate kills the second plus the departure test.

Not extended to KEY_DOWN or CLICK, and the guard that stops them re-arming the idle clock is untouched.

the comment on the KEY_DOWN test overstates it

You're right, and thank you — I'd written that from an assumption about where filter keys go rather than from core. Reworded to say what the test actually stands for: a host that claims those keys with stopPropagation in a capture-phase window listener never lets them reach Lexical, so what reaches the editor mid-session is the pass-through set — modifier and lock keys on the way to a chord, Dead, and IME keys — and any of those would re-arm the clock.

🤖 Generated with Claude Code

…nsion

Measured in the running app, which is the only place this shows: with the host's
suspend/resume wired up, `\` `nd` `\` reopened the marker palette and the
safeguard then closed it about a second later — the exact regression the
suspension exists to prevent, now caused by the thing meant to protect against a
missed resume.

The chain: the second `\` commits the typed marker and opens a replacement
palette in one keystroke. To apply that commit the host puts focus back in the
editor ON PURPOSE, mid-session. FOCUS_COMMAND fires, the safeguard reads it as
"the surface is gone, the host forgot to resume", lifts the suspension, and the
settle that follows steals focus from the palette that is about to reappear.

The `blurredWhileSuspended` gate does not help: a blur genuinely did happen when
the palette first took focus. Deferring the lift by a macrotask does not help
either, which the test for it exposed — the host re-asserts a suspension that is
ALREADY in force, and that is idempotent here, so nothing distinguishes
"re-suspended for the replacement" from "never released".

So the editor cannot tell, from focus alone, whether a host still needs its
suspension. It now warns and leaves the pairing where it belongs. That keeps what
the safeguard was actually worth — turning an invisible stuck flag into a line in
the log — without letting it break a legitimate flow. One warning per suspension,
so a commit-heavy session cannot flood the log.

Tests: the lift test becomes a no-lift test asserting the pend is still held and
the warning was issued, plus one pinning the once-per-suspension rule. The
mutation that reintroduces the lift fails the first of those.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@timothy-mccormack

Copy link
Copy Markdown
Contributor Author

The focus safeguard now warns instead of lifting — it was causing the regression it guards against

708bf025. Found by running paranext-core against this branch locally and exercising the case from your Windows pass; the full write-up is on paranext-core#2870.

Short version: with the host's suspend/resume wired up, \ nd \ still closed the marker palette, and the log named this safeguard:

[MarkerEdit] the editor regained focus while marker settling was suspended, so the
suspension was lifted...

The second \ commits the typed marker and opens a replacement palette in one keystroke. To apply that commit the host returns focus to the editor mid-session, deliberately. FOCUS_COMMAND fires, this lifted the suspension, and the settle that followed stole focus from the palette about to reappear.

Neither gate works:

  • The blurredWhileSuspended gate I had added does not help — a blur genuinely happened when the palette first took focus.
  • Deferring the lift by a macrotask does not help either, which the test for it exposed: the host re-asserts a suspension already in force, which is idempotent here, so nothing distinguishes "re-suspended for the replacement" from "never released".

So this warns now, once per suspension, and leaves the pairing to the host. The mutation that reintroduces the lift fails WARNS but does not lift when the editor regains focus while suspended.

Re-tested in the app afterwards: the palette stays open and the marker commits.

Also in this branch, unrelated: noteIndexAndHighlight.test.tsx > applies the highlight without committing an editor update is flaky on main — 3 failures in 8 runs on untouched code.

🤖 Generated with Claude Code

@tjcouch-sil

Copy link
Copy Markdown
Member

Thanks. Settle-on-resume, the TSDoc rewrite and the departure-guard consolidation all look right. On the safeguard, you're right that lifting on focus alone can't work. The host's commit paths (every keyboard commit restores the caret, and \ reopens a palette) focus the editor mid-session on purpose. And checking "still suspended?" a tick later can't separate "re-suspended for the replacement" from "never released".

I still want a safeguard, though. A missed resume silently turns settling off for the life of the editor. I think one adjustment makes the focus idea work.

1. Try focus-then-wait: lift only if the editor is still focused about a second later

  • On FOCUS_COMMAND while suspended (keeping your blur gate), start a timer of about 1 s.
  • Cancel it on BLUR_COMMAND. A surface took focus back: that's the \ reopen, where the replacement palette takes focus within roughly 70–230 ms.
  • Cancel it on resume. The host closed normally, e.g. after a keyboard commit.
  • When it fires, if the editor still holds DOM focus and is still suspended, lift the suspension, settle, and warn. That's a missed resume: the user is back in the text, and nothing took focus.

The difference from the macrotask attempt is that the check is about focus, not the flag. A legitimate mid-session focus is brief, because the replacement palette retakes focus or the host resumes. A missed resume leaves the editor focused.

It's also safe when it guesses wrong. The suspension only protects a surface that holds focus: a settle can only steal focus that is somewhere else. If the editor has held focus for a full second, a settle has nothing to steal, so lifting is harmless. The only remaining failure is a surface that takes over a second to grab focus. Its blur settle would then run, which is today's behaviour, now limited to that case.

It keeps what the focus idea had going for it: no change to the public API, and a palette left open for a long time is never affected, because the timer only runs while the editor itself has focus.

It also fixes the warning. Right now it fires on almost every keyboard commit, because each one restores the caret and so focuses the editor mid-session. People will learn to ignore a warn-level "the host may have missed a resume" that shows up in normal use. With this, it fires only when the safeguard actually lifts.

Tests with fake timers:

  • reopen: focus, then blur within the window → no lift;
  • normal close: focus, then resume within the window → no lift, no warning;
  • missed resume: focus, and nothing for the window → lifted, settled, warned;
  • the existing blur-gate case still holds.

2. The public docs still promise self-healing

Since 708bf025 the editor doesn't lift. Either way, these need to match whatever lands from 1:

  • editor.model.ts:181-185 still says "IF A RESUME IS MISSED, the editor heals itself … the suspension is lifted and a warning is logged".
  • The PR description's "A missed resume heals itself" paragraph says the same.

3. One stale comment

MarkerEditPlugin.tsx:794 (armIdleSettle) still says "the resume re-arms a full delay". Resume settles first now.

…ever resumed

Review items 1-3 from tjcouch-sil on #25. His adjustment to the safeguard, which
is the right one: the signal is not focus, it is how LONG focus is held.

A legitimate mid-session focus is brief. A host's commit path returns focus to the
editor on purpose to apply what the user chose, and then either a replacement
surface takes focus back within a few hundred milliseconds or the host resumes. A
missed resume leaves the editor focused and nothing cancels anything.

So FOCUS_COMMAND while suspended now arms a one-second lift rather than lifting:

- BLUR cancels it — something taking focus is the evidence the suspension is
  still doing its job, and the `\` reopen lands exactly here;
- a suspension change cancels it, which covers a normal close;
- when it fires, real DOM focus is re-checked before lifting. FOCUS_COMMAND is a
  notification, not proof: Lexical dispatches it where the root is not the active
  element, and a second is long enough for focus to move without a BLUR this
  handler saw.

Lifting late is harmless, which is what makes the wait acceptable: a suspension
only protects a surface that HOLDS focus, and a settle can only steal focus that
is somewhere else. If the editor has held focus for the whole window, a settle has
nothing to take. The one case left is a surface slower than the window to grab
focus; its blur settle then runs, which is the behaviour before any of this and is
now confined to that case.

It also fixes the warning. Warn-only fired on nearly every keyboard commit, since
each restores the caret and so focuses the editor mid-session; people would have
learned to ignore it. It now fires only when the safeguard actually lifts.

Four tests, one per case the review named, each mutation-checked:
- lifting immediately instead of waiting fails the reopen and normal-close cases;
- not cancelling on BLUR fails the reopen case;
- skipping the DOM-focus re-check fails the no-real-focus case. That last test
  originally passed for the wrong reason — `root.blur()` fires BLUR_COMMAND,
  which cancelled the lift — so it never exercised the re-check at all. It now
  never gives the root focus in the first place.

Also in this round: the public TSDoc promised self-healing on focus and now
describes focus-then-wait, and `armIdleSettle`'s comment said the resume re-arms a
full delay when it settles first.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@timothy-mccormack

Copy link
Copy Markdown
Contributor Author

Focus-then-wait is in — 315c58c4

You were right that the signal is duration, not focus. Implemented as you described: FOCUS_COMMAND while suspended (keeping the blur gate) arms a one-second lift; BLUR cancels it; a suspension change cancels it; when it fires, the suspension is lifted, held edits settle, and it warns.

One addition: real DOM focus is re-checked when the timer fires. FOCUS_COMMAND is a notification rather than proof — Lexical dispatches it where the root is not the active element — and a second is long enough for focus to move without a BLUR this handler saw.

Your four cases are the four tests, and each is mutation-checked:

Mutation Fails
lift immediately instead of waiting the reopen case and the normal-close case
don't cancel on BLUR the reopen case
skip the DOM-focus re-check the no-real-focus case

Worth flagging how that last one went, since it is the kind of thing that looks like coverage and is not. My first version of it moved focus away with root.blur() — which fires BLUR_COMMAND, cancelling the lift, so the re-check was never exercised and the mutation survived. It now never gives the root focus in the first place.

You were also right about the warning. Warn-only fired on nearly every keyboard commit, because each restores the caret and so focuses the editor mid-session — exactly the "people learn to ignore it" problem. It now fires only when the safeguard actually lifts.

2. The public docs. editor.model.ts described self-healing on focus and now describes focus-then-wait, including why focus alone is not evidence and why lifting late is harmless. The PR description's paragraph is rewritten to match.

3. The stale comment. armIdleSettle said the resume re-arms a full delay; it settles what was held first, then re-arms.

🤖 Generated with Claude Code

@timothy-mccormack

Copy link
Copy Markdown
Contributor Author

Ready for re-review — both branches are synced

315c58c4 here, 837b1a306ad on paranext-core#2870, so the pair can be reviewed together the way
you asked.

Nothing has changed here since the focus-then-wait safeguard you proposed — all five checks are
green and the branch is MERGEABLE. The only thing holding it is CHANGES_REQUESTED from your
708bf025 review.

Worth saying because it affects your sequencing: everything mechanical left on #2870 sits behind
this PR.
Its CI can't go green until setMarkerSettleSuspended is in the pinned editor, which
needs this merged and platform-yalc moved; then the committed dist gets the rebuild you asked
for. The full round-up is on #2870.

One result from over there that's really about this PR: with the suspension wired in and staged
locally, the Keyman check passes on macOS — \ opens the palette, the physical n/d filter to
nd, Enter commits \nd, no composed characters leaking into the filter or the text.

@tjcouch-sil tjcouch-sil left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. Focus-then-wait is what I was after, and re-checking real DOM focus when the timer fires is a good addition. Settle-on-resume, the TSDoc and the tests all look right. I also ran #2870 against this branch on Windows, and the palettes behaved correctly.

Two small non-blocking suggestions. Fine to do here or as a quick follow-up:

  1. Make the DOM-focus re-check also ask the document. The lift's re-check (MarkerEditPlugin.tsx ~:1298) reads root.ownerDocument.activeElement. A document keeps its active element after focus leaves the whole iframe (to the renderer's palette, or another panel), so the check can say "focused" when the editor isn't. That's exactly the "focus moved without a BLUR we saw" case it exists for. Adding root.ownerDocument.hasFocus() to the condition makes it mean what it says.
  2. Tag the resume settle like commitPendingMarkerEdits does. The resume microtask's settlePendingNow(lastAnchorKey) (~:794) commits without SKIP_DOM_SELECTION_TAG. If the editor doesn't hold DOM focus at that moment, Lexical's updateDOMSelection focuses the root. An example: the palette was dismissed by a click into another panel, and something other than the caret's node is still pending. commitPendingMarkerEdits already adds the tag when !holdsDomFocus() for this reason. The idle and departure settles have the same shape, but they predate this PR, so they'd be a separate ticket if you think it's worth one.

One nit: the "Apply a suspension change" doc block now sits above let blurredWhileSuspended instead of the function it describes.

timothy-mccormack and others added 2 commits October 15, 2026 06:00
The "Apply a suspension change" block sat above `let blurredWhileSuspended`,
so hover and TypeDoc showed it on that variable instead of on
`applyMarkerSettleSuspended`. Moved onto the function.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Moving the comment shifted positions in `packages/platform/dist/index.js.map`,
which the committed-output check compares. No code change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@tjcouch-sil

Copy link
Copy Markdown
Member

Thanks for moving the doc block. On the two non-blocking suggestions from my approval:

  1. hasFocus() in the lift's DOM-focus re-check (MarkerEditPlugin.tsx ~:1298). A document keeps its activeElement after focus leaves the whole iframe, so root.contains(activeElement) alone can say "focused" when the editor isn't.
  2. SKIP_DOM_SELECTION_TAG on the resume settle (~:794) when the editor doesn't hold DOM focus, the way commitPendingMarkerEdits does it.

Are you planning to do these here, or would you rather file them as a follow-up ticket? Either is fine. I'd just like to know which, so they don't get lost. The approval stands.

… blurred resume settle

Two follow-ups from review, both about a check that is true more often
than it should be.

The focus-then-wait lift re-checked focus with `activeElement`
containment alone. A document keeps its `activeElement` after focus
leaves the whole iframe, so that reports "focused" for an editor that is
not, and the lift would release a suspension the host is still
legitimately holding from another frame. It now also requires
`ownerDocument.hasFocus()`.

The resume settle now carries `SKIP_DOM_SELECTION_TAG` when the editor
does not hold DOM focus, the way `commitPendingMarkerEdits` does. A
resume usually arrives as the host's surface closes, with focus not yet
back in the editor, and without the tag Lexical re-asserts the DOM
selection for that commit and drags the caret — and focus with it — into
an editor the user has left. The tag release is disarmed immediately
after the update, which has already committed: left armed it fires
during the editor's own teardown commit.

Tests cover both, and fail without them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@timothy-mccormack

Copy link
Copy Markdown
Contributor Author

Both done here — 1fa541ed

Not a follow-up ticket: they are small and you had already described both precisely, so leaving them
to a ticket seemed the likelier way to lose them.

1. hasFocus() in the lift's re-check. The re-check now requires ownerDocument.hasFocus() as
well as containment. A test covers the exact case you described — the root is still the document's
activeElement, but the document itself has lost focus — and it fails without the change.

2. SKIP_DOM_SELECTION_TAG on the resume settle. settlePendingNow takes a
skipDomSelectionWhenBlurred flag that only the resume path passes, and adds the tag when
editorHoldsDomFocus is false. Two tests: the tag is present on a blurred resume, absent on a
focused one.

Scoped to the resume rather than applied in settlePendingNow for every caller. The departure and
idle clocks run while the user is in the editor, so the tag would almost always be inert there, and
widening it is a change to settle behaviour generally rather than the fix you asked for. Say if you
would rather it covered all three.

The tag release needs disarming immediately. releaseTagsAfterNextCommit is called right before
the update and disarmed right after. The settle is not discrete, but it always runs from a fresh
macrotask/microtask rather than inside another commit, so it has committed by the time it returns —
and a settle that finds nothing pending commits nothing at all, which leaves the listener armed. Left
armed it fires during the editor's own teardown commit and throws there.

One thing outside what you asked, for your call: editorHoldsDomFocus in shared-react has the
same gap as item 1 — containment with no hasFocus(). I did not change it, because Editor.tsx
depends on it in several places and widening a shared helper is your decision, not mine.

Full platform suite green: 2,367 passing, 3 skipped.

@tjcouch-sil

Copy link
Copy Markdown
Member

On editorHoldsDomFocus

Good catch, and I agree it has the same gap. I'd rather not change it in this PR, though. Its callers include LoadStatePlugin, applyUpdate, and EditorRef.isFocused(). Hosts use isFocused() to gate shortcuts and to defer provider sync, so adding hasFocus() changes behavior well outside the marker palette, and none of that is covered by this PR's tests. Would you mind doing it as a separate PR, or filing a follow-up ticket? Either way, it should include a pass over those callers, isFocused() especially.

@timothy-mccormack

Copy link
Copy Markdown
Contributor Author

Agreed, and thanks for listing the callers — isFocused() in particular makes this bigger than it
looks. I'll leave editorHoldsDomFocus alone here and we'll raise it as a follow-up ticket rather
than a drive-by PR, so the caller pass you're asking for gets its own review.

For the record, the callers in the tree today are LoadStatePlugin (editorHasFocus),
Editor.tsx's holdsDomFocus — which backs applyUpdate, the two other SKIP_DOM_SELECTION_TAG
sites, and EditorRef.isFocused() — and now this plugin's own blurred-resume check, which is the
one place already using the stricter test.

Worth flagging for whoever picks it up: the two are not interchangeable. Containment answers "is the
user's caret inside this editor", which is what isFocused() is documented to mean and what a host
gating a shortcut or a PDP-sync deferral wants; hasFocus() additionally answers "is this document
the one the OS is sending keystrokes to". A host in a background iframe wants different answers from
those two, so the pass may end up splitting them rather than tightening one.

@tjcouch-sil

tjcouch-sil commented Oct 16, 2026 •

Copy link
Copy Markdown
Member

Thanks. A follow-up ticket for editorHoldsDomFocus works for me, and the split you describe (caret-in-editor vs. document-has-keystrokes) is a good note for whoever picks it up. Please file the JIRA ticket. One correction for the record: the blurred-resume check in this plugin (MarkerEditPlugin.tsx :731) calls editorHoldsDomFocus, so it uses containment only. The stricter hasFocus() test is in the suspension-lift re-check (:1320).

My earlier comment was meant to include two findings on the resume-settle tag, but they didn't make it into the post. Here they are:

1. The tag release is disarmed before the settle commits

settlePendingNow arms releaseTagsAfterNextCommit, calls editor.update(...), then calls releaseTag() straight away. The comment says that's safe because the update "has already committed" by then. It hasn't. In Lexical 0.43, $beginUpdate commits synchronously only when the update is discrete (_flushSync). Otherwise it schedules the commit with scheduleMicroTask, and running inside a fresh microtask doesn't change that. The resume path calls this from queueMicrotask without discrete, so the release is always disarmed before the commit it exists to catch.

What it costs: when the settle commit changes nodes, Lexical resets its pending tags anyway, so nothing leaks. When the commit only moves the selection, SKIP_DOM_SELECTION_TAG stays pending and rides onto the next commit. That's the failure releaseTagsAfterNextCommit's own doc describes: a leftover tag stops a later focus() from focusing the editor. A selection-only commit is a real possibility here. As the setMarkerSettleSuspended comment in Editor.tsx notes, an update that runs outside an event re-reads the DOM selection, and that alone can produce one.

Suggestion: do what commitPendingMarkerEdits (Editor.tsx ~:690) already does. Make the update discrete when skipDomSelection is set, e.g. editor.update(fn, skipDomSelection ? { discrete: true } : undefined). Then the commit has really happened when releaseTag() runs, and disarming right away is correct. That's also why disarming fixed the teardown throw you saw. Please also correct the comment.

The current tests can't catch this. The tag is added inside the update, so it shows up on the settle commit whether or not the release ever fires. A test that would catch it: a blurred resume whose settle commit only moves the selection, then assert that the next commit doesn't carry SKIP_DOM_SELECTION_TAG.

2. (Minor) The "does NOT tag … when the editor still holds DOM focus" test can pass vacuously

It records only the first commit after resume and asserts that commit has no tag. If the settle commits nothing, for example because the only pending marker is in the node lastAnchorKey excludes, the listener catches some unrelated commit (or none), and the assertion still passes. Because it asserts an absence, this test also can't fail when the fix is missing.

Suggestion: also assert that the settle actually ran (the marker settled, e.g. para.getMarker() is "s2") and that the commit the listener captured is that settle.

…ased

The resume settle armed `releaseTagsAfterNextCommit` and disarmed it
immediately after `editor.update()`, on the claim that the update had
committed by then. It had not. Lexical commits inside the call only for a
`discrete` update — `pendingEditorState._flushSync = discrete`, otherwise
`scheduleMicroTask($commitPendingUpdates)` — and running from a fresh
microtask does not change that. The release was therefore always disarmed
before the commit it existed to catch.

When the settle changes nodes Lexical resets its pending tags anyway, so
nothing leaked. When the commit only moved the selection — which an
update running outside an event can produce by re-reading the DOM
selection — `SKIP_DOM_SELECTION_TAG` stayed pending and rode onto the
next commit, where a leftover tag stops a later `focus()` from focusing
the editor.

The tagged update is now discrete, the way `commitPendingMarkerEdits`
does it, so disarming straight afterwards is correct. The comment that
asserted otherwise is corrected.

Tests: the release test keeps the LIVE tag set rather than a copy, since
the release deletes from it in place and a snapshot looks identical
either way. It fails without `discrete`.

The "does NOT tag when focused" test asserted an absence that held
whether or not the settle ran. It now asserts the precondition that
drives the branch — the editor really holds DOM focus at resume. It
deliberately does not assert that the settle mutated anything: with focus
on the root and no caret moved, the pending marker IS the caret's own
node, which every settle trigger excepts, and moving the caret to avoid
that settles the pend before there is anything to suspend.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@timothy-mccormack

Copy link
Copy Markdown
Contributor Author

Both findings were right — f0a86430

1. The tag release was disarmed before the commit

You're right, and my comment asserted the opposite of what Lexical does. Checked it in
Lexical.dev.mjs rather than take it on trust:

pendingEditorState._flushSync = discrete;                 // 8812
...
if (pendingEditorState._flushSync) { $commitPendingUpdates(editor); }   // 8889
else if (editorStateWasCloned) { scheduleMicroTask(() => $commitPendingUpdates(editor)); }

So the release was disarmed before the commit on every resume, and the microtask the resume already
runs in makes no difference. The tagged update is discrete now, as you suggested, and the comment
says what actually happens.

That also explains the teardown throw I described as evidence for the old arrangement: the listener
was never consumed, so it was still armed when the editor unmounted. I had the symptom right and
the cause backwards.

2. The focused test was vacuous — and so was my first replacement

You were right, and it took three attempts to get a test that bites, which is worth writing down.

The release test. My first rewrite still passed with discrete removed. The watcher copied the
tag set with new Set(tags), and the release deletes from the live set in place — so a snapshot
taken during the commit is identical either way. It now keeps the live Set and asserts the tag is
gone afterwards. Passes with the fix, fails without.

The focused test. I could not satisfy the "assert the settle actually ran" half, and would
rather say so than imply I had. With focus on the root and no caret moved, the pending marker IS
the caret's own node, which every settle trigger excepts — so nothing settles, which is why my
first attempt failed with expected 's1' to be 's2'. Moving the caret to a different node fixes
that and breaks it the other way: the departure settles the pend before there is anything to
suspend, so the resume has nothing left to do.

So it asserts the PRECONDITION instead — that the editor really holds DOM focus at resume, which is
what sends the settle down the untagged path — plus the absence. That pins it to the branch it
describes without claiming more. The limitation is written into the test. If you can see an
arrangement I've missed, I'll take it.

3. Your correction

Noted, and you're right: the blurred-resume check calls editorHoldsDomFocus, containment only;
hasFocus() is in the lift re-check. I'd got that backwards in my last comment, and in the
follow-up ticket summary — both corrected.

The JIRA ticket is being filed from our side.


Full platform suite green: 2,368 passing, 3 skipped.

@tjcouch-sil

Copy link
Copy Markdown
Member

Thanks. The discrete fix and the new release test both look right. I checked the test's premise: after a commit that changes nodes, Lexical 0.43 starts a new tag set rather than clearing the old one, so keeping a reference to the live set does what you say.

On the focused test, and your question about an arrangement you missed: as written, it still can't fail. The resume commits nothing, so if someone dropped the "only when blurred" condition, nothing would get tagged and the test would still pass. Here's an arrangement that should get a real settle without moving the caret (untested):

  1. Use two heading paragraphs, with the caret in the first and the editor focused.
  2. setSuspended(editor, true).
  3. Only then pend a glyph edit on the second paragraph's marker. Settling is suspended, so neither the departure nor the idle clock takes it.
  4. Resume. The settle now resolves the second paragraph, because it isn't lastAnchorKey. Use watchForSettleCommit on that paragraph and assert the tag is absent.

The caret never moves after the pend exists, so the departure settle you ran into never happens. Non-blocking: if it turns out not to work, the current test is fine to keep.

@timothy-mccormack
timothy-mccormack merged commit 5707190 into main Oct 19, 2026
5 checks passed
@timothy-mccormack
timothy-mccormack deleted the pt-4611-settle-pause branch October 19, 2026 18:34
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