Skip to content

Fix the editor context menu and \id-line editing - #14

Merged
tjcouch-sil merged 82 commits into
mainfrom
standard-view-pt-4195
Oct 2, 2026
Merged

tjcouch-sil merged 82 commits into
mainfrom
standard-view-pt-4195

Conversation

@tjcouch-sil

@tjcouch-sil tjcouch-sil commented Sep 15, 2026 •

Copy link
Copy Markdown
Member

What

Editor-side fixes surfaced while hand-QAing (and then reviewing) an endnote insert item in paranext-core — the host contributes the insert items, and with four of them the right-click menu is eight items long.

Three in ContextMenuPlugin's right-click menu:

  1. The list was clipped with no way to reach the rest. The menu reuses .typeahead-popover ul, whose max-height: 200px is sized for the marker typeahead's long, filterable list. The context menu is a short fixed list at ~36px per item, so it overflows that cap at seven items — the last items sit behind a fold, and the menu has no filter to narrow the list with.
  2. Its own scroll closed it. The close-on-scroll listener is registered on window in capture phase, which fires for a descendant's (non-bubbling) scroll event too — so scrolling the menu's own list to reach the clipped items closed the menu instead.
  3. The fold was invisible, and the menu was unannounceable. Even capped to the viewport, a panel shorter than ~270px still clips it, and the inherited rule pairs overflow-y: scroll with a hidden scrollbar — so nothing on screen said there was more. Separately, the items were role="option" inside a bare ul, which is not a listbox, so the role had no list to mean anything in and nothing told an assistive technology which item the arrow keys had highlighted.

Together, (1) and (2) made the items past the fold unreachable by mouse entirely.

And one unrelated data-rendering bug in the USJ forward adaptor, found by chasing an endnote that a paranext-core E2E spec inserted into the \id line: it saved to USFM correctly but the editor rendered none of it after a chapter re-read.

createBook was the one content container the forward adaptor did not recurse into. It flattened the book's content with getTextContent, which returns "" unless the content is exactly one plain string — so the moment anything else sat in the \id line, the whole content went with it. The line rendered as a bare \id JON, losing both the note and the line's own description text, and the next save wrote that truncation back to the file. The reverse adaptor already recursed the book node's children, so this was the asymmetric half of the pair and broke the round-trip invariant the corpus suite exists to hold.

Changes

  • ContextMenuPlugin: ignore scroll events originating inside the menu; still close on a scroll of anything else, which is what that listener is for (the menu is positioned in fixed viewport coordinates, so the content it was opened over moves out from under it).
  • ContextMenuPlugin: role="listbox" + an accessible name on the option list, and aria-controls/aria-activedescendant on the focused editor root while the menu is open. This completes the pattern the plugin had already started rather than moving to menu/menuitem: focus deliberately stays in the contenteditable the whole time the menu is open — that is what keeps the selection the chosen item acts on — and option-list + aria-activedescendant on the focused element is the pattern for a popup whose owner keeps focus. It is also what Lexical's own typeahead menu does. menu/menuitem would require moving focus into the menu, putting that selection at risk. The item ids move to their own namespace, because Lexical's shared typeahead-* ids are reused by every menu built on its typeahead and an aria-activedescendant IDREF resolving to another menu's item announces the wrong thing.
  • editor.css: cap .typeahead-popover.auto-embed-menu ul to the viewport instead of 200px, and give it overflow-y: auto + scrollbar-width: thin so the fold is visible when the panel is genuinely too short. The .typeahead-popover qualifier is needed to out-specify the shared rule — the plugin puts both classes on the menu's outer element and nests a second .typeahead-popover inside it.
  • usj-editor.adaptor.ts: createBook now recurses its content like every other container, so the two adaptor halves agree. getTextContent had no other caller and goes with it.
  • Adds the plugin's first tests (it had none). They drive real DOM keydown events rather than dispatching Lexical commands, which is what makes the propagation the menu actually depends on observable: its key handling sits on a capture-phase listener on document, ahead of Lexical's bubble-phase listener on the root element. One test is the control — Enter reaches Lexical once the menu has closed — so "Lexical never saw Enter" means the menu claimed it rather than that the harness never routed it. Three more cover the ARIA wiring, including that it is torn down when the menu closes.
  • Adds a corpus fixture for a note in the \id line (round-trip identity in all five view modes, plus the transform fixed point) and a forward anchor on the book node's children — identity alone is blind to a bug mirrored on both sides, which is exactly the shape this one had.

The \id line's content now edits like paragraph content

Fixing createBook made the \id line's content survive a reload; hand QA then showed that everything else about editing it still treated the line as a single run of literal header text. The line is a BookNode at document root, not a ParaNode, but Paratext 9 treats its text as ordinary content — footnotes and character styles included — so each place below now treats the book like a paragraph. The \id GEN prefix stays one immutable decorator the caret cannot enter; only the content after it changed.

This closes PT-4613 — "backslash menu in the \id line lists paragraph markers but committing one does nothing". Its DoD offered a choice between offering only insertable markers and inserting everything offered; both halves landed, because the two triggers need different answers. \ no longer lists paragraph markers in the line (it is character source there now), and the Enter palette — which offers them deliberately — now inserts instead of doing nothing. The rule behind it, a menu offers nothing it cannot insert, is written down in docs/standard-view-invariants.md along with the \id-line rule the defects below all came from; the host-side half is in paranext-core's .context/standards/Standard-View-Invariants.md.

  • Notes in the line can be navigated and expanded (shared-react). ArrowLeft could not get back past a note in the line, and a note at the line's end never expanded for inline editing, because both guards assumed a book held one run of text.
  • \ opens the inline palette there (markerMenuContext.utils.ts). With no ParaNode ancestor the trigger reported paragraph source; even forced to character source it would have listed nothing, because the character list filters on the enclosing paragraph's marker. A caret in the line now reports character source with paraMarker: "id": the character styles valid under id, plus every note style — which is what Paratext 9 lists there.
  • A paragraph pick starts its paragraph after the line (markerMenuApply.utils.ts). The Enter palette's Enter did nothing: there was no paragraph to retag or split. The pick now splits the line at the caret, closing and reopening an open character span across the cut. It lives in $splitParagraphWithMarker, because the Enter palette calls that directly and never goes through the \ palette's apply path.
  • Typed markers settle ($rebuildBook, a fourth settle scope beside paragraphs, note content and chapters). The line had no settle scope, so \nd Lord\nd* typed there stayed literal on screen while the save wrote a real span. Like the note scope, it re-tokenizes only the content and preserves the book node, its code and its prefix. The read-only settle ($settledUsj) mirrors it, the undo re-pend scan descends into the line, and live typing display-maps space runs there the way load and settle already did.
  • A typed \p , \ip or \c ends the line immediately, starting its paragraph or chapter right after the book, with the tail moving into it and the caret following — the same split a paragraph gets. (It previously stayed literal on screen and only turned into a paragraph after a reload.) Bytes that literally begin with \p tokenize to a wrapper indistinguishable from the tokenizer's implied \p, so they are told apart by the bytes and leave the line empty.
  • Backspacing away the marker of the paragraph below the line merges it into the line (markerEditDeletion.utils.ts). The merge only recognized a ParaNode above, so below the \id line it reset the marker to \p with a fresh prefix — and every further Backspace deleted the re-created marker and grew it back again.

Also in this PR: overscroll-behavior: contain on the context menu's list, so a wheel gesture that reaches the end of the list no longer chains to the page and closes the menu.

Since the last update

Review round 5 (lyonsil), answered in the threads. Each behavior fix has a test that failed before it.

  • Drag-moving or IME-replacing a selection that starts at the \id line no longer deletes the \id GEN glyph. REMOVE_TEXT_COMMAND is now narrowed past the glyph, like delete, typing over, paste and cut.
  • getUsj() no longer duplicates a paragraph when an unknown-marker paragraph's rejoin into the \id line is pending, it holds a transient marker declaration, and its text splits into more than one block. The transient pass now skips a scope the rejoin already claimed.
  • formatPara retags the header paragraphs (\h, \mt1) when a selection from the \id line ends in the \c 1 line, as it already did when the selection ended one paragraph later. The chapter itself is still never retagged.
  • Cleanups: $isBookPrefixGlyph (in shared) names the any-marker-mode prefix check that three sites spelled out, and $isBookPrefixNode documents why it excludes the editable glyph; $narrowSelectionPastBookPrefix skips its node walk unless the selection can reach the prefix; a one-off helper replaced by $findMatchingParent; $createBookLine test fixtures follow the repo's tree-shaped append rule.

Previous update (2026-09-30)

Home no longer puts the caret in front of the \id GEN glyph (ParaMarkerPrefixCursorGuardPlugin). The glyph is a contenteditable="false" island at the start of the line, so Home and Ctrl+Home put the browser caret on the boundary before it, at (book, 0). Only a click there was corrected, so after Home, typed text rendered in front of \id GEN while the save (which never writes the glyph as its own node) wrote it after the book code, and the line changed shape on the next load. Two changes, each with a test that failed before it:

  • A collapsed caret that lands at (book, 0) is moved just past the prefix on SELECTION_CHANGE_COMMAND, the same place a click there already goes. A Shift+Home selection is left alone, since every delete, type-over, cut and paste already narrows it past the prefix.
  • A BookNode transform moves anything that still lands in front of the prefix (a drop, a programmatic insert) to directly after it, in order. The save drops the prefix wherever it sits, so the editor now shows the line exactly as the file will read. docs/standard-view-invariants.md states the rule: the prefix is always the book's first child.

Rebased onto main, past #23 (the copy limit). No source conflicts; the mid-history dist rebuild conflicted only in generated dist/, and one commit on top regenerates packages/platform/dist from the rebased source.

Previous update (2026-09-25)

Review round 4 (lyonsil), answered in the threads. Each behavior fix has a test that failed before it.

  • Guarded-mode paragraph merges (the second Backspace/Delete at a paragraph boundary) drop the merging paragraph's own marker glyph. Before this, \q fused onto the previous line's text as first\qsecond, and into the \id line as …Book\hHeader.
  • formatPara (the paragraph-style control) never deletes text. A selection that starts in the \id line now splits the line at its start and retags each paragraph it covers, one at a time, so a \c between them is left alone. Before this, the selected text was deleted, including the start of any verses it reached.
  • Cmd+Backspace in the \id line deletes back to the visual line start and stops at the \id GEN glyph. Before this, the line boundary stepped over the glyph and deleted it.
  • A selection that spans the \id glyph (Ctrl+A is the common case) is narrowed to start just after the glyph for delete, typing over, paste and cut. Before this, Backspace/Delete did nothing, and typing, paste or cut removed the glyph. Guarded mode's two-step range delete narrows the same way.
  • An \id-line settle with the caret directly before a leading note puts the caret back before the note. Before this, it landed inside the collapsed note.
  • Cleanups: a dead branch in ArrowNavigationPlugin, a shared helper for the char/comment-mark ancestor walk, CharStackBreak.parent is undefined rather than null, a duplicate selection normalize removed, and two post-settle calls no longer rebuild a whole fragment just to read its content nodes.

Previous update (2026-09-24)

Review round 3 (lyonsil), answered in the threads. Each fix has a test that failed before it.

  • ArrowLeft in the \id line is refused only right after the prefix (an element point or offset 0). Before this, it was refused anywhere in the first text run or a leading opener.
  • formatPara routes from the selection's start, so a forward drag from the line into the next paragraph splits the line and no longer retags the book.
  • Word and line deletes (DELETE_WORD_COMMAND, DELETE_LINE_COMMAND) can't remove the \id GEN prefix.
  • A caret at (book, 0) reached by Home, selectStart() or a programmatic selection is moved past the prefix in $applyMarkerMenuSelection, before every pick kind. Character and note picks no longer land in front of the prefix.
  • The book split treats a caret at the start of an opening glyph as before the span (no doubled opener). It refuses a selection that reaches into a note nested in the line before removing anything, so a refusal leaves the document unchanged.
  • $rebuildBook's sid carry-over pairs against the live post-splice nodes, so a preserved (sentinel) verse no longer shifts the pairing.
  • The context menu scrolls the highlighted item into view using rect math, so padding above the list no longer affects it.
  • Test and comment fixes: every test that builds the \id line now uses one composable $createBookLine(code, ...children) helper (in react-test.utils.tsx, shared by both packages) instead of about 40 hand-built copies, the "BEFORE a note" settle test now exercises the crash shape, and three comments corrected.

Previous update (2026-09-23)

Two automated review rounds (lyonsil), answered in the threads. Each behavior fix below has a test that fails without it.

