Repository navigation
Let a host suspend the gesture-free marker-settle clocks (unblocks PT-4611) - #25
Conversation
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>
Self-review pass (5 analysis agents) — 1 critical defect found and fixed, 1 design question for youI 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 suspendedThe 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 Proven, not theorised: The realistic trigger is the host's own debounced pre-save Fixed by guarding the departure queue and its microtask, with a regression test. Also fixed in this round:
The design question: Lexical has a tag for exactly this
Every settle goes through one chokepoint — 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
🤖 Generated with Claude Code |
tjcouch-sil
left a comment
There was a problem hiding this comment.
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 ingetUsj, 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-141still 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-580argues 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.
|
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 Suggestion: when the editor regains focus (
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 That said, the comment on the |
# 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>
|
Thanks — all five points are in 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: 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 3. Comments. The 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 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 — 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 🤖 Generated with Claude Code |
Implemented in
This wasn't theoretical: adding the safeguard as suggested broke So the lift is gated on the editor having actually lost focus first. A flag set in the Not extended to
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 🤖 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>
The focus safeguard now warns instead of lifting — it was causing the regression it guards against
Short version: with the host's suspend/resume wired up, The second Neither gate works:
So this warns now, once per suspension, and leaves the pairing to the host. The mutation that reintroduces the lift fails Re-tested in the app afterwards: the palette stays open and the marker commits. Also in this branch, unrelated: 🤖 Generated with Claude Code |
|
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 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
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:
2. The public docs still promise self-healingSince
3. One stale comment
|
…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>
Focus-then-wait is in —
|
| 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
Ready for re-review — both branches are synced
Nothing has changed here since the focus-then-wait safeguard you proposed — all five checks are Worth saying because it affects your sequencing: everything mechanical left on #2870 sits behind One result from over there that's really about this PR: with the suspension wired in and staged |
tjcouch-sil
left a comment
There was a problem hiding this comment.
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:
- Make the DOM-focus re-check also ask the document. The lift's re-check (
MarkerEditPlugin.tsx~:1298) readsroot.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. Addingroot.ownerDocument.hasFocus()to the condition makes it mean what it says. - Tag the resume settle like
commitPendingMarkerEditsdoes. The resume microtask'ssettlePendingNow(lastAnchorKey)(~:794) commits withoutSKIP_DOM_SELECTION_TAG. If the editor doesn't hold DOM focus at that moment, Lexical'supdateDOMSelectionfocuses 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.commitPendingMarkerEditsalready 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.
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>
|
Thanks for moving the doc block. On the two non-blocking suggestions from my approval:
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>
Both done here —
|
On
|
|
Agreed, and thanks for listing the callers — For the record, the callers in the tree today are Worth flagging for whoever picks it up: the two are not interchangeable. Containment answers "is the |
|
Thanks. A follow-up ticket for 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
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, Suggestion: do what 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 2. (Minor) The "does NOT tag … when the editor still holds DOM focus" test can pass vacuouslyIt 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 Suggestion: also assert that the settle actually ran (the marker settled, e.g. |
…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>
Both findings were right —
|
|
Thanks. The 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):
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. |
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:
markerSettleDelayMsafter 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.What
EditorRef.setMarkerSettleSuspended(suspended: boolean), dispatching a newSET_MARKER_SETTLE_SUSPENDED_COMMANDthat the marker-edit engine reads at all three clocks.MarginalRefforwards it like the rest ofEditorRef.Suspending cancels an already-armed idle timer. That is the part a delay change cannot do:
markerSettleDelayMsis 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_COMMANDfires 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_COMMANDis a notification rather than proof.What still settles, because the host or the user explicitly asked for it: Enter,
commitPendingMarkerEdits, the settle-on-read insidegetUsj, 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:
Full
packages/platformsuite green (2361 passed, 3 pre-existing skips);typecheckandlintclean through nx.🤖 Generated with Claude Code
This change is