The right-click menu (ContextMenuPlugin)

  • Modal while open, like a native context menu: every key except a bare modifier or an IME composition is claimed, so a typed character, Backspace or Delete can no longer land in the text behind the menu. Composing keystrokes (including an IME's confirming Enter) pass through untouched.
  • The highlight follows mousemove, not mouseenter: a menu clamped into the viewport under a stationary pointer opens with nothing highlighted, so the next Enter can't run an item the user never chose.
  • Arrow keys scroll the highlighted item into view within the list; focus landing inside the menu (a press on a disabled item) still counts as the menu holding the keyboard; a window-targeted scroll no longer throws; items are keyed stably, so an options rebuild no longer remounts them mid-click.

Note callers match Paratext 9. Only \f and \x take the project's default caller; every other note marker falls back by first letter as PT9's GetFallbackCaller does, so a new \fe always gets the caller + (\fe + …), never the project's custom footnote caller.

The \id line

  • Read-only settle: a note in the line no longer comes back as a literal U+FFFC from getUsj()/onUsjChange while an edit is pending ($settledBookLine replaced sentinels in a throwaway copy).
  • The caret stays out of the immutable \id GEN prefix: ArrowLeft from a leading span or from the note-hop landing, and clicks/Home/selectStart() at (book, 0); Backspace/Delete aimed at the prefix are refused; ArrowRight steps over a collapsed note in the line.
  • Splitting the line is as safe as splitting a paragraph, and now shares the risky parts with it: the break-and-lift step ($breakAndLiftCharStack) and the closing-glyph caret step ($stepCaretPastClosingGlyphSpan), plus up-front glyph normalization. That fixes a doubled opener, an unmatched closer cut in two, a pick at (book, 0) moving the prefix out of the book, and selections from the line into the next paragraph (routed by the selection's start). formatPara (the toolbar paragraph style) now splits after the line instead of retagging the book into a paragraph.
  • Rebuilds: the caret is restored from the live nodes after the sentinel splice (typing a closed span right before a note threw "selection has been lost"); an element-point caret (between two children) no longer jumps on settle — fixed in the shared capture, so all four rebuild scopes get it; verse sids carry over; the Enter palette in the line validates against [id], so it offers only markers valid after \id.
  • An unknown marker typed in the line rejoins it. Pausing mid-marker, or fixing a typo like \ndd, split a paragraph off after the line that the correction never rejoined, so the save gained an untyped \p. The rejoin now accepts the book as its predecessor and folds the paragraph back through $rebuildBook as trailing content. The read-only settle mirrors it, and both use one shared paragraph joiner.
  • Structure keyboard modes treat the line as a block: guarded-mode Backspace merges the paragraph below into it, and protected mode blocks Delete at its end.
  • expectTier2FixedPoint now drives the line through $rebuildBook; one serialized "synthesized marker" predicate replaces two private copies.
  • A paragraph pick inside a comment highlight in the line splits it (paranext-core's translator comments are TypedMarkNode wrappers). The split lifts out of marks as well as char spans, in any nesting, and both halves keep the comment's ids.

Ordinary paragraphs, same nesting (pre-existing). Enter, or a paragraph pick, with the caret in a char span nested with a comment highlight (either way round) skipped the char-stack-aware split and fell through to Lexical's generic one. That left \p \nd thi (no closer, comment gone) and \p ng (style gone), and typing continued unstyled. The paragraph split's entry checks now see through comment marks, so it reaches the same shared lift the \id split uses: both halves keep the style with real glyphs and keep the comment, and the caret lands inside the reopened style. Notes still get their \fp break.

Not changed: the regex/tokenizer whitespace drift in tokenizedBookLine is unreachable today; multi-line paste into the line is pre-existing.

Previous update (2026-09-18)

Code-review fixes (2026-09-18), each with a test that fails without it:

  • The \id line split where the tokenizer does not (tokenizedBookLine). Telling a typed leading \p from the tokenizer's implied one re-read the bytes, and the re-read disagreed with the tokenizer at both edges. It skipped any leading whitespace, but the tokenizer drops a leading run only when it holds a line break, so \p more emptied the line and added a whitespace-only \p paragraph, in the live settle and in the saved USJ alike. It also ended the marker name only at whitespace, where the tokenizer also ends it at \, | and ZWSP, so a \p typed straight before \bd … silently vanished. The pattern now mirrors the tokenizer on both edges, pinned by a table of the shapes where the two could disagree (six rows fail against the old pattern).
  • A paragraph pick in the \id line no longer deletes the selection and then gives up ($splitBookWithMarker). The split can lift its break point only out of char spans, so inside an annotation's mark wrapper it bailed — after it had already removed the selected text. Whether the split can reach the book is now decided before anything is mutated.
  • The context menu leaves keys to whatever has focus once focus leaves the editor (ContextMenuPlugin). Nothing closes the menu on Tab, and its listener hears the whole document, so a focused button's Enter was swallowed (or, with an item highlighted, ran that item). The menu now drives Arrow/Enter only while the editor, or nothing, holds focus; Escape still closes it from anywhere. #2653 depends only on the editor-focused case, which is unchanged.
  • A stale comment in the undo re-pend scan still said the scan never descends into books.

Rebased onto main, past #12 (the font fallback chain). Every source commit is patch-identical to before the rebase. #12's own dist rebuild conflicted with this branch's, so one commit on top regenerates packages/platform/dist from the rebased source.

The context menu owns Enter for as long as it is open and the editor has focus (ContextMenuPlugin). It used to claim Enter only while an item was highlighted, and a right-click highlights nothing. Enter pressed straight after one therefore reached Lexical, which still has DOM focus behind the menu, and split the paragraph; in paranext-core it instead opened a paragraph palette underneath the still-open menu. Enter is now claimed whenever the menu is up. It invokes the highlighted item if that item is enabled, and otherwise is swallowed with the menu left open, so a disabled highlighted option is a deliberate no-op rather than a key that falls through. Two new tests, Enter with nothing highlighted and Enter on a disabled option, both assert that Lexical never sees the press and the menu stays open.

ArrowLeft walks back into a character span in the \id line (ArrowNavigationPlugin). At the start of the text after a span (\id GEN \nd LORD\nd* Berean…), the book-line guard claimed the press and called preventDefault, so ArrowLeft was a dead key there. The guard used "parent is the book node" to mean "nothing to the left", which stopped being true once the line could carry spans. It now checks whether anything other than the line's immutable \id GEN prefix is to the left. The new test asserts defaultPrevented rather than caret position, because jsdom performs no native move and a position check would pass either way. Confirmed red against the old guard.

A racy ScriptureReferencePlugin test now settles before asserting (ScriptureReferencePlugin.test.tsx, test-only). After the rebase, macOS CI failed "stops at the next verse marker for an empty verse with an editable marker" twice in a row, while ubuntu and local runs passed. The placement commits offset 0 of the next verse's marker. The asserted position, the end of this verse's marker, only appears once a selectionchange reads the DOM selection back and Lexical resolves the collapsed offset-0 point to the end of the previous text. jsdom fires that event a macrotask later, and the test asserted right after act(). It had passed only because the setup selection's own queued event happened to land after the placement. The test now flushes the setup event first and the placement's event before asserting, using the file's existing flushQueuedEvents. Forcing the macOS ordering locally reproduced CI's exact keys and offsets 3/3; with the fix it passes 3/3. Nothing in this branch touches that plugin or its test. I didn't pin down which of the branch's changes moved the event ordering on macOS; the race was in the test either way.

Merge order

Merge this before paranext-core#2653, and move platform-yalc past it before #2653 merges. #2653 now stands its Enter handling down whenever this menu is open and relies on the menu claiming the press, and it relies on this PR's \id-line createBook fix, in-menu scroll exemption, modal key claim and mousemove highlight. #2653 now carries a merge-order contract test that mounts the staged editor, so its npm test goes red against a platform-yalc without this PR.

Not fixed: Backspace before a paragraph's marker

Pre-existing and not \id-specific, found while testing the merge above. With the caret before a paragraph's marker glyph, Backspace joins the whole paragraph — glyph included — onto the end of the previous line. The glyph stays visible, but the save drops the marker: \ip more\p s on screen was saved as \ip mores. Normal paragraphs behave the same way.

Not fixed here

A host that claims Enter from a window capture-phase listener still starves this menu's document capture-phase listener, whatever order the two registered in, because capture descends window → document. That is a host-side decision (the host has to stand down while the menu is open) and is fixed in paranext-core rather than here; there is no library-side fix, since nothing this plugin does from document can run before a window listener.

The plugin's built-in Cut / Copy / Paste / Paste as Plain Text items — and the new menu aria-label — are still hardcoded English, and the host can only append items. Pre-existing, and worth its own change.

Repo move

Moved here from eten-tech-foundation/scripture-editors#555, which is closed with a pointer to this PR: paranext-core main now consumes paranext/scripture-editors, so a PR merged on the eten repo would never reach the host. Rebased --onto origin/main from the old base (the two mains have diverged — paranext carries its own PT-4304 commit), every commit patch-identical to the original. One commit is added on top: paranext commits packages/*/dist, which eten does not, so the inherited build output predates this branch.

Testing

  • Review round 5 (2026-10-01): vitest run — shared 704, shared-react 1743 (1 skipped), platform 2191 (3 skipped), all passing. nx run-many -t typecheck lint clean on shared, shared-react and platform-editor (pre-existing warnings only). pnpm rebuild-committed-output, then verify-committed-dist.mjs reports current; the committed index.d.ts is the full rollup. Verified through paranext-core's isolated Playwright suite with 00e7d142 staged: full scripture-editor subset 16 of 16 passed first try.
  • Home fix + rebase (2026-09-30): vitest run — shared-react 33 files / 1738 (1 skipped), platform 111 files / 2189 (3 skipped), shared 41 files / 704, all passing. nx run-many -t typecheck lint clean across all 10 projects (pre-existing warnings only). pnpm rebuild-committed-output, then verify-committed-dist.mjs reports current. In the real app, paranext-core's new id-line-home-key e2e reproduced the bug (after Home the DOM caret sat at (p.book, 0) and typing landed in front of \id JON) and passes with this branch staged; full scripture-editor subset 16/16 first try, before and again after the rebase (93847a88 staged).
  • Review round 4 (2026-09-25): vitest run across the workspace: 192 files, 4551 passed, 4 skipped. nx run-many -t typecheck clean on all 10 projects (after a build), nx lint 0 errors (pre-existing warnings only). pnpm rebuild-committed-output, then verify-committed-dist.mjs reports current. Verified through paranext-core's isolated Playwright suite with this branch staged: full scripture-editor subset 15 of 15 passed first try.
  • Review round 3 (2026-09-24): vitest run — platform 109 files / 2054 (3 skipped), shared-react 33 files / 1717 (1 skipped), all passing. nx lint clean on shared-react and platform-editor (pre-existing warnings only); nx typecheck + nx lint clean on platform-editor and shared-react in a fresh worktree (pnpm install --frozen-lockfile), re-run with the same counts after the test-fixture refactor. pnpm rebuild-committed-output, then verify-committed-dist.mjs reports current; the committed index.d.ts is the 1853-line rollup. Verified through paranext-core's isolated Playwright suite with this branch staged: full scripture-editor subset 14 of 15 passed first try; the endnote spec passed on its own once its new step's setup was fixed on the core side.
  • Review-round fixes (2026-09-23): vitest run — platform 96 files / 1782, shared-react 31 files / 1696 (1 skipped), shared 41 files / 678, all passing. nx typecheck and nx lint clean on shared, shared-react and platform-editor (pre-existing warnings only). pnpm rebuild-committed-output, then verify-committed-dist.mjs reports current. Verified through paranext-core's isolated Playwright suite with this branch staged (npm run build:editor): full scripture-editor subset 9/9 first try on the final build (c8de1578); on two intermediate builds attribute-display-settle passed on retry after hitting the known pre-existing OutPortal cold-start crash.
  • Code-review fixes (2026-09-18): vitest run across the workspace — 177 files / 4150 passing, 1 skipped. nx run-many -t typecheck lint clean on platform-editor, platform, shared-react and scribe-editor (pre-existing no-console warnings only). pnpm rebuild-committed-output, then verify-committed-dist.mjs reports current after commit; the committed index.d.ts is the 1846-line rollup. paranext-core's isolated E2E was not re-run against this push.
  • This push (2026-09-18), rebased onto main: vitest run across the workspace — 177 files / 4136 passing, 1 skipped. nx run-many -t typecheck lint --skip-nx-cache clean across all 10 projects (warnings only). pnpm rebuild-committed-output, then verify-committed-dist.mjs reports Committed build output is current. ✓; the dist index.d.ts is the 1846-line rollup, not the tsc stub. Verified in the real app through paranext-core's isolated Playwright suite with this commit staged in: the full scripture-editor subset ran 9/9 with no retries, including #2653's new step (right-click, nothing highlighted, Enter then \: no palette, the menu stays up, and the paragraph neither splits nor gains a character).
  • vitest run across the workspace: 176 files / 4096 passing, 1 skipped — re-run on the new base after the move.
  • nx run-many -t typecheck and -t lint clean across the workspace; pnpm rebuild-committed-output then node scripts/verify-committed-dist.mjs reports Committed build output is current. ✓.
  • tsc --noEmit on packages/platform and libs/shared-react; eslint and prettier --check clean on every changed file.
  • The scroll test was verified red-then-green against the scroll fix; the ARIA tests red-then-green against the ARIA change; the \id-line corpus fixture red-then-green against createBook (6 failures before, all passing after).
  • Verified in the real app through paranext-core's isolated Playwright suite (this branch yalc-linked in): inserting an endnote into the \id line and re-reading the chapter rendered 0 notes before and 1 after, with the line's own text intact on both sides of the caller. Full scripture-editor subset 8/8, no retries.
  • \id-line editing (latest push): vitest run on packages/platform — 96 files / 1721 passing, including new tests that failed before each fix (bookLineSettle.test.tsx, two settleDifferential rows for the read-only mirror, and the \id-line merge in paraWholeDeletion.test.tsx). nx typecheck and nx lint clean on platform-editor (one pre-existing no-loop-func warning in verse-block.utils.ts); pnpm rebuild-committed-output then verify-committed-dist.mjs reports current.
  • PT-4613 pinning pass (latest push): vitest run on packages/platform — 96 files / 1728 passing. The new \id-line block in markerMenuApply.utils.test.tsx commits every entry the line offers and asserts the document changed, with a pin per offered kind (a real char span in the book; a real note whose key comes back for the host's session). Its falsifiable member is the one comparing the offered list against a live caret's context — checked red by restoring just markerMenuContext.utils.ts and markerMenuApply.utils.ts to their pre-fix revisions; the per-marker commits pass either way, since the old apply path already handled char and note picks. The stale item-source case for the book region, which asserted the earlier "no paraMarker, same list either way" model, was rewritten onto paraMarker: "id". nx lint and nx typecheck clean on platform-editor (same pre-existing no-loop-func warning); verify-committed-dist.mjs reports current — tests and docs only, so no dist rebuild.
  • Verified in the real app through paranext-core with this branch built in: \ip typed at the end of the \id line created the paragraph at once and the next characters went into it; the Enter palette picked \imt and started it after the line; three Backspaces on the marker of the paragraph below merged it into the line with the caret at the junction; and undo reverted the typed \ip and its split together.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TXbNhzh48xgmAWmwxqhMXi


This change is Reviewable

@tjcouch-sil
tjcouch-sil force-pushed the standard-view-pt-4195 branch 2 times, most recently from 849fa4a to 1a64c51 Compare September 15, 2026 22:44
@tjcouch-sil tjcouch-sil changed the title Fix the editor context menu's clipping, scrolling and accessibility — and the \id line's dropped content Fix the editor context menu and \id-line editing Sep 17, 2026

@lyonsil lyonsil 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.

This review covers 18 findings from an automated pass over the diff. Each comment's header states its severity and status as the reviewer settled on it: checked and confirmed means the finding was verified directly against the code, while needs a human call means it could not be settled either way and is left for you to judge. Two findings couldn't attach to a specific line and are included below instead of as inline comments.

Findings that could not be attached to a line in this diff

#1 (high · checked and confirmed) libs/shared-react/src/plugins/usj/ArrowNavigationPlugin.tsx:986 - Pressing ArrowLeft at the start of the paragraph immediately after a \id line that ends in a collapsed footnote does not stop the caret in front of that footnote as it does between two ordinary paragraphs; instead, because no branch in $handleBackwardNavigation claims the press when the previous block is a BookNode, the press falls through to Lexical's own default arrow-key handling, which walks the caret into the collapsed note's hidden interior text rather than stopping outside it.

What happens: ArrowNavigationPlugin.tsx:986's if ($isSomeParaNode(prevNode) && viewOptions?.noteMode === "collapsed") branch is what stops the caret before a trailing collapsed note; it fires when $getPreviousNode (libs/shared/src/nodes/usj/node.utils.ts:275) falls back to the previous block entirely. For a \id line ending in a note, prevNode resolves to the BookNode, which $isSomeParaNode returns false for, so every branch in $handleBackwardNavigation returns false and the press falls through to Lexical's own default KEY_ARROW_LEFT_COMMAND handling, which has no concept of "collapsed" and walks the caret into the note's hidden inner text. This PR fixed the identical check for the same reason in NoteNodePlugin.tsx:363 ($isSomeParaNode → $isParaLikeNode) but missed the sibling check here.

Why it matters: This PR is what first makes a note inside the \id line constructible at all, so this is newly reachable, not pre-existing — and the result is worse than a dead key: the caret lands inside hidden, collapsed content rather than simply not moving.

Fix: Change line 986's gate to $isParaLikeNode(prevNode) (import from "shared", already imported in this file's sibling NoteNodePlugin.tsx:34). Add an ArrowNavigationPlugin.test.tsx case: \id line ending in a collapsed note, followed by a paragraph, noteMode: "collapsed", ArrowLeft from the paragraph's start — assert the caret lands at the element point before the note, matching the ordinary-two-paragraphs control case.

How this was checked: Verified via live vitest probe in libs/shared-react: with a BookNode ending in a collapsed note followed by an ordinary paragraph, ArrowLeft from the paragraph's start lands the caret 10 characters into the note's hidden text (inside the ft CharNode) rather than stopping before it, matching the two-ordinary-paragraphs control case only after applying the $isParaLikeNode fix. Applied the one-line fix and reran the full ArrowNavigationPlugin.test.tsx suite (109 tests, including this PR's own new book-line tests): all pass, no regressions. Line 986 itself is untouched by this PR's diff (the PR's changes to this function are at lines 955-972), so this is an existing check that a new capability (notes in the \id line) newly exposes.

Not attached to a line: no longer on a changed line; cannot be posted inline

#14 (low · checked and confirmed) packages/platform/src/editor/markerEdit/virtualSettle.utils.ts:1168 - A code comment undercounts how many settle passes precede it, and its list of what chapters don't nest inside is incomplete.

What happens: virtualSettle.utils.ts:1168, just above the chapter pass in $settledUsj, still says "Chapters are top-level and disjoint from both passes above — a chapter is never inside a paragraph or a note" — written when only the notes pass (line 1115) and paragraphs pass (line 1136) preceded it. This PR inserts a third pass, the new book-line pass (line 1153), immediately before this comment without updating either the count or the list of block types named.

Why it matters: Purely cosmetic — the underlying claim (a chapter is never inside a paragraph, note, or book) still holds — but misleads a reader checking the ordering-safety argument, and the omission of "book" from the list is itself now incomplete given the new pass it sits beside.

Fix: Reword to: "Chapters are top-level and disjoint from all three passes above — a chapter is never inside a paragraph, note, or book — so ordering against them is free."​

How this was checked: Confirmed via the worktree: the PR adds a book-pass loop (lines 1153-1166) immediately before this comment. Three passes now precede the chapter pass (notes at 1115, paragraphs at 1136, books at 1153), but the comment was not updated when the book pass was inserted.

Not attached to a line: no longer on a changed line; cannot be posted inline

(AI-assisted, with my guidance)

Comment thread demos/perf-react/src/index.css Resolved

@lyonsil lyonsil 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.

This review covers 31 further findings from a second automated pass over this PR, mostly around editing in the \id line and the context menu's keyboard handling; findings already raised in the earlier review are not repeated. Each comment's header gives the severity the reviewer settled on and a status: checked and confirmed means the finding was verified directly against the code, and needs a human call means it could not be settled either way and is left for you to judge. Findings that sit on lines this PR did not change cannot attach inline and are listed below instead.

Findings that could not be attached to a line in this diff

#3 (high · checked and confirmed) libs/shared-react/src/plugins/usj/structureKeyboard.utils.ts:317 - In guarded mode, the confirming Backspace below the \id line does nothing after the first press arms it, and a third press empties the paragraph's text while leaving an empty paragraph behind.

What happens: Backspace at the start of the paragraph below the line arms the delete. The confirming press calls $mergeParaIntoPrevious, which returns at structureKeyboard.utils.ts:319 because the previous sibling is a BookNode, not a SomeParaNode.

Why it matters: The PR's invariant says a paragraph below the \id line merges into it (docs/standard-view-invariants.md:190-191), and the marker-edit path already does (markerEditDeletion.utils.ts:400); this guarded-mode path accepts the keystroke and does nothing.

Fix: At structureKeyboard.utils.ts:318, change if (!$isSomeParaNode(prev)) return; to also accept a BookNode previous sibling (import $isBookNode from "shared" alongside the existing $isSomeParaNode import), and append para's children into it the same way the paragraph-into-paragraph branch already does. Filter out any $isMarkerTrailingSeparator child (also importable from "shared") before appending, mirroring markerEditDeletion.utils.ts:400-403 - that code only drops the orphaned trailing separator there, not a marker prefix, since none remains in the paragraph's children by the point it runs, so no separate prefix-stripping is needed here either. Update $mergeParaIntoPrevious's TSDoc to say it also merges into a BookNode, and add the calling-context line CLAUDE.md requires for exported $-prefixed functions ("Mutating: call inside editor.update()", dispatched from StructureKeyboardPlugin.tsx:119). Add a guarded-mode test in StructureKeyboardPlugin.test.tsx next to the existing "paragraph Backspace at start" test, building the initial tree by chaining .append(...) calls inside $getRoot().append(...) per this repo's test-authoring convention.

How this was checked: Reproduced with a guarded-mode probe test: a BookNode("GEN") followed by a ParaNode as root children, caret at the paragraph's start. The first Backspace arms a range selection over the paragraph's content without changing the tree (structureKeyboard.utils.ts:247-259). The confirming press calls $mergeParaIntoPrevious (StructureKeyboardPlugin.tsx:119), which returns immediately at structureKeyboard.utils.ts:318-319 because para.getPreviousSibling() is the BookNode, not a SomeParaNode - paragraph and book text both unchanged, armed state cleared. A third Backspace no longer matches the two-step gate (armedRef is already undefined) and falls through to Lexical's native handling of the still-live range selection from the first press, which erases the paragraph's content while leaving the empty ParaNode in place - so the two-step confirmation is not merely inert, it lets a third, un-gated keystroke silently discard the user's text. Every book start (\id line followed by a paragraph) is affected, and the natural response to an apparently-ignored confirm keystroke - pressing it again - is exactly what triggers the unconfirmed deletion. The BookNode-merge invariant this violates (docs/standard-view-invariants.md:190-191) and its sibling implementation (markerEditDeletion.utils.ts:397-400) were both added by this PR; structureKeyboard.utils.ts itself is untouched (git diff against the merge base is empty for that file).

Not attached to a line: not on a changed line; cannot be posted inline

#4 (high · checked and confirmed) packages/platform/src/editor/Editor.tsx:676 - A toolbar paragraph-style pick with the caret in the \id line turns the book into a paragraph, so the saved USJ loses the \id line and book code while the \id GEN glyph stays on screen.

What happens: StateChangePlugin.tsx:87 reports blockMarker id for the line, so the host's paragraph-style control calls EditorRef.formatPara(marker). $setBlocksType(selection, () => $createParaNode(blockMarker)) (Editor.tsx:691) replaces every selected block, the BookNode included, and $applyParaMarker (:703) adds the marker prefix. Result: tree [\p \id GEN Genesis], USJ [{para p, ["Genesis"]}].

Why it matters: One toolbar pick deletes the book object from the file. The path predates this PR, but the PR's new rule that a book is never retagged (docs/standard-view-invariants.md:181-184) moved only the \ and Enter menus onto $splitBookWithMarker (markerMenuApply.utils.ts:452-458).

Fix: In formatPara (Editor.tsx:676), before calling $setBlocksType at :691, check whether the selection's focus node has a BookNode ancestor ($findMatchingParent(focusNode, $isBookNode), importing $isBookNode from "shared" and $findMatchingParent from "@lexical/utils"). If it does, call the already-imported $splitParagraphWithMarker(blockMarker, viewOptions) (Editor.tsx:24) instead of $setBlocksType and return - it already detects the missing ParaNode ancestor and delegates to the private $splitBookWithMarker (markerMenuApply.utils.ts:449-458), giving the book case the same split-after-book behavior the \ and Enter menus use, with no new export required. Otherwise fall through to the existing $setBlocksType path unchanged. $splitBookWithMarker's own $canSplitBookAt guard silently no-ops for a caret position it cannot split, so route that case through the same logged-warning refusal used at Editor.tsx:684-689 rather than leaving it silent. Add a test with the caret in the \id line asserting the BookNode survives and the tail becomes a new paragraph after it, per the "a menu offers nothing it cannot insert" rule in docs/standard-view-invariants.md.

How this was checked: Reproduced with a live probe (Editor mounted with a \id GEN "Test Book", caret parked in the book text, ref.current.formatPara("p") called): the committed state has no BookNode left ($isBookNode finds none among root children) and getUsj() returns a "para" entry with content ["Test Book"] in place of the "book" entry - the GEN code is gone - while the paragraph's text content is literally \p \id GEN Test Book, so the stale \id GEN glyph is left on screen inside the new paragraph, exactly as claimed. $setBlocksType (Editor.tsx:691) treats BookNode as a convertible block because INTERNAL_$isBlock (@lexical/selection LexicalSelection.dev.js:616-623) accepts any non-inline ElementNode with canBeEmpty() !== false and a leaf/inline first child, and BookNode (libs/shared/src/nodes/usj/BookNode.ts) never overrides isInline/canBeEmpty. StateChangePlugin.tsx:87,89 reports blockMarker: "id" for a caret resolved to a BookNode. On paranext-core's current main, ParagraphStyleTrigger only withholds rendering when blockMarker is falsy (paragraph-style-trigger.component.tsx: if (!blockMarker) return undefined;) and generateParagraphMenuListItems (platform-scripture-editor.utils.ts:567-591) offers every entry of blockMarkerToBlockNames unconditionally, calling editorRef.current.formatPara(marker) on pick with no book-specific gate - so the path is live end-to-end, not merely theoretical. git diff <merge-base> HEAD -- packages/platform/src/editor/Editor.tsx is empty, confirming formatPara predates this PR.

Not attached to a line: not on a changed line; cannot be posted inline

#5 (high · checked and confirmed) packages/platform/src/editor/markerEdit/markerEditTier1.utils.ts:216 - Pausing mid-marker in the \id line (typing \n, then d a second later), or mistyping a marker there, splits off a paragraph that correcting the marker never rejoins, adding an untyped \p paragraph to the file.

What happens: The idle settle (IDLE_SETTLE_DELAY_MS = 1000) runs $rebuildBook; tokenizedBookLine (tier2Rebuild.utils.ts:1932-1947) ends the line at the unknown, paragraph-typed \n and inserts it after the book (:2038). The next keystroke calls $tryUnknownSplitRejoin, but $unknownSplitRejoinScope returns undefined unless the previous sibling is a ParaNode (markerEditTier1.utils.ts:228), so $rebuildParas([para]) wraps the bytes in a synthesized \p: \id GEN Genesis then \p \xnd , caret inside the glyph. The read-only settle uses the same gate (virtualSettle.utils.ts:1063-1066).

Why it matters: An ordinary typing rhythm, or a typo like \ndd, corrupts the line and the saved file; the same keys in a paragraph rejoin correctly.

Fix: Any fix must widen the rejoin gate to a BookNode predecessor, not just a ParaNode one. Concretely: (1) change what $unknownSplitRejoinScope (markerEditTier1.utils.ts:216) returns, or add a sibling check, so a BookNode previous sibling (parent.getPreviousSibling() at :227) also counts as a rejoin target; (2) extend $rebuildBook (tier2Rebuild.utils.ts:1962), which today only re-tokenizes book.getChildren() (:1896), to also accept and fold in the stray paragraph's content bytes, mirroring how $rebuildParas already re-tokenizes multiple ParaNode siblings as one fragment; (3) route both $tryUnknownSplitRejoin (markerEditTier1.utils.ts:243-246) and the read-only settle's identical check (virtualSettle.utils.ts:1057-1066) through this widened result, preserving the "both legs decide identically" contract the existing TSDoc states; (4) update $unknownSplitRejoinScope's TSDoc to describe the new case. Add tests for "idle split, then keep typing" and "typo, then fix" against a BookNode predecessor specifically, alongside the existing ParaNode-predecessor cases in unknownSplitRejoin.test.tsx.

How this was checked: I built a minimal Lexical tree with a BookNode followed directly by an unknown-marker paragraph (the shape $rebuildBook produces: tier2Rebuild.utils.ts:2038 inserts a split-off paragraph directly after the book) plus a parking paragraph, then corrected the unknown paragraph's glyph to the known inline marker \w and let the pend settle. $unknownSplitRejoinScope requires parent.getPreviousSibling() to be a ParaNode (markerEditTier1.utils.ts:227-228); with a BookNode predecessor it returns undefined, so $tryUnknownSplitRejoin fails (:243-246) and $applyOpenerRename falls through to $requestTier2ForNode (:421), which re-tokenizes the lone paragraph and fabricates a \p wrapper. The resulting getUsj() output contained a standalone {type: "para", marker: "p", content: [{type: "char", marker: "w", ...}]} node that was never authored - confirming the fabrication. virtualSettle.utils.ts:1057-1066 calls the identical $unknownSplitRejoinScope gate, so getUsj() reports the same fabricated paragraph without a full commit. $rebuildBook (tier2Rebuild.utils.ts:1962-2046, added by this PR) is what first makes a BookNode-adjacent split reachable at all.

Not attached to a line: not on a changed line; cannot be posted inline

#8 (medium · checked and confirmed) libs/shared-react/src/plugins/usj/ArrowNavigationPlugin.tsx:894 - In views that hide markers, ArrowRight at the end of \id line text before a collapsed note enters the note's hidden content instead of stepping past it as it does in a paragraph.

What happens: $handleForwardNavigation's paragraph-end check (ArrowNavigationPlugin.tsx:894) and its caret-between-verse-and-collapsed-note hop (:916) both gate on $isSomeParaNode(node), which is false for a BookNode, so a caret on the book element (including the (book, i) position the PR's new backward note hop creates at :977-978) falls through to default handling.

Why it matters: The plugin's own comment (:873-876) says a caret inside a collapsed note is invisible and edits the wrong bytes; notes in the \id line only load since this PR.

Fix: In ArrowNavigationPlugin.tsx, replace $isSomeParaNode(node) with $isParaLikeNode(node) at :894 and :916, and $isSomeParaNode(prevNode) with $isParaLikeNode(prevNode) at :986, importing $isParaLikeNode from "shared" (it is already imported the same way, for the same reason, in NoteNodePlugin.tsx:363). Add a forward-navigation test with a collapsed note in the \id line, built with the existing $buildBookLine/$collapsedNote helpers in the "Backward navigation in the book line" describe block. After the source change, regenerate the committed packages/platform/dist via pnpm nx extract-api @eten-tech-foundation/platform-editor (after build) and commit it in a follow-up commit, matching the dist rebuild this PR already did for its other ArrowNavigationPlugin.tsx book-line fixes.

How this was checked: Traced $handleForwardNavigation (ArrowNavigationPlugin.tsx:889-940): when the anchor is an element-type point directly on the BookNode (e.g. (book, 1), exactly the shape parent.select(noteIndex, noteIndex) produces at :977-978), node is the BookNode itself, so $isSomeParaNode(node) at :894 is false and the else branch's text-offset comparison (:898-900) can never match an element offset, forcing an early return false. I built that exact tree (BookNode -> immutable id text, collapsed note with a non-marker first child, trailing text) in libs/shared-react/src/plugins/usj/ArrowNavigationPlugin.test.tsx, set selection to (book, 1) and pressed ArrowRight: event.defaultPrevented stayed false and the selection did not move, confirming the plugin declines and Lexical's default takes over, exactly as "leaves the default move to run" is asserted for the analogous character-span case a few tests above it. $isBookNode(bookNode) is never true at :960 in this codepath since node is the BookNode, not its child, so the unrelated \id-line-start guard doesn't intercept either. git diff ccb9e396..HEAD -- ArrowNavigationPlugin.tsx shows this PR touched only $handleBackwardNavigation; $handleForwardNavigation (:889-940, including :894 and :916) is untouched.

Not attached to a line: not on a changed line; cannot be posted inline

#9 (medium · checked and confirmed) libs/shared-react/src/plugins/usj/structureKeyboard.utils.ts:57 - In structure-protected mode, Delete at the end of the \id line (or deleting a selection from the line into the next paragraph) merges the next paragraph into the \id line instead of being blocked.

What happens: $getParaAncestor only recognizes paragraph nodes (structureKeyboard.utils.ts:57-62), so $caretAtParaEnd, $selectionSpansBlockBoundary and $hasNeighborBlock (:65-73, :185-190) never treat the book as a block, and the protected branch at StructureKeyboardPlugin.tsx:80-86 returns without preventDefault(), so the native merge runs. Result: book ["GenesisTitle"], the \h paragraph gone, and in Standard view a stray \h glyph left in the line.

Why it matters: Protected mode exists to refuse exactly this merge. The path predates this PR, but the PR makes the \id line a content block (docs/standard-view-invariants.md:172-174).

Fix: Use $isParaLikeNode in $getParaAncestor, landing it together with the $mergeParaIntoPrevious change in #3 so guarded mode does not regress. Add protected-mode tests for Delete at the line end and a selection spanning into the next paragraph.

How this was checked: Reproduced both scenarios with real jsdom keydown/command dispatch against this PR's head (structureKeyboard.utils.ts and StructureKeyboardPlugin.tsx are unchanged by this PR, per git diff <merge-base> <head> --stat showing no hits for either file). With a BookNode("GEN") holding "GenesisTitle" followed by a ParaNode("h") holding "Genesis", in structureProtectionMode="protected": pressing Delete with the caret at the end of the book's text merges the paragraph into the book (root ends up with one "book" child, text "GenesisTitleGenesis", \h paragraph gone); a selection from inside the book's text to inside the paragraph's text, fed through CONTROLLED_TEXT_INSERTION_COMMAND, likewise collapses to a single "book" child. Root cause matches the finding: $getParaAncestor (structureKeyboard.utils.ts:57-62) only matches $isSomeParaNode, so a node inside a BookNode has no "para" ancestor, making $caretAtParaEnd/$hasNeighborBlock (used by $shouldBlockStructuralEdit's deleteForward branch) and $selectionSpansBlockBoundary all return false for this boundary, so StructureKeyboardPlugin.tsx's protected branch (:80-86) takes the return false path and never calls event.preventDefault(), leaving Lexical's own native delete-forward/replace-selection handling (outside this file) to run the merge.

Not attached to a line: not on a changed line; cannot be posted inline

#20 (low · checked and confirmed) libs/shared/src/nodes/features/ImmutableTypedTextNode.ts:198 - Backspace at the start of the \id line's content deletes the immutable \id GEN glyph from the screen, while the file keeps \id GEN.

What happens: The prefix is a DecoratorNode whose isKeyboardSelectable() returns false (ImmutableTypedTextNode.ts:198-200), so Lexical's backward deleteCharacter from (text, 0) removes it outright, and nothing restores a book's prefix (the marker-deletion transform covers only paragraphs, markerEditDeletion.utils.ts:332-345). The screen shows book ["Genesis"] while the USJ is unchanged.

Why it matters: The PR's invariant calls the prefix "ONE immutable decorator … that the caret cannot enter" (docs/standard-view-invariants.md:176-178); a common keystroke removes it until reload and changes nothing in the document. The path predates this PR.

Fix: Refuse a Backspace or Delete whose target is the book's prefix glyph (for example a DELETE_CHARACTER_COMMAND handler in MarkerEditPlugin at the line start), so the keystroke is visibly refused rather than silently eaten. Add a test.

How this was checked: Built the \id GEN line exactly as editor-usj.adaptor.ts renders it (BookNode -> ImmutableTypedTextNode("\id GEN ") -> content TextNode, matching bookLineSettle.test.tsx's own $buildBookLine), placed a collapsed caret at offset 0 of the content text, and dispatched a real KEY_DOWN_COMMAND "Backspace" through the full RichTextPlugin pipeline (Editor.tsx:1059) in a vitest probe under packages/platform; the ImmutableTypedTextNode decorator is gone from the tree afterward (book.getFirstChild() becomes the content text node). Lexical's RangeSelection.deleteCharacter removes an adjacent DecoratorNode outright at this boundary regardless of isKeyboardSelectable() (node_modules/lexical/Lexical.dev.js:7005-7020), so ImmutableTypedTextNode.ts:198-200 does not protect it. deserializeSerializedEditorState returns the byte-identical {"type":"book","marker":"id","code":"GEN","content":["Genesis"]} before and after the keystroke, confirming the USJ is untouched (the code/marker live on BookNode's own state, not the decorator; usj-editor.adaptor.ts:292-323). No BookNode node transform is registered anywhere (MarkerEditPlugin.tsx:650-777 covers MarkerNode, VerseNode, ChapterNode, ParaNode, CharNode, MilestoneNode, AttributeRunNode, NoteNode, ImmutableUnmatchedNode, TextNode only), and $paraMarkerDeletionTransform is typed para: ParaNode (markerEditDeletion.utils.ts:332), so nothing heals the loss. Neither ImmutableTypedTextNode.ts (zero diff in this PR) nor the transform's guard body (lines 331-393, untouched) were changed by this PR, matching the finding's "predates this PR" statement.

Not attached to a line: not on a changed line; cannot be posted inline

#21 (low · checked and confirmed) libs/shared/src/nodes/usj/BookNode.ts:37 - A multi-line paste into the \id line runs the pasted lines together into the line text, and EditorRef.insertMarker with a paragraph marker there does nothing.

What happens: BookNode inherits ElementNode's insertNewAfter, which returns null, so RangeSelection.insertParagraph() creates no block in the line. Paste: MarkerEditPlugin's multi-line handling declines outside paragraphs (charFormatting.utils.ts:206-211) and @lexical/clipboard's per-newline insertParagraph() drops every newline - pasting "one⏎two" at Gen|esis gives Genonetwoesis. insertMarker: getUsjMarkerAction's block branch (usj-marker-action.utils.ts:346-356) gets null the same way.

Why it matters: Text is silently fused, or a pick changes nothing, on paths the PR's new split does not cover. The behavior predates this PR; pasting inside a char span in the line is newly reachable.

Fix: Export $splitBookWithMarker from packages/platform/src/editor/markerMenu/markerMenuApply.utils.ts and call it from the block branch of getUsjMarkerAction (packages/platform/src/editor/adaptors/usj-marker-action.utils.ts:346-356) in place of selection.insertParagraph() when the selection's container is a BookNode, passing the already-in-scope marker - this fixes EditorRef.insertMarker directly, matching the split-and-reopen contract docs/standard-view-invariants.md:181-184 already ratifies. For the paste path, widen BOTH $isSelectionInParagraphCharStack (charFormatting.utils.ts:211) and $splitParagraphAtCharStack's own internal check (charFormatting.utils.ts:262-263) from $isSomeParaNode to $isParaLikeNode (exported from shared, libs/shared/src/nodes/usj/node.utils.ts:290-291) - changing only one leaves the other declining and the split still falls through to Lexical's glyph-less generic split. $splitParagraphAtCharStack's para.insertNewAfter(selection, false) call (charFormatting.utils.ts:277) assumes a ParaNode/ImpliedParaNode continuation-marker shape that does not exist for a book; that call site needs a BookNode-specific branch (mirroring $splitBookWithMarker's own split-and-lift, without a picked marker) rather than a bare insertNewAfter, since plain paste/Enter has no marker to retag with. Add a paste test and an insertMarker test with the caret inside a char span in the \id line, per the existing bookLineSettle.test.tsx / markerMenuApply.utils.test.tsx patterns.

How this was checked: Traced end to end against the installed lexical@0.43.0 and @lexical/clipboard@0.43.0 sources. BookNode (libs/shared/src/nodes/usj/BookNode.ts:37) has no insertNewAfter override, so it uses ElementNode's default, which returns null (Lexical.dev.js:9654-9656). $insertDataTransferForRichText (LexicalClipboard.dev.js:130-153, registered by RichTextPlugin at COMMAND_PRIORITY_EDITOR) splits pasted text on \n and calls insertParagraph() per break; RangeSelection.insertParagraph() (Lexical.dev.js:6734-6754) splits the text node first via $removeTextAndSplitBlock but, when block.insertNewAfter() is null, creates no new block and leaves the caret at the split point - so the next line's insertText lands right after the previous one, reproducing "Genonetwoesis" for "Gen|esis" + "one\ntwo". MarkerEditPlugin's own char-stack-aware paste handler (charFormatting.utils.ts:206-211, $isSelectionInParagraphCharStack) only claims this when $charStackContainer is a ParaNode/ImpliedParaNode ($isSomeParaNode), so it declines for BookNode and falls through to the generic path above - confirmed by reading $isSomeParaNode's definition (node.utils.ts:299-300), which excludes BookNode. EditorRef.insertMarker (Editor.tsx:780-800) calls getUsjMarkerAction(...).action(...), whose generic block branch (usj-marker-action.utils.ts:346-356) calls selection.insertParagraph() directly for a non-inline ElementNode marker (e.g. "p") on a collapsed selection - same null return, same no-op - and isUsjMarkerSupported (usj-marker-action.utils.ts:179-188) is marker-name-only, with no caret-position gate, so a host can reach this. Commit b1fa79c confirms this was a known gap ("A paragraph pick had no paragraph to retag or split, so the Enter palette's Enter did nothing") but fixed it only for the marker-menu's Enter-triggered pick via a new, non-exported $splitBookWithMarker (markerMenuApply.utils.ts:174) - EditorRef.insertMarker was left on the old getUsjMarkerAction path and still hits the no-op. docs/standard-view-invariants.md:181-184 ratifies that a paragraph pick in the \id line "can only SPLIT: the tail after the caret becomes a new paragraph inserted directly after the book, with an open character span closed on the left and reopened in it" - confirming this is a real, intended behavior that both remaining call sites still fail to deliver.

Not attached to a line: not on a changed line; cannot be posted inline

#22 (low · checked and confirmed) packages/platform/src/editor/markerEdit/markerEditTier2Trigger.utils.test.tsx:1040 - A test comment still says book content is a literal-only degradation context, which now misdescribes the engine.

What happens: markerEditTier2Trigger.utils.test.tsx:1040-1042 says "Book/chapter/opaque-unknown content is a literal-only degradation context", but this PR makes the \id line a settle scope ($rebuildBook).

Fix: Reword the comment to drop "Book" from the list of literal-only contexts, naming only the contexts that still degrade.

How this was checked: This PR adds $rebuildBook (tier2Rebuild.utils.ts:1962), documented as "the fourth settle scope, beside $rebuildParas, $rebuildNoteContent and $rebuildChapter" (tier2Rebuild.utils.ts:1951-1961), and wires it into $settleScopeForNode's return type and $requestTier2ForNode's routing (tier2Rebuild.utils.ts:2358-2390; diff confirms $isBookNode(scope)) return $rebuildBook(scope, context) at :2390 is new versus the merge base). A new 350-line test file, bookLineSettle.test.tsx, exercises live \id-line marker/note settling. The comment at markerEditTier2Trigger.utils.test.tsx:1040-1042 is unchanged by this PR (git diff shows no touch to that text) and still reads "Book/chapter/opaque-unknown content is a literal-only degradation context," which is now false for Book content.

Not attached to a line: not on a changed line; cannot be posted inline

#27 (low · checked and confirmed) packages/platform/src/editor/markerEdit/virtualSettle.utils.ts:1185 - The husks-last rationale in $settledUsj names only the note and paragraph passes, so anyone reordering the passes gets no warning that the new book pass also needs husks to run last.

What happens: The rationale at virtualSettle.utils.ts:1185-1214 explains why husk cleanup runs last in terms of the note and paragraph passes' in-place splice and first-content anchor. The book pass this PR adds has the same splice and anchor but is not named.

Fix: Name the book pass in the husks-last rationale alongside the note and paragraph passes.

How this was checked: Confirmed. The husks-last rationale at virtualSettle.utils.ts:1185-1214 is unchanged by this PR (the diff shows no +/- lines inside it) and enumerates exactly two scope mechanisms as the reason husks must splice last: NOTE (1194-1199) and PARAGRAPH (1200-1207). The new book pass at virtualSettle.utils.ts:1153-1166 shares NOTE's mechanism exactly: bookChildren.splice(start, built.contentNodes.length, ...built.rebuilt) mutates bookChildren in place, anchored on sites.get(built.contentNodes[0].getKey()) — the same anchor-and-splice shape the NOTE bullet describes at 1115-1133. A husk that is the book line's own first content node would suffer the identical silent start < 0 skip described for notes if the passes were ever reordered to run husks before the book pass, and the rationale gives no warning of this third case.

Not attached to a line: not on a changed line; cannot be posted inline

#28 (low · checked and confirmed) packages/platform/src/editor/markerMenu/markerItemSource.ts:35 - The public MarkerMenuContext.paraMarker documentation says it is undefined at book level, but getMarkerMenuContext() now returns "id" for every caret in the \id line.

What happens: The doc string (markerItemSource.ts:35) predates the change at markerMenuContext.utils.ts:217 (para?.getMarker() ?? book?.getMarker()), and it ships in the committed typings (dist/index.d.ts:1159).

Why it matters: A host that uses paraMarker === undefined to detect book level would silently change behavior.

Fix: Reword it (e.g. "the enclosing block's marker: the paragraph's, or id in the \id line; undefined where the caret has no block owner") and run nx extract-api @eten-tech-foundation/platform-editor so the committed dist and API report are updated.

How this was checked: packages/platform/src/editor/markerMenu/markerItemSource.ts:35 documents MarkerMenuContext.paraMarker as "undefined at e.g. book level"; git diff ccb9e396..HEAD -- .../markerItemSource.ts is empty, so this comment predates the PR and was not touched by it. The PR's actual diff in markerMenuContext.utils.ts adds const book = para ? undefined : $findMatchingParent(focusNode, $isBookNode) and changes the return from paraMarker: para?.getMarker() to paraMarker: para?.getMarker() ?? book?.getMarker() (markerMenuContext.utils.ts:207, 216-217). BookNode.getMarker() (libs/shared/src/nodes/usj/BookNode.ts:69-72) always returns the literal BOOK_MARKER = "id", so any caret whose nearest para/book ancestor is the \id line's BookNode now yields paraMarker: "id", not undefined. The stale wording ships unchanged in the committed typings at packages/platform/dist/index.d.ts:1159, read directly and confirmed to still say "undefined at e.g. book level".

Not attached to a line: not on a changed line; cannot be posted inline

#30 (low · checked and confirmed) packages/platform/src/editor/markerMenu/markerMenuContext.utils.ts:66 - The Enter palette in the \id line lists every paragraph marker, including \p, \q1 and \s1, which the editor flags as invalid as soon as the pick inserts them after the line.

What happens: $collectPreviousParaMarkers stops at the caret's own top-level element (markerMenuContext.utils.ts:70), which for the \id line is the first root child, so the preceding-marker list is empty. getEnterMenuItems (markerItemSource.ts:305-326) validates against that empty stack, which accepts every marker (markerValidation.utils.ts:77): 122 items instead of 47. After $splitBookWithMarker inserts \p, $validateDocument (stack [id]) flags it.

Why it matters: These picks did nothing before this PR; now they commit invalid structure. Paratext 9's equivalent list includes the current block (id at the document start).

Fix: In $collectPreviousParaMarkers (markerMenuContext.utils.ts:66-76), when the loop's child.is(topLevel) break (line 70) fires because child is the BookNode itself, push child.getMarker() onto markers before breaking - only for that book case, not the general break. This mirrors $validateDocument's stack build (markerValidation.utils.ts:213-231), which always joins the book's tag into an empty stack before checking what follows it. Add a test in markerMenuContext.utils.test.tsx asserting previousParaMarkers is ["id"] for a collapsed caret inside a bare \id line's text, and/or a getEnterMenuItems assertion that its result excludes p for that same context. Because this changes packages/platform runtime behavior that the host consumes, also run nx extract-api @eten-tech-foundation/platform-editor afterward and commit the regenerated packages/platform/dist.

How this was checked: Confirmed with a direct probe: for a caret inside a bare \id 2SA book line, $collectPreviousParaMarkers (markerMenuContext.utils.ts:66-76) returns [] because it breaks at child.is(topLevel) (line 70) before ever recording the book's own marker. getEnterMenuItems (markerItemSource.ts:305-326) replays that empty list into isParagraphTagValid (markerValidation.utils.ts:95-100), whose placeParaTag (line 77) short-circuits stack.length === 0 to "valid anywhere" regardless of occursUnder. The probe against defaultStyleInfo returns exactly 122 Enter-menu items (including p, q1, s1) where the correct, id-inclusive stack returns 47 and excludes p - matching the finding's own numbers. $splitBookWithMarker (markerMenuApply.utils.ts:174, new in this PR - absent from the merge-base version of $splitParagraphWithMarker) inserts the picked marker as a new paragraph right after the \id line, and a follow-up $validateDocument run (markerValidation.utils.ts:208-251) flags that inserted \p glyph "invalid" because its real ancestor stack is [id], not [c]. The anchored lines (66-76) are pre-existing and untouched by this PR's diff to the file (hunks only at lines 7-9, 188-207, 201-210), but the PR is what makes the pre-existing enumeration bug newly consequential by adding the book-arm split path.

Not attached to a line: not on a changed line; cannot be posted inline

#31 (low · checked and confirmed) packages/platform/src/editor/settledGetUsj.test-helpers.tsx:215 - The shared settled-output acceptance helper expectTier2FixedPoint never drives a document's \id line through a Tier-2 rebuild, so a settled \id line that is not actually a re-tokenization fixed point would pass every settled-output test undetected.

What happens: expectTier2FixedPoint only re-runs $rebuildParas and $rebuildNoteContent (settledGetUsj.test-helpers.tsx:224-237), and no pending shape in settledGetUsj.test.tsx edits the \id line.

Why it matters: The PR added a fourth settle scope without extending the standing acceptance that $rebuildParas's doc points to (tier2Rebuild.utils.ts:1490-1493).

Fix: Run $rebuildBook on every root BookNode (counting it in rebuildScopes), and add pending shapes for the \id line, including one with a note.

How this was checked: expectTier2FixedPoint (settledGetUsj.test-helpers.tsx:215-246) filters $getRoot().getChildren() for ParaNode and drives $rebuildParas, then collects NoteNode descendants for $rebuildNoteContent, but has no branch for BookNode, so a document's \id line is never driven through $rebuildBook (tier2Rebuild.utils.ts:1962), the fourth settle scope this PR adds. Every entry in pendingShapes (settledGetUsj.test.tsx:385-793, 24 shapes) leaves the \id line at its fixture value (twoParaUsj always sets content: ["GEN"], settledGetUsj.test.tsx:271-279), so no shape in "settled getUsj — output is always a Tier-2 fixed point" ever exercises book scope either. I extended expectTier2FixedPoint locally with a $getRoot().getChildren().filter($isBookNode) loop calling $rebuildBook and counting rebuildScopes, then added a pendingShapes entry typing a marker literal into the \id line: the suite (52 cases) passed cleanly with the extension in place, confirming this is a real, closeable gap rather than something already covered elsewhere.

Not attached to a line: not on a changed line; cannot be posted inline

(AI-assisted, with my guidance)

@tjcouch-sil

Copy link
Copy Markdown
Member Author

Replies to the first automated review's findings that have no inline anchor:

#1 Fixed in f01dd51. The collapsed-note hop in $handleBackwardNavigation now gates on $isParaLikeNode, matching NoteNodePlugin. A new ArrowNavigationPlugin.test.tsx case, plus a para→para control, failed before the fix with the caret at offset 10 inside the note's text. Scoping note: with Standard view's real editable prefix, a caret at a paragraph's content start has the prefix separator as its previous node. So this branch is reached from an element point at the block's start rather than from the first content character. The fix is right either way, but the everyday Standard-view path is narrower than the description suggests.

#14 Fixed in 8a9b0a3.

🤖 Generated with Claude Code

@tjcouch-sil

Copy link
Copy Markdown
Member Author

Replies to the second automated review's findings that have no inline anchor:

#3, #9 Fixed in 958c98e. The structure keyboard guards treat the \id line as a block. In guarded mode, the confirming Backspace merges the paragraph below into the line, so the unguarded third press no longer erases its text. In protected mode, Delete at the line's end and a selection spanning into the next paragraph are blocked.

#4 Fixed in 29d7a54. formatPara with the caret in the \id line routes to the same split-after-book path as the \ and Enter menus, instead of $setBlocksType retagging the book. A refused split is logged the way formatPara's other refusals are.

#5 Fixed in bbdc2c3. $unknownSplitRejoinScope accepts a BookNode predecessor. The split-off paragraph is then passed to $rebuildBook as trailing content: its bytes join the line's, and tokenizedBookLine's existing line/following-blocks split produces the rejoined line. The read-only $settledBookLine mirrors it step for step. Both legs now use one shared paragraph joiner ($appendParaFragments), which $rebuildParas and $settledParaNodes also switched to. Tests mount the real editor with fake timers: "idle split, then keep typing" (\n, pause, d), "typo, then fix" (\ndd → \nd), and an empty \id line. Each also asserts that the pending getUsj() equals the settled result, and each failed before the fix with a fabricated \p (['id','p','c','p']).

#8 Fixed in bd06e20. The forward-navigation checks use $isParaLikeNode, so ArrowRight steps over a collapsed note in the \id line.

#20 Fixed in a6a8a71. Backspace or Delete whose target is the book's prefix glyph is refused. The prefix is identified by identity, so a paragraph's own marker prefix keeps its intentional marker-deletion behavior.

#21 Not changing in this PR. The insertMarker half is the non-Standard-view \ path in the \id line, already scoped as separate work. Multi-line paste into the line fusing its lines is pre-existing and rare, and it loses no text.

#22, #27, #28 Fixed in 9aac1dc.

#30 Fixed in 799043e. The book's own marker goes onto the Enter palette's stack, so the \id line offers only markers valid after \id.

#31 Fixed in 79dd034. expectTier2FixedPoint drives every root BookNode through $rebuildBook, and there are two new pending shapes in the line, one with a note.

🤖 Generated with Claude Code

@lyonsil

lyonsil commented Sep 24, 2026

Copy link
Copy Markdown
Member

Follow-ups on three of the second review's findings that have no inline thread:

#4 (formatPara in the \id line). A collapsed caret or a backward selection now splits correctly, but a forward selection still retags the book. formatPara routes on selection.focus only (Editor.tsx:719), so a drag from the \id line down into the next paragraph (the normal direction) leaves the focus in the paragraph and falls through to $setBlocksType. On the mounted <Editor>, getUsj() then starts with {"type":"para","marker":"p","content":["Test Book"]}: the book and GEN are gone, which is the original bug. The same span dragged backward keeps the book.

Fix: route from the start point, as #12 does for the palettes: const start = selection.isBackward() ? selection.focus : selection.anchor; then $findMatchingParent(start.getNode(), $isBookNode). With that change, the forward case keeps the book and Editor.test.tsx passes. Please add a forward-selection case next to the existing test at Editor.test.tsx:1668.

#20 (prefix deletion). The guard only covers DELETE_CHARACTER_COMMAND (ParaMarkerPrefixCursorGuardPlugin.tsx:122). Ctrl/Alt+Backspace sends DELETE_WORD_COMMAND and Cmd+Backspace sends DELETE_LINE_COMMAND, and rich-text handles both through deleteWord / deleteLine without going through the character command. Dispatching DELETE_WORD_COMMAND with the caret at the start of the \id content deletes the \id GEN glyph (no stubbing needed). DELETE_LINE_COMMAND does the same once modify is stubbed for jsdom.

Fix: register the same $shouldRefuseBookPrefixDeletion handler for DELETE_WORD_COMMAND and DELETE_LINE_COMMAND at COMMAND_PRIORITY_HIGH. OpaqueBlockGuardPlugin.tsx:119-128 already does this for its own case. Please add a test for each command.

#22 (test comment). markerEditTier2Trigger.utils.test.tsx:1043 still reads "Chapter/opaque-unknown content is a literal-only degradation context". 3aefe1b dropped "Book" but kept "Chapter". $inLiteralOnlyBlock only checks unknown and table nodes, and its own TSDoc says chapters are a settle scope. The test below it only builds an unknown node. Please make it "Opaque-unknown content ...".

(AI-assisted, with my guidance)

@tjcouch-sil

Copy link
Copy Markdown
Member Author

All three done:

@lyonsil lyonsil 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.

This review covers 12 further findings on this PR, mostly around editing in the \id line, plus a few in the settle code. Each comment's label gives its severity, and "checked and confirmed" means the finding was verified against the code at the current head.

(AI-assisted, with my guidance)

@lyonsil lyonsil 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.

:lgtm:

@lyonsil reviewed 60 files and all commit messages, made 1 comment, and resolved 47 discussions.
Reviewable status: :shipit: complete! all files reviewed, all discussions resolved (waiting on tjcouch-sil).

tjcouch-sil and others added 11 commits September 30, 2026 14:26
…ole list

The right-click menu reuses `.typeahead-popover ul`, whose 200px cap is sized for
the marker typeahead's long, filterable list. The context menu is a short fixed
list (~36px per item), so a host contributing a few insert items pushes it past
that cap — and the items behind the fold could not be reached at all, because the
close-on-scroll listener is registered on `window` in capture phase and so fired
for the menu's OWN scroll, closing the menu on any attempt to scroll down to
them.

Cap the menu's list to the viewport instead of 200px, and ignore scroll events
that originate inside the menu.

Also adds the plugin's first tests. They drive real DOM keydowns rather than
dispatching Lexical commands, which is what makes the capture/bubble propagation
the menu depends on observable — its key handling sits on a capture-phase
listener on `document`, ahead of Lexical's bubble-phase listener on the root
element.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CkuPP4eA6PPSgCTadJ1J95
…e does

The same rule is re-stated in paranext-core's `_editor-overrides.scss`, because
the copy of this file vendored there cannot be edited in place. The two comments
were written separately and drifted into saying the same thing two ways; align
them so a reader comparing the two sees only the deliberate difference — the
host's note about when its override can be dropped.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CkuPP4eA6PPSgCTadJ1J95
…apter

The book node was the one content container the forward adaptor did not
recurse into: `createBook` flattened its content with `getTextContent`,
which returns "" unless the content is exactly one plain string. So the
moment anything else sat in the \id line — a note, say — the whole
content went with it, the line rendered as a bare `\id JON`, and the next
save wrote that truncation back to the file.

The reverse adaptor already recursed the book node's children, so this
was the asymmetric half of the pair and broke the round-trip invariant
the corpus suite exists to hold. Recursing makes the two halves agree;
`getTextContent` had no other caller and goes with it.

Pinned by a corpus fixture (round-trip identity in all five view modes,
plus the transform fixed point) and a forward anchor, since identity
alone is blind to a bug mirrored on both sides.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TXbNhzh48xgmAWmwxqhMXi
The menu's items were `role="option"` inside a bare `ul`, which is not a
listbox, so the role had no list to mean anything in and nothing told an
assistive technology which item the arrow keys had highlighted.

Completes the pattern the plugin had already started rather than moving
to menu/menuitem: focus deliberately stays in the contenteditable the
whole time the menu is open — that is what keeps the selection the chosen
item acts on — and the option list plus `aria-activedescendant` on the
focused element is the pattern for a popup whose owner keeps focus. It is
also what Lexical's own typeahead menu does. Moving focus into the menu
would be the menu/menuitem pattern's requirement and would put that
selection at risk.

The item ids move to their own namespace: Lexical's shared `typeahead-*`
ids are reused by every menu built on its typeahead, and an
`aria-activedescendant` IDREF resolving to another menu's item announces
the wrong thing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TXbNhzh48xgmAWmwxqhMXi
Capping the menu to the viewport fixed the fold at ordinary heights, but
the rule it inherits pairs `overflow-y: scroll` with a hidden scrollbar —
right for the marker typeahead, which you narrow by typing rather than by
scrolling. This menu has no filter, so below roughly 270px of panel
height its last items sat behind a fold with nothing on screen saying
they were there.

`auto` rather than `scroll` so the gutter stays out of the way at the
heights where the whole menu already fits.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TXbNhzh48xgmAWmwxqhMXi
…led to the end

A wheel gesture that reaches the end of the clipped list chains to the ancestor
scroller. That ancestor's scroll event does not originate inside the menu, so
the close-on-scroll listener reads it as the page moving out from under a
fixed-positioned menu and closes the menu — in exactly the case the list is long
enough to need scrolling at all. `overscroll-behavior: contain` keeps the
gesture in the list.

The same override was missing entirely from the three vendored copies of this
stylesheet, so the scribe package and both demos still capped the menu at 200px
behind a hidden scrollbar.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TXbNhzh48xgmAWmwxqhMXi
The `\id` line is a content container like any other — Paratext 9 accepts a
footnote or end note in its text content, and now so does the forward adaptor —
but two guards still treated a book node as a single run of text with nothing
before it:

- Backward arrow navigation blocked every move from offset 0 of a book node's
  text, so a caret in the text after a note could not get back past it. It now
  blocks only when nothing the caret can reach sits to the left, and the
  collapsed-note hop applies in the book line too: there is no verse to sit
  before its notes, because the book code is part of the line's own immutable
  marker text.
- The caret-at-end expand tested `$isSomeParaNode`, which excludes `BookNode`,
  so a note at the end of the `\id` line never expanded for inline editing.
  `$isParaLikeNode` is the existing union of exactly those two.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TXbNhzh48xgmAWmwxqhMXi
…paragraph pick after it

The `\id` line is a BookNode at document root, not a ParaNode, but its text is content like any
paragraph's: Paratext 9 offers the inline marker list there, footnotes included. Two probes still
treated it as the header region:

- The `\` trigger found no ParaNode ancestor and reported paragraph source. Even forced to
  character source it would have listed nothing, because the character list filters on the
  enclosing paragraph's marker. A caret in the line now reports character source with
  `paraMarker: "id"`, which yields the character styles valid under `id` plus every note style.
- A paragraph pick had no paragraph to retag or split, so the Enter palette's Enter did nothing.
  The pick now splits the line at the caret and starts the new paragraph after it, closing and
  reopening an open character span across the cut. It lives in `$splitParagraphWithMarker`
  because the Enter palette calls it directly and never goes through the `\` palette's apply path.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
… at a typed paragraph marker

The `\id` line had no settle scope, so the marker-edit engine kept everything typed there
literal: `\nd Lord\nd*` stayed as text on screen while the save wrote a real span, and the next
load showed the span. What the user saw and what the file held disagreed until a reload.

`$rebuildBook` is the fourth settle scope, beside paragraphs, note content and chapters. Like the
note scope it re-tokenizes only the line's content and preserves the book node, its code and its
immutable `\id GEN ` prefix, which are never re-derived from displayed bytes. The read-only settle
mirrors it, the undo re-pend scan now descends into the line, and live typing display-maps space
runs there the way load and settle already did.

A typed block marker ends the line where the file bytes would: `\p`, `\ip` or `\c` starts its
paragraph or chapter directly after the book, with the tail after the marker moving into it and
the caret following its byte — the same split a paragraph gets. Bytes that literally begin with
`\p` tokenize to a wrapper indistinguishable from the tokenizer's implied one, so they are told
apart by the bytes themselves and leave the line empty.

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

Deleting a paragraph's whole marker merges its content into the previous paragraph, but the
transform only recognized a ParaNode as the previous line. Directly below the `\id` line it fell
through to resetting the marker to `\p` with a fresh visible prefix, so every further Backspace
deleted the re-created marker and grew it back again, forever. The `\id` line takes content like a
paragraph, so a paragraph below it now merges into it the same way, caret at the junction.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The offered list and the commit paths are one contract, so the tests now hold both ends of it.
`markerMenuApply.utils.test.tsx` commits EVERY entry the line offers and asserts the document
changed, with a pin per offered kind: a real character span inside the book, and a real note
whose Lexical key comes back for the host's editing session. A further test builds the list from
a caret in a live editor and compares it to the list the sweep iterates, so the two cannot drift
apart. The `\id`-line fixture is hoisted to module scope, since three describes build it.

The item-source case for the book region still asserted the earlier model — no `paraMarker`, and
the same paragraph list whichever source it was asked for — a context shape the editor no longer
produces. It now pins the inline list under `paraMarker: "id"` and that no paragraph entry reaches
it.

`docs/standard-view-invariants.md` records the rule the line's defects all came from ("The `\id`
line is content, not a header") and the general one they are an instance of ("A menu offers
nothing it cannot insert"), plus the book line's outcome beside the other marker-apply outcomes.

PT-4613

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
tjcouch-sil and others added 9 commits September 30, 2026 14:27
…gationPlugin

$handleBackwardNavigation's second disjunct
($isImmutableTypedTextNode(prevNode) && prevNode.is(bookNode.getFirstChild()))
is exactly $isBookPrefixNode(prevNode), which the function already returns true
for earlier in the offset-0 case that reaches this branch. Reduce to the one
reachable condition and trim the comment to match.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… on a book-line settle

$restoreSelectionInContentRegion's no-byte-anchor fallback picked the first
ELEMENT node among the rebuilt content and entered it with selectStart(). When
that node is a sentinel the fragment builder never gave the caret a byte
position in — most commonly a note that leads the `\id` line's content, with
nothing addressable before it for the element-point anchor to resolve
against — entering it lands an invisible caret inside the note's own body
instead of stopping before it.

Add $selectBeforeFirstUnaddressableRegionChild, which uses $isRebuildSentinel
(the same authority $appendNodesFragment's own sentinel branches already
agree with) to detect this case and select immediately before the sentinel
via its parent and index instead of descending into it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…tent nodes

$rebuildNoteContent and $rebuildBook each re-derive their live content nodes
after the splice by calling $buildNoteFragment/$buildBookFragment, which also
walks the nodes through $appendNodesFragment to build fragment text and spans
neither call site uses.

Factor the guard checks + children slicing each fragment builder starts from
into $noteContentNodes and $bookContentNodes, shared by the fragment builders
and the two post-splice call sites, which now skip the unused fragment walk.
Behavior is unchanged — $buildNoteFragment/$buildBookFragment still build the
exact same fragment from the exact same content nodes.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…tack walk, drop a redundant normalize call

- CharStackBreak.parent is now LexicalNode | undefined instead of
  LexicalNode | null, matching repo convention (undefined unless an API
  requires null). Updates $breakAndLiftCharStack's two return sites and
  the one read site (markerMenuApply.utils.ts's book.is(parent), whose
  signature already accepts undefined).
- $canSplitBookAt (markerMenuApply.utils.ts) and $charStackParagraph
  (charFormatting.utils.ts) each hand-rolled the same
  "climb past every CharNode/TypedMarkNode ancestor" walk. Factored into
  $outermostCharStackAncestor (charFormatting.utils.ts, exported), which
  only does the climb — each caller still computes its own starting node
  (itself or its parent), preserving the two walks' exact prior semantics.
- $splitBookWithMarker called $normalizeSelectionOutOfGlyphText a second
  time; its only caller, $splitParagraphWithMarker, already normalizes
  the selection immediately before calling in, with no selection change
  in between. Removed the redundant call and documented the precondition
  on $splitBookWithMarker instead.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…x, not through it

Cmd+Backspace (DELETE_LINE_COMMAND) on a collapsed caret already past the
book prefix's own boundary reached Lexical's default deleteLine, which
extends the selection to the DOM's own visual line boundary before removing
it (RangeSelection.modify('extend', isBackward, 'lineboundary')). That
extension steps the far endpoint past an adjacent inline, non-isolated
decorator whenever the visual line boundary sits right past the prefix glyph
— the whole line for a short \id line, or a wrapped line's own start for a
long one — so the deletion that followed removed the prefix along with the
content, only $shouldRefuseBookPrefixDeletion's own offset-0 boundary case
was refused.

Add $clampLineDeletionPastBookPrefix, registered for DELETE_LINE_COMMAND
below the existing boundary refusal and above Lexical's own default handler:
it runs the same lineboundary extension, then clamps whichever endpoint
moved onto or past the prefix back to just past it before removing, so a
wrapped line's Cmd+Backspace still deletes only back to that visual line's
own start.

DELETE_WORD_COMMAND needs no equivalent fix: modify() with 'word'
granularity never runs the trailing decorator-stepping pass that
'lineboundary' does, so a genuinely mid-content collapsed caret cannot reach
it — confirmed by reading Lexical's own modify() source.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…d of losing it

A non-collapsed selection that spans the book's own immutable prefix — most
commonly Ctrl+A, whose selection normalizes to an anchor right before it —
hit two different losses depending on the gesture: Backspace/Delete were
silently refused by $shouldRefuseBookPrefixDeletion's non-collapsed branch (a
no-op against the "a keystroke either changes the document or is visibly
refused" rule), while typing over the selection, pasting into it, or cutting
it removed the prefix glyph along with the selected content, since all three
resolve to RangeSelection.insertText()/removeText() against the same
un-narrowed selection.

Add $narrowSelectionPastBookPrefix: for a non-collapsed selection spanning
the prefix, moves whichever of anchor/focus is earlier in document order to
just past it, so the range that survives covers only real content.
$shouldRefuseBookPrefixDeletion's non-collapsed branch now narrows and
returns false (letting the delete proceed on the narrowed range) instead of
refusing, refusing only when narrowing leaves nothing to delete.
CONTROLLED_TEXT_INSERTION_COMMAND, PASTE_COMMAND and CUT_COMMAND each get a
new $narrowSelectionBeforeCommand handler at COMMAND_PRIORITY_CRITICAL — the
top priority, since other CRITICAL-tier handlers for these commands already
exist (StructureKeyboardPlugin, OpaqueBlockGuardPlugin) and CRITICAL-tier
order otherwise follows plugin mount order, which this plugin does not
control.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…e delete

Guarded mode deletes an armed range straight off the keystroke, so the prefix
guard's DELETE_CHARACTER_COMMAND narrowing never sees it: Ctrl+A then Backspace
twice removed the \id line's glyph with the content. Narrow the range past the
prefix before removing it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Home (and Ctrl+Home) put the browser caret on the boundary in front of the
line's read-only `\id GEN ` glyph, so typed text rendered before the book
code while the save wrote it after — the line changed shape on reload.

- A collapsed caret that lands at (book, 0) is moved just past the prefix
  on SELECTION_CHANGE_COMMAND, the same place a click there already goes.
- A BookNode transform moves anything that still lands in front of the
  prefix (a drop, a programmatic insert) to directly after it, in order,
  which is where the save puts it.
- Invariants doc: the prefix is always the book's first child.

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

@lyonsil lyonsil 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.

Fourth-round review of this PR at 93847a88, covering the full diff against main. There are 7 findings. Each comment's header gives the severity the reviewer settled on and a status: checked and confirmed means the finding was verified against the code, and needs a human call means it could not be settled either way and needs your judgment.

Findings that could not be attached to a line in this diff

#8 (low · checked and confirmed) packages/platform/src/editor/markerEdit/virtualSettle.utils.ts:1114 - getUsj() called while an unknown-marker paragraph's rejoin into the \id line is pending returns a paragraph twice when that paragraph holds a transient marker declaration and its bytes start another block (for example \ip).

What happens: in $settledUsj, the rejoin loop puts the artifact paragraph in claimed and in bookTrailingParas (or a two-paragraph paraScopes entry) (virtualSettle.utils.ts:1103-1112). The transient block then calls addScope without checking claimed (:1114-1119), adding [artifact] back to paraScopes. The paragraph pass replaces the artifact's slot (:1176), and the book pass then splices bookIndex + 1 with a delete count of trailingParas.length (:1200), assuming the artifact is still the single node there.

Why it matters: when the artifact's rebuild yields more than one node, the extras stay in the settled USJ as duplicated content, which reaches the host's save.

Fix: In $settledUsj (virtualSettle.utils.ts:1114-1119), change the transient block to if (scope && !claimed.has(scope.getKey())) addScope(scope); so a paragraph already owned by a rejoin scope is not re-added as its own scope (the rejoin scope already receives transient via $settledParaNodes / $settledBookLine). Add a case to packages/platform/src/editor/settledGetUsj.test.tsx (or bookLineSettle.test.tsx): \id line followed by an unknown-marker paragraph whose text contains \ip , glyph retyped to a char marker so the rejoin is pending, plus a verified transient declaration in the artifact's text node; assert exactly one ip block follows the book. Regenerate the committed output with node scripts/rebuild-committed-output.mjs.

How this was checked: A probe test (book line, an unknown-marker \n paragraph holding abc \ip def, glyph retyped to \nd, then $settledUsj with a verified transient declaration in the artifact's text node) returned the \ip def paragraph twice. Without the transient the same state settles correctly. The cause is as described: the rejoin loop claims the artifact (virtualSettle.utils.ts:1103-1112), the transient block re-adds [artifact] to paraScopes without checking claimed (:1114-1119), the paragraph pass splices the artifact's slot with every rebuilt block (:1176), and the book pass then removes only trailingParas.length (1) block after the book (:1200). The duplication needs the artifact's own bytes to tokenize to two or more blocks, so it is narrow; with a single-block rebuild the output is correct. The paragraph-predecessor rejoin does not have this gap, because its two-paragraph scope comes first in paraScopes and removes the artifact's node, so the later [artifact] entry hits indexOf < 0 and is skipped; only the book-predecessor branch (new in this PR) leaves the artifact in place for the book pass. The anchored lines are unchanged by this PR (they date from d5412cb); the new bookTrailingParas handling is what exposes the gap.

Not attached to a line: not on a changed line; cannot be posted inline

(AI-assisted, with my guidance)

Comment thread packages/platform/src/editor/Editor.tsx Resolved

@lyonsil lyonsil 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.

Fourth-round review of this PR at 93847a88, covering the full diff against main. There are 6 findings. Each comment's header gives the severity the reviewer settled on and a status: checked and confirmed means the finding was verified against the code, and needs a human call means it could not be settled either way and needs your judgment.

Findings that could not be attached to a line in this diff

#8 (low · checked and confirmed) packages/platform/src/editor/markerEdit/virtualSettle.utils.ts:1114 - getUsj() called while an unknown-marker paragraph's rejoin into the \id line is pending returns a paragraph twice when that paragraph holds a transient marker declaration and its bytes start another block (for example \ip).

What happens: in $settledUsj, the rejoin loop puts the artifact paragraph in claimed and in bookTrailingParas (or a two-paragraph paraScopes entry) (virtualSettle.utils.ts:1103-1112). The transient block then calls addScope without checking claimed (:1114-1119), adding [artifact] back to paraScopes. The paragraph pass replaces the artifact's slot (:1176), and the book pass then splices bookIndex + 1 with a delete count of trailingParas.length (:1200), assuming the artifact is still the single node there.

Why it matters: when the artifact's rebuild yields more than one node, the extras stay in the settled USJ as duplicated content, which reaches the host's save.

Fix: In $settledUsj (virtualSettle.utils.ts:1114-1119), change the transient block to if (scope && !claimed.has(scope.getKey())) addScope(scope); so a paragraph already owned by a rejoin scope is not re-added as its own scope (the rejoin scope already receives transient via $settledParaNodes / $settledBookLine). Add a case to packages/platform/src/editor/settledGetUsj.test.tsx (or bookLineSettle.test.tsx): \id line followed by an unknown-marker paragraph whose text contains \ip , glyph retyped to a char marker so the rejoin is pending, plus a verified transient declaration in the artifact's text node; assert exactly one ip block follows the book. Regenerate the committed output with node scripts/rebuild-committed-output.mjs.

How this was checked: A probe test (book line, an unknown-marker \n paragraph holding abc \ip def, glyph retyped to \nd, then $settledUsj with a verified transient declaration in the artifact's text node) returned the \ip def paragraph twice. Without the transient the same state settles correctly. The cause is as described: the rejoin loop claims the artifact (virtualSettle.utils.ts:1103-1112), the transient block re-adds [artifact] to paraScopes without checking claimed (:1114-1119), the paragraph pass splices the artifact's slot with every rebuilt block (:1176), and the book pass then removes only trailingParas.length (1) block after the book (:1200). The duplication needs the artifact's own bytes to tokenize to two or more blocks, so it is narrow; with a single-block rebuild the output is correct. The paragraph-predecessor rejoin does not have this gap, because its two-paragraph scope comes first in paraScopes and removes the artifact's node, so the later [artifact] entry hits indexOf < 0 and is skipped; only the book-predecessor branch (new in this PR) leaves the artifact in place for the book pass. The transient block at :1114-1119 predates this PR; the new bookTrailingParas handling is what exposes the gap.

Not attached to a line: not on a changed line; cannot be posted inline

(AI-assisted, with my guidance)

Comment thread packages/platform/src/editor/Editor.tsx Resolved
tjcouch-sil and others added 8 commits October 1, 2026 12:57
Drag-move deletion and composition-driven deletes resolve to
REMOVE_TEXT_COMMAND rather than DELETE_CHARACTER_COMMAND, and
RichTextPlugin's own handler for it calls removeText() against
whatever selection is current. A selection spanning the book's \id
prefix reached that handler un-narrowed, so either gesture removed the
prefix along with the content. Register the same narrowing used for
CONTROLLED_TEXT_INSERTION_COMMAND/PASTE_COMMAND/CUT_COMMAND for
REMOVE_TEXT_COMMAND as well.

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

An unknown-split artifact that rejoins its predecessor (the \id line's
book, or a paragraph) is removed from the single-paragraph scopes and
claimed into the widened rejoin scope. A transient declaration whose
node resolves to that same artifact was added back into the
single-paragraph scopes regardless, so the artifact settled twice:
once joined into the widened scope, once rebuilt alone. When the
alone-rebuild happened to tokenize to more than one block, the second
pass spliced in without removing the first, leaving a duplicate block
in the settled USJ. Skip re-adding a scope the rejoin already claimed
— $settledBookLine/$settledParaNodes both receive the transient
declaration directly, so it still reaches the widened rebuild.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…e nearest paragraph

formatPara's book-split path found where to stop retagging siblings
by walking up from the selection's end node to the nearest ParaNode
ancestor. A selection ending ON a non-paragraph root sibling with no
text of its own — a \c chapter resolves to an element point directly
on the ChapterNode — has no such ancestor, so the lookup returned
nothing and the whole retag silently gave up before touching any
paragraph between the split and that point.

Use the end node's top-level element instead, which every root child
has regardless of kind, and keep the existing $isParaNode(sibling)
guard in the walk so a chapter reached as the end block still stops
the walk without ever being retagged itself.

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

$getEnclosingBook duplicated $findMatchingParent(node, $isBookNode),
the same lookup markerMenuApply.utils.ts already uses for the same
question (an ancestor typed as BookNode | null, not | undefined).
Use the shared helper directly at the one call site instead of
keeping a narrower local wrapper around it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…prefix question

$isSynthesizedMarkerNode(book.getFirstChild()) was spelled out at
three call sites (the book split, the selection-normalize pass, and
the book's own content-nodes helper) to ask the same question: is
this node the \id line's prefix glyph, in whichever marker mode is
rendering it. Name that question once as $isBookPrefixGlyph, beside
$isSynthesizedMarkerNode, and use it at all three sites.

$isBookPrefixNode (the cursor-guard plugin) asks a narrower, different
question — can a caret go here — and deliberately excludes the
editable-mode MarkerNode prefix, which hosts one. Document that split
on both predicates, and pin it with a test showing the editable-mode
glyph is the one case where the two disagree.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…fix early

$narrowSelectionPastBookPrefix called selection.getNodes() — a walk
over every node the selection spans — on every non-collapsed
selection, just to check whether the book's prefix is among them. The
prefix can only ever be in that span when the selection's EARLIER
endpoint is at or before it: an element point on the root itself at
offset 0, or anywhere inside the book (its own element point included,
since a node's top-level element is itself when it already is one).
Check that cheaply first and skip the walk for every selection that
cannot possibly reach the prefix — ordinary mid-document editing,
which is the common case.

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

A test that needs a local reference to a book line's BookNode wrote
book = $createBookLine("GEN", ...children); then appended the bare
variable to root (or alongside siblings) in a later statement — the
same half-flat shape the repo's Lexical-fixture convention forbids
for $createXNode(...).append(...), since $createBookLine builds its
children the same way internally. Hoist the bare $createBookLine(code)
call to the variable and move its children into the root chain's own
.append(...) instead, so the code shape mirrors the resulting tree.
One non-book fixture (a ParaNode built the same half-flat way) got
the same treatment.

Behavior is unchanged: $createBookLine(code).append(...children)
builds the identical tree $createBookLine(code, ...children) does,
since the helper's own children are appended first either way.

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

Copy link
Copy Markdown
Member Author

#8 ($settledUsj duplicating a paragraph): reproduced and fixed in ce61204. The transient block now skips a scope the rejoin already claimed (if (scope && !claimed.has(scope.getKey())) addScope(scope);). The claimed scope still receives transient through $settledBookLine/$settledParaNodes. The new bookLineSettle.test.tsx case (book, unknown-marker paragraph holding \ip, rejoin pending, transient declaration on the artifact) returned two ip blocks before and returns one now.

@lyonsil lyonsil 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.

:lgtm: - I can reapprove after the test failure is fixed.

@lyonsil reviewed 17 files and all commit messages, made 1 comment, and resolved 11 discussions.
Reviewable status: :shipit: complete! all files reviewed, all discussions resolved (waiting on tjcouch-sil).

…e its focus inside the test

Focusing the editor root makes jsdom collapse the selection to the root's
start; the \id-line cursor guard moves that caret past the prefix glyph into
text, and Lexical's post-commit scroll-into-view then calls
Range.getBoundingClientRect, which jsdom does not implement. The throw came
from Lexical's async commit as an unhandled error, so whether it landed (and
failed the run) depended on timing - it failed CI on ubuntu.

The test now flushes jsdom's queued selectionchange inside itself, which makes
the path deterministic, and stubs the Range rect the same way the other
platform tests that move the caret do.

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

@lyonsil lyonsil 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.

:lgtm:

@lyonsil reviewed 1 file and all commit messages, and made 1 comment.
Reviewable status: :shipit: complete! all files reviewed, all discussions resolved (waiting on tjcouch-sil).

@tjcouch-sil
tjcouch-sil merged commit 660adfe into main Oct 2, 2026
6 checks passed
@tjcouch-sil
tjcouch-sil deleted the standard-view-pt-4195 branch October 2, 2026 12:30
lyonsil pushed a commit that referenced this pull request Oct 2, 2026
…rs (#24)

Rest the caret at an empty verse's editable marker, not between markers (#24)

Navigating to an empty verse (one followed only by the next verse
marker) placed the caret with $placeCaretAtBoundary, which hosts the
caret in whatever text node follows the boundary. With editable verse
markers (Standard and Unformatted views) that host is the next verse's
own marker, so the caret landed at offset 0 of `\v 6 ` instead of the
end of `\v 5 `. Both draw at the same screen location, and Lexical
sometimes normalized the point back to the end of `\v 5 ` before the
selection was next read and sometimes did not. That race made "stops
at the next verse marker for an empty verse with an editable marker"
fail intermittently on macOS CI.

$placeCaretAtVerseContentStart now puts the caret at the end of an
editable empty verse's own marker, the rule it already applied to a
verse that opens with a note, milestone or char span. Immutable
markers, used by every other view, are unchanged: they keep the
element point that EmptyVerseCaretGuardPlugin repairs.

The reported verse does not change in either marker style: a caret at
offset 0 of `\v 6 ` also reports verse 5, so the race only ever moved
the caret, never the verse sent to the host.

- TSDoc: $placeCaretAtVerseContentStart covers both empty-verse shapes
  (the next verse marker follows, or the verse ends its paragraph).
  $caretHostAtBoundary and $placeCaretAtBoundary state their calling
  context, and that an editable next verse marker is returned as the
  caret host, so a caller placing a caret right after a verse marker
  must handle that case itself.
- Tests: renames the placement test to "rests at the end of the
  editable verse marker for an empty verse", adds one for an empty
  verse that ends its paragraph, and adds tests that a caret in an
  empty verse reports that verse in both marker styles. None of them
  fails with the placement change reverted: the flushQueuedEvents()
  calls main added in #14 let the race settle in the placement test,
  and the other cases come out the same either way.
- Rebuilds the committed platform dist.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
tjcouch-sil added a commit that referenced this pull request Oct 13, 2026
Brings in #23 (copy limit), #14 (context menu, \id-line editing and the
book settle scope), #24 (empty-verse caret) and #15 (note index, key and
highlight, unfocused applyUpdate, and the note-editing fixes).

Conflicts, resolved to keep both sides' intent:

- Settle engine (tier2Rebuild, virtualSettle): this branch's caret and
  annotation carry ($captureCaret/$restoreCaret through pairRuns, mark
  carry) replaces main's byte anchor with preserved-key counting, which
  covers the same typed-undeclared-marker case through the literal
  alignment. Main's book scope ($rebuildBook, $settledBookLine), note
  close at a typed closer, undeclared-marker-in-note rule and region
  caret restore are kept and ported onto this branch's capture, char
  opener renames, carried runs and tokenizeFragment (tokenizedBookLine
  now takes the fragment, so placeholders keep their kinds). One fragment
  join: $buildParaScopeFragment uses main's $appendParaFragments.
  $charNeedsSentinelAs asks main's edited-glyph question of a span as
  renamed.
- applyUpdate: main's applyOps (focus rule, extra tag, report from
  onUpdate so a call from an update listener works) with this branch's
  applying-update signal and settled-USJ report. The signal is now set
  inside the update and cleared in onUpdate, so a nested call is applied
  and announced once with its ops; the "inside an update" warning and its
  test expectation go, since the call now behaves.
- Note shell guard: this branch's rule that a caret never rests outside a
  protected note (front and past-closer carets go into the content,
  ranges are confined, select-all handled in its own update, moves
  announced with APP_PLACED_CARET_COMMAND) on main's command handling
  (deletes refused or stopped at the shell and closer edges, edits
  confine the range first). The past-closer caret lands at main's
  content-end text point.
- Caller: this branch's caller transform, regex and caret handling are
  kept; main's caller-slot predicate replaces the duplicate scan, and
  $createWholeNote builds the slot for an empty caller (unmergeable).
  The editor->USJ adaptor keeps the identity-based caller slot and adds
  main's Standard-view space collapse after the caller.
- Separator prefix: both helpers kept ($charSeparatorPrefixLength is
  mark-transparent); both use main's $ownsOpenerSeparator.
- Literal-only blocks: the shared $isInLiteralOnlyBlock drops the book,
  which main gave a settle scope.
- Tags: this branch's "tag only a commit that moved a node" and
  APP_PLACED_CARET_COMMAND are kept over main's release-after-commit in
  the caret repairs and scripture-reference placement.
- Committed dist: this branch's; rebuilt separately.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KvcPjD9t3ojhfixqiz43us
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