Skip to content

PT-4540: Make a paragraph's gutter marker selectable - #22

Merged
jolierabideau merged 48 commits into
mainfrom
pt-4540-para-marker-selection
Oct 21, 2026
Merged

jolierabideau merged 48 commits into
mainfrom
pt-4540-para-marker-selection

Conversation

@jolierabideau

@jolierabideau jolierabideau commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Makes a paragraph's gutter marker a selection target in the paragraph-structure view, so the user can pick the paragraph whose marker they are about to change.

  • Select: click the gutter glyph in an editable editor. Selection is click-only; no arrow key stops on a marker, and arrow navigation is unchanged from main. The selection is a Lexical NodeSelection of the glyph, so no glyph byte becomes a document position. $selectParaMarker (shared) is the only way to create one: it selects only in an editable editor where ParaMarkerSelectionPlugin is mounted.
  • While selected:
    • The row is highlighted (psc-para-marker-selected), and the root's aria-activedescendant names the glyph, which carries role="option" and aria-selected.
    • Everywhere else, the selection counts as a caret at the start of the paragraph's text:
      • Any arrow, Escape, typing, dictation, paste and the emoji picker go there. A spellcheck replacement or a drop acts where it was aimed instead.
      • The scripture reference reports that verse.
      • insertMarker, insertNote, applyMarkerMenuSelection and the typed-marker commits act there.
    • Enter and Alt+↓ fire onParaMarkerMenuRequest when it is set. Without it, Enter splits at that position and Alt+↓ acts like any other arrow.
    • Backspace/Delete, and any other deletion (macOS ⌃H/⌃D, a virtual keyboard's), merge the paragraph into the previous one in one undo step. They are a no-op on the first paragraph of a book or after a chapter, and refused under "protected" structure. Under "guarded", selecting the marker is the arming step, so one press merges.
    • Cut, copy and drag are refused unless the browser's selection has moved to other text.
  • Consumers: formatPara retags the selected paragraph in place and keeps it selected. StateChangePlugin and ActiveTextPlugin report the owning paragraph. EditorRef.focus() returns focus to the editor.
  • New paragraphs: in the gutter view, a paragraph the editor creates (an Enter split, a multi-line paste) gets the gutter glyph for its own marker, instead of being reset to \p.
  • Backspace at the start of a line with no verse (a \q2, say) merges it into the paragraph before, as removing its selected marker does. On main it reset the line to \p. "guarded" arms first and "protected" refuses.
  • Public API: EditorRef.getSelectedParaMarker() and EditorProps.onParaMarkerMenuRequest. Every marker selection fires onSelectionChange(undefined), and getSelection() returns undefined for it.

The editor ships no UI or strings. The themed styling and the dropdown wiring land in the paranext-core follow-up (based on paranext-core#2852 / PT-4539). Release order: core should take this editor only in that PR, together with its restoreSelectionIfLost change. Otherwise the toolbar dropdown retags the wrong paragraph after a gutter click. The Character Marker Bar path no longer depends on that, because insertMarker now collapses a marker selection first.

Open before merge: manual and VoiceOver QA (including whether axe's aria-required-parent flag on role="option" without a listbox matters in practice), and a decision on eten-tech-foundation/scripture-editors#548's boundary-normalization finding.

The review response, item by item, is in the PR comments.

AI-assisted — Claude Code (Claude Opus 5.5)

🤖 Generated with Claude Code

This change is Reviewable

jolierabideau and others added 16 commits September 23, 2026 14:13
A paragraph's gutter marker glyph becomes a NodeSelection target. The helpers
are the single definition of that selection for every consumer.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The gutter-glyph click moves to its own LOW-priority registration and claims
the click when it selected a paragraph marker, so rich-text's NodeSelection
clear never sees it. Book and table glyphs keep the caret advance.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
ParaMarkerSelectionPlugin marks the owning paragraph with a class and
aria-selected, follows it across a retag, and removes the stray browser caret
a click leaves inside the glyph.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Arrows leave or walk the marker column (mirrored in RTL), Enter and Alt+Down
ask the host for the marker menu, Escape returns to the text, and typing
collapses to the paragraph's text and proceeds there.

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

Backspace and Delete are refused visibly through a transient root signal the
host renders; cut, copy, paste, drag, drop and controlled text insertion are
refused so the glyph never becomes an edit operand.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Left at a paragraph's first content position and right at a paragraph's end
select the paragraph marker, ahead of the collapsed-note hops so they cannot
skip the stop.

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

formatPara retags the marker's paragraph and keeps it selected; the toolbar
state reports its marker, the active-text box stays on it, and the scripture
reference does not move while it is selected.

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

The test started at verse 1 and asserted nothing moved on select — but the
\li2 glyph resolves to verse 1 without the guard too, so it passed whether or
not the guard existed. Start settled in verse 2 instead, so an unguarded
resolve is a detectable move to verse 1, and exit backward (into verse 1)
instead of forward (back into the already-current verse 2) so the "reports on
the way out" half stays meaningful.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
EditorRef.getSelectedParaMarker names the selected marker, and
EditorProps.onParaMarkerMenuRequest fires on Enter or Alt+Down so the host can
open its paragraph dropdown. Integration tests cover clicks through rich-text,
the idle settle clock, undo, focus round trips, and the invariant regression.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The loop over glyphHelperCalls asserted nothing on a clean run: none of the
selecting/leaving-a-marker interactions actually call the spied glyph-position
helpers, so the "never named the glyph" assertions ran zero times. Add a
positive control — re-select the marker (a node selection, where
getMarkerMenuContext bails out with no call at all) then move an ordinary
caret into the paragraph text and call getMarkerMenuContext again, which does
call $isPointInMarkerGlyphText through the routed shared entry — proving the
spy actually intercepts before trusting its silence.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
A tint across the gutter and the paragraph plus a stronger glyph accent, on a
visual channel of its own so it never competes with the active-text focus box.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
A selected paragraph marker is a NodeSelection with no offsets that admits only
a retag, so it adds no exclusion predicate and no glyph becomes an operand.

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

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

Walking the marker column with arrow keys prevented the arrow's default, so a
selected marker below the fold never scrolled into view (Lexical's own
scroll-into-view only runs for a RangeSelection). ParaMarkerSelectionPlugin's
update listener now scrolls the newly-owning paragraph's element into view
whenever the selected marker's owner changes, with scrollIntoView
feature-detected for environments (jsdom) that lack it.

DROP_COMMAND was refused whenever any marker was selected, regardless of drop
target, because Lexical dispatches DROP straight from the DOM with no
selection update - so a drop anywhere else in the document (e.g. content
dropped into another paragraph) was silently swallowed. The refusal now
follows OpaqueBlockGuardPlugin's pattern and judges the drop by its target,
refusing only a drop onto the selected glyph itself.

Also corrects a comment that described CONTROLLED_TEXT_INSERTION_COMMAND's
payload as always a string; it is `InputEvent | string`.

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

libs/shared-react source changed (ParaMarkerSelectionPlugin), so the platform
package's committed dist must be regenerated to match.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The entry described a paragraph-structure-view feature in a Standard-view contract, mostly as
implementation detail, and predates the invariants owner's sign-off. The rule goes to the owner
with the sign-off request instead.

This reverts commit f433926.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jolierabideau jolierabideau changed the title Pt 4540 para marker selection PT-4540: Make a paragraph's gutter marker selectable Sep 24, 2026
jolierabideau and others added 2 commits September 24, 2026 08:47
- formatPara retags a selected marker's paragraph in place instead of running
  $setBlocksType, which swapped in a fresh ParaNode and dropped its attributes
  and identity.
- A marker is selected only in an editable editor that mounts
  ParaMarkerSelectionPlugin (new paraMarkerSelectionOwner registry). A
  read-only click, which Lexical still delivers while dropping keydown, places
  the caret as before, and an editor without the plugin can no longer create a
  selection whose deletion nothing refuses. The highlight hides while the
  editor is read-only; the unreachable read-only key guards are removed.
- Replace the invalid aria-selected on the paragraph's <p> with the root's
  aria-activedescendant naming the selected glyph.
- -> at a paragraph's end steps over a chapter number or table onto the next
  paragraph's marker, mirroring <- out of that marker.
- Ctrl/Cmd/Alt arrows (other than Alt+Down) collapse to the paragraph's content
  and proceed from there instead of being treated as plain arrows.
- $getSelectedParaMarker and $getSelectableParaMarker share one rule: the
  gutter glyph that is a ParaNode's first child.
- $getActiveVerseKey measures the paragraph prefix with $paraContentStartIndex.
- Document $getParaFromSelection's calling context.
- CHANGELOG: getSelection()/onSelectionChange report no range while a marker
  is selected.
- Rebuild the committed platform dist.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…election

# Conflicts:
#	packages/platform/CHANGELOG.md
#	packages/platform/dist/index.js
#	packages/platform/dist/index.js.map
#	packages/platform/src/editor/Editor.tsx

@katherinejensen00 katherinejensen00 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Review — PR #22: PT-4540 Make a paragraph's gutter marker selectable

#22 · head 462934af · base 7c899221 (main)

Hi Jolie. The feature is well-built where it was aimed. The key handling is carefully mirrored for
RTL, the host signal avoids shipping strings, and the tests are strong: 26 of 28 targeted mutations
were caught. The main problem is that a marker selection is a Lexical NodeSelection, and only
formatPara and three read-only consumers were taught about it. Every other code path still
assumes a caret. The worst case is item 1, which silently rewrites Scripture and is reachable today
from paranext-core's Character Marker Bar. I'd hold the merge for item 1. Items 2–13 should be fixed
or ticketed explicitly. Most of them come from the same root cause, and item 14 proposes one fix
for it.

How this was checked. Findings marked Confirmed were reproduced with throwaway jsdom tests on
the real platform <Editor> in the paragraph-structure view, and a few also in headless Chromium.
The probes were deleted afterwards. Plausible means the mechanism was traced in code but needs a
real browser or assistive technology to observe. The host paths were checked read-only against
paranext-core main (aec038b3f63). The PR's own suites and CI are green, so none of this shows
up there.

Severity: High = block merge · Medium = fix before merge or ticket explicitly · Low = worth
doing · Nit = optional.

Index

# Severity Attach at Issue
1 High packages/platform/src/editor/Editor.tsx:717 insertMarker / applyMarkerMenuSelection delete the glyph and demote the paragraph to \p
2 Medium-High libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:198 The delete refusal can be bypassed (macOS Ctrl+H/D, virtual keyboards)
3 Medium-High libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:268 Focus returning without a click lets typing land in the selected (off-screen) paragraph
4 Medium packages/platform/src/editor/paraMarkerSelection.test.tsx:138 A real mouse click on a marker moves the host's reference back a verse
5 Medium libs/shared-react/src/plugins/usj/ParaMarkerPrefixCursorGuardPlugin.tsx:101 Clicking a verse/chapter number while a marker is selected leaves no selection
6 Medium libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:140 Cut/copy/paste are silent no-ops, including a context-menu paste elsewhere
7 Medium packages/platform/src/editor/editor.model.ts:605 EditorRef.focus() can't return focus while a marker is selected
8 Medium packages/platform/src/editor/Editor.tsx:634 getSelectedParaMarker() is stale inside onSelectionChange; its return type is too thin
9 Medium packages/platform/src/editor/ScriptureReferencePlugin.tsx:398 Host navigation to the verse just before the selected paragraph is ignored
10 Medium libs/shared-react/src/plugins/usj/ParaMarkerPrefixCursorGuardPlugin.tsx:214 Read-only click puts the caret before the leading verse (a regression)
11 Medium libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:210 Text typed with macOS Option, dictation, emoji picker or non-BMP keys is lost
12 Medium libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:274 Selecting a marker can scroll the page by hundreds of pixels
13 Medium packages/platform/src/editor/markerEdit/paraMarkerSelectionIdle.test.tsx:3 Several tests can't catch what they claim
14 Medium (design) libs/shared-react/src/plugins/usj/paraMarkerSelectionOwner.ts:8 Creation and protection are coupled only by a registry; every consumer special-cases the selection
15 Low libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:310 Screen readers probably aren't told a marker is selected
16 Low libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:176 Enter / Alt+↓ are claimed even with no menu handler
17 Low packages/platform/CHANGELOG.md:92 The CHANGELOG's onSelectionChange contract is wrong
18 Low libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:230 A remote delete, or going read-only, strands the marker selection
19 Low libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:152 In protected mode, drops elsewhere are still swallowed
20 Low libs/shared-react/src/plugins/usj/ArrowNavigationPlugin.tsx:1022 Arrow stops around trailing and unclosed notes
21 Low libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:382 ← from the first paragraph's marker is a dead end
22 Low libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:414 ← can land inside a hidden \fig/\ref; sidebar/periph paragraphs are selectable
23 Low libs/shared/src/nodes/usj/node.utils.ts:689 Paragraphs created while editing have no glyph, so they can never be selected (pre-existing)
24 Low packages/platform/src/editor/editor.css:623 The selected-row tint is sized in the paragraph's own em
25 Low libs/shared/src/nodes/features/ImmutableTypedTextNode.ts:41 Stale "unclickable" comments outside the diff; the "three states" wording is off
26 Low libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:55 Comment volume: a few blocks are twice as long as they need to be
27 Nit libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:168 Keydown robustness (event.key undefined, cross-window instanceof, id counter)
28 Nit libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:346 Duplicated helpers and lookups
29 Nit libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.test.tsx:91 CLAUDE.md conventions
30 Nit PR description (general comment) Description inconsistencies

Correctness

1. High — Inserting a marker while a paragraph marker is selected silently rewrites the paragraph

Attach at: packages/platform/src/editor/Editor.tsx:717 · Confirmed

With a marker selected, insertMarker and applyMarkerMenuSelection delete the gutter glyph and
the paragraph is saved as \p. formatPara is the only mutator that was taught about the new
selection.

  • Why: getUsjMarkerAction falls back to selection?.insertNodes([node]) for any selection
    that isn't a range (adaptors/usj-marker-action.utils.ts:503-505). Lexical's
    NodeSelection.insertNodes inserts after the selected node and then removes it.
    ParaMarkerPrefixGuardPlugin then sees a paragraph with no glyph and resets it to \p.
  • Repro: \p \v 1 first / \li2 \v 2 second…. Click the \li2 glyph, then call:
    • insertMarker("wj") → {marker:"p", content:[{char wj}," ",{verse 2},…]}
    • insertMarker("v") → \p with a duplicated \v 2
    • insertMarker("c") → an empty \li2, then \c 2, then a \p holding v2
    • applyMarkerMenuSelection({kind:"char", marker:"nd"}) → demoted to \p
    • insertMarker("q1") changes only the glyph text, so the screen and the USJ disagree
    • insertNote and insertMarker("f") silently do nothing
  • A user can reach it today, in core main with no new host code:
    • The CharacterMarkerBar renders only when viewOptions.hasGutterParaMarkers is set.
    • Its items call editorRef.current?.insertMarker(marker) when selectionState === undefined
      (character-marker-menu.utils.ts:250).
    • A marker selection makes getSelection() undefined, and so selectionState too.
    • This PR's onStateChange reports blockMarker: "li2", which enables the bar.
    • So: click a gutter glyph, then pick \wj in the bar, and the paragraph is demoted.
  • The PR's release-order note only covers formatPara, so it doesn't protect this path.
  • Fix (either):
    • Narrow the getUsjMarkerAction fallback to $isRangeSelection.
    • Or, better (see item 14), have every EditorRef mutator other than formatPara collapse a
      marker selection to the paragraph's content start ($advancePastParaPrefixes), or refuse
      with a logger.warn, before it runs.
  • Test: add a regression test that selects a marker and calls each mutator.

2. Medium-High — The delete refusal can be bypassed

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:198 · Confirmed

The refusal matches only event.key === "Backspace" | "Delete", so other ways of deleting remove the
glyph with no signal.

  • On macOS, Lexical maps Ctrl+H and Ctrl+D to delete. So does any programmatic
    DELETE_CHARACTER_COMMAND, which isn't guarded. Either one removes the glyph, and the paragraph
    silently becomes \p. It then has no glyph, so it can't be selected again until reload.
  • A virtual-keyboard Backspace (key: "Unidentified", keyCode 229) takes the "typing" branch at
    :210. It collapses into the content and then deletes the verse number or the glyph.
  • Fix: also guard DELETE_CHARACTER_COMMAND (and word/line delete) at CRITICAL while a marker
    is selected, the way OpaqueBlockGuardPlugin already does.

3. Medium-High — When focus returns without a click, typing lands in the selected paragraph

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:268 · Confirmed

After Tab/Shift+Tab back into the editor, or a host root.focus() when its dropdown closes, the
caret you see and the selection Lexical holds are different.

  • Chromium draws a caret at the document start. Lexical keeps the NodeSelection and never commits
    the browser's range.
  • Typing "x" then lands at the start of the selected \li2 paragraph, which may be off-screen.
  • Backspace at the visible caret shows the "refused" signal, and → jumps into \li2.

4. Medium — A real mouse click on a marker moves the host's scripture reference back one verse

Attach at: packages/platform/src/editor/paraMarkerSelection.test.tsx:138 · Confirmed

The test clicks by dispatching a bare click. A real click first fires selectionchange, and that
path misbehaves.

  • On mousedown the browser puts a caret inside the glyph. DecoratorBoundarySelectionPlugin (merged
    in from main) turns it into a caret at the paragraph start. The reference plugin reports the
    previous verse, and onSelectionChange fires with that caret.
  • The click then selects the marker. $resolvePosition ignores marker selections
    (ScriptureReferencePlugin.tsx:398), so nothing corrects the reference.
  • Fix: exempt selectable paragraph glyphs in DecoratorBoundarySelectionPlugin's
    $hasDedicatedSelectionOwner.
  • Test: drive the full pointerdown → selectionchange → pointerup → click sequence.

5. Medium — Clicking a verse or chapter number while a marker is selected leaves no selection

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerPrefixCursorGuardPlugin.tsx:101 · Confirmed

Keystrokes are then lost until a second click.

  • A press on a decorator like that doesn't make Lexical rebuild the selection from the DOM.
  • Rich-text's EDITOR-priority click handler then clears the NodeSelection, leaving null.
  • Starting from a caret, the same click works normally.

6. Medium — Cut, copy and paste are refused silently while a marker is selected

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:140 · Confirmed

Ctrl+X/C/V (and EditorRef cut/copy/paste) do nothing and give no hint.

  • This includes a context-menu Paste after right-clicking other text. Lexical only rebuilds the
    selection on a left-button press, so the marker stays selected while the browser has moved the
    caret. Confirmed in Chromium on Windows. Before this PR, paste after a gutter click pasted at the
    start of the paragraph's text.
  • The comment at :201 refuses Backspace visibly because "Invariant I forbids a silent no-op", so
    the plugin contradicts itself. The same comment also names a spec heading without saying what it
    is. CLAUDE.md asks that code stand on its own.
  • Fix:
    • Re-validate against the live DOM selection before claiming (right-click case).
    • Either redirect paste to the paragraph's content, as typing does, or publish a refusal. That
      means widening ParaMarkerRefusedIntent beyond the two delete directions.
    • Reword :201 inline: // Refuse visibly, never silently: the host renders a hint from this signal.

7. Medium — EditorRef.focus() can't return keyboard focus while a marker is selected

Attach at: packages/platform/src/editor/editor.model.ts:605 · Confirmed

The flow this doc describes is Enter → host dropdown → formatPara. After it, focus() leaves
focus on the host control.

  • Lexical's focus() only focuses the root for a range selection.
  • The PR's focus test checks the highlight, not document.activeElement.
  • Fix: focus the root element directly when a marker is selected.

8. Medium — getSelectedParaMarker() is stale inside onSelectionChange

Attach at: packages/platform/src/editor/Editor.tsx:634 · Confirmed

A host that follows the CHANGELOG shows the wrong paragraph marker.

  • The method reads the last committed state.
  • Repro: click from a selected \li2 marker into \p text. onSelectionChange receives the new
    caret, but getSelectedParaMarker() still returns "li2", and nothing corrects it later. A host
    would show \li2 in its paragraph control while formatPara retags \p.
  • API shape (worth settling before it ships):
    • A bare string can't say which paragraph (two \li2s look the same). Widening it later is a
      breaking change, so consider { marker, location } | undefined now.
    • A push signal for "marker selected vs. caret" would spare hosts from polling. onStateChange's
      blockMarker can't tell the two apart.
  • Docs: the TSDoc's first sentence is circular ("the marker of the paragraph whose marker is
    selected, if a paragraph marker is the selection"). Suggest: "The selected paragraph marker's
    name (e.g. "li2"), if a paragraph's gutter marker is selected."

9. Medium — Host navigation to the verse just before the selected paragraph is ignored

Attach at: packages/platform/src/editor/ScriptureReferencePlugin.tsx:398 · Confirmed

With \li2 (verse 2) selected, the host navigating to 1:1 does nothing. The next → then pulls
the host back to 1:2.

  • $moveCaretToVerseStart reads the glyph as belonging to the previous verse, so it decides the
    caret is "already here".

10. Medium — In a read-only editor, clicking a marker now puts the caret before the verse number

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerPrefixCursorGuardPlugin.tsx:214 · Confirmed

The PR dropped main's if ($isSomeParaNode(owner)) return $advancePastParaPrefixes(owner);, so the
fallback now puts the caret right after the glyph, before a leading \v.

  • Nothing corrects it afterwards: the EDITOR-priority $guardCursorOnClick now returns early for
    glyph targets (:119).
  • Repro: read-only editor, click the \li2 glyph.
    • With this PR: getSelection() = {jsonPath:"$.content[3]", offset:0}.
    • With main's line restored: {jsonPath:"$.content[3].content[1]", offset:0}.
  • The old test, "moves a click ON the glyph past a leading verse marker too", was rewritten without
    its verse. The new read-only test never checks where the caret lands.
  • Three places say the behavior is unchanged: the test comment
    (paraMarkerSelection.test.tsx:309-310, "as it did before"), CHANGELOG.md:89-91, and the PR
    body.
  • Fix: add if ($isSomeParaNode(owner) && $advancePastParaPrefixes(owner)) return true; before
    the fallback, and a read-only test with a leading verse.

11. Medium — Some text input is lost while a marker is selected

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:210 · Confirmed

Some kinds of input never collapse into the paragraph, so they're dropped.

  • macOS Option characters (©, “, German @ and \): isEditingKey treats Alt without AltGraph
    as a shortcut, and Chromium on macOS reports Option only as Alt.
  • Dictation, the emoji picker and some IME commits send no ordinary keydown. Lexical ignores
    their input for a NodeSelection, and no browser caret exists.
  • Non-BMP keys (emoji, Adlam) aren't recognised as typing.
  • Fix: collapse on beforeinput rather than trying to classify keydown. Then insertion of any
    kind lands in the content.

12. Medium — Selecting a marker can scroll the page

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:274 · Confirmed

scrollIntoView({block:"nearest"}) targets the whole paragraph and runs on every change of
selected paragraph, clicks included.

  • In headless Chrome, clicking a visible marker jumped the view 300–370px.
  • An ↑ walk onto a tall paragraph still leaves the glyph off-screen.
  • Fix: scroll the glyph element, and skip the scroll for clicks.

13. Medium — Several tests can't catch what they claim

Attach at: packages/platform/src/editor/markerEdit/paraMarkerSelectionIdle.test.tsx:3 · Confirmed

  • Idle and arms tests: paraMarkerSelectionIdle.test.tsx and paraMarkerSelectionArms.test.tsx
    guard against the marker-edit engine's settle clock and delete arms. MarkerEditPlugin never
    registers in this view (markerMode is "hidden", gated at MarkerEditPlugin.tsx:607). Either
    reframe them as defence-in-depth or drop them.
  • Click tests: they use bare synthetic clicks, so they miss item 4.
  • Read-only test: it doesn't assert the caret position (item 10).
  • Trailing-note test: it passes only because it doesn't mount TrailingNoteCaretGuardPlugin
    (item 20).
  • editor.css.test.ts: it hard-codes the class name instead of importing
    PARA_MARKER_SELECTED_CLASS_NAME.
  • Surviving mutations: two mutations survived. The highlight re-applied only when the owner
    changes survived, so the "re-created element" case in the comment at :233 is untested.

14. Medium (design) — The selection model needs one owner

Attach at: libs/shared-react/src/plugins/usj/paraMarkerSelectionOwner.ts:8

Most of items 1–3, 5–9 and 11 come from one thing. "Marker selected" is a NodeSelection, and it
reaches code written for carets, which each have to opt out one by one.

  • Creation vs. protection.
    • Creating the selection and protecting it are tied together only by a module-level registry and
      by a check-then-select sequence that's hand-copied at four sites.
    • $selectParaMarker itself (in shared) is ungated.
    • ArrowNavigationPlugin (which scribe also mounts) and the cursor guard change behaviour
      depending on whether another plugin is mounted. The cursor-guard tests have to fake the
      registration.
  • Consumers. Each one special-cases the selection by hand, and they've already drifted:
    • The consumers are StateChangePlugin:55, ActiveTextPlugin:151, :205,
      ScriptureReferencePlugin:398 and Editor.tsx:634, :717.
    • StateChangePlugin duplicates its snapshot emission.
    • ScriptureReferencePlugin opts out of the marker selection, while ActiveTextPlugin treats it
      as a caret at the content start.
  • Refusals. They're a blocklist of commands, and items 1–3 and 5–6 slip past it.
  • Suggestion:
    • Move click-to-select into ParaMarkerSelectionPlugin so one plugin creates and protects the
      selection. The cursor guard then goes back to one rule and needs no registry.
    • Put the registry beside $selectParaMarker in shared and make that function the gate.
    • Add one shared resolver, e.g. $getSelectionParaContext(selection), for "which paragraph /
      which verse", and decide once whether a marker selection counts as a caret at the content start.
    • Mutators then either accept a marker selection or collapse it first (item 1).
  • This is also your open "Suggested Review Focus" question. The evidence above argues for settling
    it before the host API ships.

Lower severity

15. Low — Screen readers probably aren't told a marker is selected

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:310 · Plausible

  • aria-activedescendant points at a plain <span> with no role, name or selected state, and the
    caret is removed at the same moment.
  • The TSDoc at :68-70 says it's announced "the way it would an option in a list". That's stated as
    fact while VoiceOver QA is still open.
  • Fix: give the glyph a role and label (e.g. role="option", aria-selected), and soften the
    comment until QA confirms it.

16. Low — Enter and Alt+↓ are claimed even with no menu handler

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:176 · Confirmed

  • The keys are preventDefaulted whether or not onParaMarkerMenuRequest is set. Current
    paranext-core, the demo and toolbar mode all leave it unset, so Enter on a selected marker
    (which used to split the paragraph) does nothing.
  • Fix: don't claim the keys when there's no handler.
  • Home, End, PageUp and PageDown also don't move a caret (Plausible).

17. Low — The CHANGELOG's host contract is wrong

Attach at: packages/platform/CHANGELOG.md:92 · Confirmed

  • Every marker selection, by keyboard or click, fires onSelectionChange(undefined). The entry
    says keyboard selection "fires no onSelectionChange", and the PR body's API section says a
    third thing.
  • paranext-core then emits selectionChanged(undefined) and skips its \ and Escape handling.
    Please state the actual behaviour.

18. Low — The marker selection can be left stranded

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:230 · Confirmed

  • Remote delete or split of the selected paragraph leaves a NodeSelection on an orphaned
    glyph. Typing, Enter, Escape and focus() do nothing until an arrow key, Backspace or a click.
  • Going read-only while a marker is selected (e.g. Send/Receive locks the pane) hides only the
    highlight. Meanwhile:
    • getSelectedParaMarker() and onStateChange keep reporting the marker.
    • Ctrl+C is still refused.
    • removeDomRangesInside wipes the reader's text selection on every update.
  • Fix: when the selection loses its owner or the editor stops being editable, clear it or
    collapse it to content.

19. Low — In protected mode, drops elsewhere are still swallowed

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:152 · Confirmed

  • The comment says "a drop elsewhere in the document … must go through". With structure protection
    on, StructureKeyboardPlugin.tsx:193 refuses it anyway while a marker is selected.

20. Low — Arrow stops around trailing notes

Attach at: libs/shared-react/src/plugins/usj/ArrowNavigationPlugin.tsx:1022 · Confirmed / Plausible

  • Collapsed note at a paragraph's end: → skips the position past the note. In the full editor,
    → from that position isn't handled.
  • Unclosed note (closed:"false"): ← from the next paragraph's marker lands after it. Text
    typed there may round-trip as footnote text (Plausible).

21. Low — ← from the first paragraph's marker is a dead end

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:382 · Confirmed

  • $findPreviousCaretPara skips the BookNode, so ← is claimed and nothing happens. The \id text
    was reachable by ← before this PR.
  • → from the end of the \id line doesn't stop on the first marker either. So the "mirror" claim
    doesn't hold here.
  • The tests at ArrowNavigationPlugin.test.tsx:2761, :2775 say "nothing before it takes a caret".
    Their own fixture has caret-able \id text, so they lock the dead end in.

22. Low — Read-only constructs aren't respected

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:414 · Confirmed

  • Hidden \fig/\ref: ← from a marker into a paragraph ending with one puts the caret inside
    it, because $selectParaEnd uses the last descendant. This isn't a regression, but it's new
    code.
  • Sidebar and periph paragraphs are selectable and retaggable even though CSS hides them.

23. Low (pre-existing) — Paragraphs created while editing can never be marker-selected

Attach at: libs/shared/src/nodes/usj/node.utils.ts:689 · Confirmed

  • Enter-splits and multi-line plain-text pastes create paragraphs with no gutter glyph, and the
    split half is demoted to \p.
  • As a result there's nothing to click, the arrow stops skip them, and a caret-based formatPara
    gets reset to \p.
  • The cause predates this PR, but it blocks the new workflow, so please ticket it.

24. Low — The selected-row tint is sized in the paragraph's own font size

Attach at: packages/platform/src/editor/editor.css:623 · Confirmed

  • The 4em fallback in the box-shadow offset resolves against the paragraph's font size. For
    \mt1, the tint runs about 42px past the editor's edge.
  • Fix: use a root-relative unit or a value set once on the root.

Documentation and comments

25. Low — Stale "unclickable" comments, and a miscounted "three states"

Attach at: libs/shared/src/nodes/features/ImmutableTypedTextNode.ts:41 · Confirmed

  • What this line gets wrong: it replaced "makes gutter markers unclickable", but says "It gives a
    gutter glyph three states" and then lists the inline glyph as one of them. It also says all
    three are decided by the cursor guard. ArrowNavigationPlugin and $getSelectableParaMarker
    decide them too.
  • Suggested wording: "It separates three cases, each decided per node: an inline glyph keeps
    its caret; a gutter glyph is never a caret position; and a paragraph's gutter glyph is a selection
    target ($getSelectedParaMarker) that admits only a retag."
  • The same claim, now false, outside the diff:
    • usj-editor.adaptor.ts:927 ("makes it unclickable")
    • delta-apply-update.utils.ts:1759-1760 ("non-selectable aid … unclickable")
    • usj-editor-adaptor.test.ts:205-206
  • A self-contradiction the PR created: ArrowNavigationPlugin.tsx:299 now reads "arrow
    navigation is the only caller; exported … for ParaMarkerSelectionPlugin". Drop the first
    clause.

26. Low — Some comment blocks are about twice as long as they need to be

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:55

Most comments are accurate and well aimed. A few long blocks bury the key point, and the same
"decided per node, never per view" explanation appears in four places: node.utils.ts:656,
ParaMarkerPrefixCursorGuardPlugin.tsx:37, ImmutableTypedTextNode.ts:36-45 and
ArrowNavigationPlugin.tsx:769. Keep it once (on gutterMarkerState) and link to it from the rest.

The blocks worth trimming:

Location Lines Could be
ParaMarkerSelectionPlugin.tsx:55 (plugin TSDoc) 48 ~22 (draft below)
node.utils.ts:647 ($getSelectedParaMarker) 20 ~11
paraMarkerSelection.invariants.test.tsx:118 (positive control) 13 3
ArrowNavigationPlugin.tsx:767 (section comment) 12 7

Draft for the plugin TSDoc. It also fixes three accuracy slips in the current text: the untested
screen-reader claim, the missing CONTROLLED_TEXT_INSERTION refusal, and "pasting it would insert a
glyph" where copy was meant.

/**
 * Owns a selected paragraph marker: its highlight, accessibility state, keys and commands.
 *
 * A marker is selected by a `NodeSelection` of its gutter glyph (`$getSelectedParaMarker`), first
 * made by a click (`ParaMarkerPrefixCursorGuardPlugin`) or an arrow key (`ArrowNavigationPlugin`).
 * Everything here is inert without one. Mounting registers the editor as able to hold that
 * selection (`registerParaMarkerSelectionOwner`); the creators check it.
 *
 * - Highlight: {@link PARA_MARKER_SELECTED_CLASS_NAME} on the owning paragraph, recomputed every
 *   update, plus the root's `aria-activedescendant` naming the glyph. Hidden while read-only.
 * - Keys (CRITICAL, RTL-mirrored): arrows leave or walk the marker column; Enter and Alt+↓ call
 *   `onParaMarkerMenuRequest`; Escape, typing and Ctrl/Cmd/Alt arrows collapse to the content.
 * - Refusals: Backspace/Delete publish {@link PARA_MARKER_REFUSED_CLASS_NAME} and
 *   {@link PARA_MARKER_REFUSED_INTENT_ATTRIBUTE} for the host's hint; cut, copy, paste, text
 *   insertion and drag-start are refused; a drop only when it targets the glyph.
 */

Smaller slips:

  • node.utils.ts:680 is a 139-character line with a sentence spliced into the middle of it.
  • paraMarkerSelectionOwner.ts:10 lists only some of the refusals, and says "never exists" although
    $selectParaMarker is public.
  • The paraMarkerSelectionIdle test header describes a clock that doesn't run in this view
    (item 13).

Nits

27. Nit — Keydown robustness

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:168

  • event.key.startsWith throws on a keydown with no key (some autofill and synthetic events).
    That happens before Lexical's own guard and leaves an update pending. Use event.key?..
  • The instanceof Event / instanceof Node checks at :142 and :153 fail for events from another
    window.
  • Glyph ids come from a module counter (:303-304), so they can collide after hot reload. Derive them
    from the editor key plus the node key.
  • setActiveDescendant removes the root's aria-activedescendant on every update, even when this
    plugin never set it.

28. Nit — Duplicated helpers and lookups

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.tsx:346

  • Sibling walks: $findPreviousCaretPara (exported here) and $findNextCaretPara (private in
    ArrowNavigationPlugin.tsx:830) have the same loop. Move one $findSiblingPara(node, direction)
    into shared next to $getSelectableParaMarker.
  • Forward stop: it's decided in two places ($stopAtNextParaMarker and the note hop at
    ArrowNavigationPlugin.tsx:1018-1027).
  • Marker-to-paragraph lookup: it's repeated at 8 sites with 4 different guards.
  • Other cleanup:
    • $selectParaContentStart has an unreachable fallback, and its name clashes with a different
      platform helper.
    • Five exports have no users outside their own file.
    • ParaMarkerSelectionPlugin imports from three other plugin modules.

29. Nit — CLAUDE.md conventions

Attach at: libs/shared-react/src/plugins/usj/ParaMarkerSelectionPlugin.test.tsx:91

  • Half-flat test trees. These fixtures build each paragraph with its children and then append
    it to the root. CLAUDE.md asks you to hoist only the bare $createXNode(...) and append children
    inside the root chain:
    • ParaMarkerSelectionPlugin.test.tsx:91-94, 597-600
    • ArrowNavigationPlugin.test.tsx:2738, 2780, 2808, 2942, 2966
  • Priority type. ParaMarkerPrefixCursorGuardPlugin.test.tsx:661 types a priority as 0 | 1.
    Use Lexical's CommandListenerPriority.
  • null vs undefined. null is used where undefined works:
    • $getSelectedParaMarker(selection: BaseSelection | null) forces selection ?? null at
      ActiveTextPlugin.tsx:205.
    • $siblingOf returns LexicalNode | null (:347).
    • The test helper activeDescendant returns null (…test.tsx:59-61). It also lets the
      assertions at :125 and :148 pass vacuously when both sides are null.

30. Nit — PR description

Attach at: general PR comment

  • The summary says the self-review "found two real behavior bugs … and one undocumented host-facing
    change. All three are fixed", but it then lists five Important findings.
  • "PR #548" is in another repository. Qualify it (eten-tech-foundation/scripture-editors#548) so
    the link resolves.
  • Update "otherwise the click places the caret as before" (item 10) and the release-order note
    (item 1).
  • The auto-generated block is about 100 lines and repeats your own summary. Collapsing it into
    <details> would bring the ~12-line summary, which is good, to the top.

Checked and not raised

  • onParaMarkerMenuRequest forwarding: it reaches <Editor> through both Marginal and
    Editorial, which spread their props.
  • formatPara on a selected marker: it keeps the glyph's key, the paragraph's attributes, and
    undo behaviour.
  • Host callback timing: queueMicrotask in requestMenu doesn't expose pre-commit state,
    because Enter and Alt+↓ change nothing.
  • → over tables: tables were already crossed whole, so none became unreachable. Shift and
    non-collapsed selections are excluded correctly.
  • StateChangePlugin early branch: it mirrors the normal branch, including the
    getElementByKey guard.
  • Invariants entry: dropping it (d269fb5a) was right, because the doc covers Standard view.
    The retag-only contract should instead be stated where it's enforced, and backed by item 1's
    test.
  • Owner count: the strict-mode double mount goes 1 → 0 → 1, which is correct.

@katherinejensen00 reviewed 30 files and all commit messages, and made 2 comments.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on jolierabideau).


packages/platform/src/editor/Editor.tsx line 717 at r1 (raw file):

          // attributes and identity. The glyph is rewritten in place too, so the selection stays
          // on it.
          const owner = $getSelectedParaMarker(selection)?.getParent();

1. High — Inserting a marker while a paragraph marker is selected silently rewrites the paragraph

Attach at: packages/platform/src/editor/Editor.tsx:717 · Confirmed

With a marker selected, insertMarker and applyMarkerMenuSelection delete the gutter glyph and
the paragraph is saved as \p. formatPara is the only mutator that was taught about the new
selection.

  • Why: getUsjMarkerAction falls back to selection?.insertNodes([node]) for any selection
    that isn't a range (adaptors/usj-marker-action.utils.ts:503-505). Lexical's
    NodeSelection.insertNodes inserts after the selected node and then removes it.
    ParaMarkerPrefixGuardPlugin then sees a paragraph with no glyph and resets it to \p.
  • Repro: \p \v 1 first / \li2 \v 2 second…. Click the \li2 glyph, then call:
    • insertMarker("wj") → {marker:"p", content:[{char wj}," ",{verse 2},…]}
    • insertMarker("v") → \p with a duplicated \v 2
    • insertMarker("c") → an empty \li2, then \c 2, then a \p holding v2
    • applyMarkerMenuSelection({kind:"char", marker:"nd"}) → demoted to \p
    • insertMarker("q1") changes only the glyph text, so the screen and the USJ disagree
    • insertNote and insertMarker("f") silently do nothing
  • A user can reach it today, in core main with no new host code:
    • The CharacterMarkerBar renders only when viewOptions.hasGutterParaMarkers is set.
    • Its items call editorRef.current?.insertMarker(marker) when selectionState === undefined
      (character-marker-menu.utils.ts:250).
    • A marker selection makes getSelection() undefined, and so selectionState too.
    • This PR's onStateChange reports blockMarker: "li2", which enables the bar.
    • So: click a gutter glyph, then pick \wj in the bar, and the paragraph is demoted.
  • The PR's release-order note only covers formatPara, so it doesn't protect this path.
  • Fix (either):
    • Narrow the getUsjMarkerAction fallback to $isRangeSelection.
    • Or, better (see item 14), have every EditorRef mutator other than formatPara collapse a
      marker selection to the paragraph's content start ($advancePastParaPrefixes), or refuse
      with a logger.warn, before it runs.
  • Test: add a regression test that selects a marker and calls each mutator.

jolierabideau and others added 6 commits September 25, 2026 14:34
A paragraph's gutter marker is now selected only by clicking it. Arrow
navigation goes back to its main-branch behaviour: ←/→ no longer stop on
the marker at a paragraph boundary, and the collapsed-note forward hop
lands on the next paragraph's content again. On a selected marker, ↑/↓
now return the caret to the paragraph's content instead of walking the
marker column, so the scroll-into-view that served the walk is gone.

isMovingForward stays exported from ArrowNavigationPlugin for now,
because the selected-marker ←/→ handling still uses it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
With a marker selected, every arrow key, whatever its direction or
modifiers, now ends the marker selection and puts the caret at the start
of that paragraph's content, and stops there. Alt+↓ still asks the host
for the marker menu. The arrow's own movement does not follow, so the
scripture reference lands only where a click at that position would put
it.

The ← exit to the previous paragraph's end and its helpers are removed,
and ArrowNavigationPlugin is identical to main again. The plugin
docstring now says keyboard selection is left to the arrow-navigation
work.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Removing a paragraph's marker now merges the paragraph into the one
before it, as removing a paragraph marker does in other programs,
instead of being refused. Both keys call $mergeParaIntoPrevious on the
owning paragraph. That is the merge StructureKeyboardPlugin performs
from a caret, so the paragraph is the operand and the glyph never is.
It runs in one update, so one Undo restores the document. With nothing
before the paragraph to merge into, the key does nothing and the marker
stays selected. "protected" structure refuses the merge, as it does from
a caret, so ParaMarkerSelectionPlugin now takes structureProtectionMode.

The refusal signal (psc-para-marker-refused,
data-para-marker-refused-intent and its constants) is removed.

$mergeParaIntoPrevious now drops the merged paragraph's gutter marker
glyph instead of moving it into the middle of the previous paragraph.
That also fixes the guarded two-step merge in the paragraph-structure
view.

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

Power and Standard view build no gutter glyph, so marker selection must
not change anything there. The tests build the same paragraph twice,
flipping only gutterMarkerState rather than switching view mode. The
inline glyph is not selected by a click, and keys pressed on it behave
exactly as they do with ParaMarkerSelectionPlugin unmounted.

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

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

Address review of the paragraph-marker selection. Selecting a marker was
a NodeSelection that reached code written for carets, so each consumer
had to opt out by hand, and several did not.

- $selectParaMarker (shared) is now the single gate: it selects only a
  selectable glyph, in an editable editor with an owner registered. The
  owner registry moves beside it, and paragraphs inside an UnknownNode
  are no longer selectable.
- ParaMarkerSelectionPlugin owns click-to-select as well as protecting
  the selection; the cursor guard is back to one rule, and a click on a
  glyph it cannot select now lands past a leading verse number.
- Everywhere else a selected marker counts as a caret at its paragraph's
  content start: EditorRef mutators collapse to it before running (a
  NodeSelection no longer reaches insertNodes, which deleted the glyph),
  and the scripture reference resolves from it, so host navigation to
  the previous verse moves and a real click reports no stray verse.
- Every deletion (DELETE_CHARACTER_COMMAND, beforeinput delete*) merges
  like Backspace; text input with no keydown lands in the text; paste
  and clicks elsewhere follow the browser's selection; focus returning
  without a click removes the browser's stray caret; EditorRef.focus()
  focuses the root; Enter and Alt+Down pass through without a menu
  handler; an orphaned selection collapses on the next key; read-only
  stands the refusals and reporters down.
- In the gutter view a paragraph without its glyph (an Enter split, a
  multi-line paste) gets one for its own marker instead of being reset
  to \p.
- The selected glyph gets role="option" and aria-selected; the row tint
  is sized by a length computed on the root.
- Comments, CHANGELOG and TSDoc are brought in line; the idle/arms tests
  are reframed as defence in depth.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
jolierabideau and others added 11 commits October 16, 2026 14:52
Restoring a paragraph's gutter glyph meant to move a caret at the
paragraph's start past the glyph, but inserting the glyph had already
shifted that element point to offset 1: between the glyph and any
leading verse number, which is no caret position, and one that
$caretAtParaStart read as the paragraph's start, so a single Backspace
merged the paragraph, verse and all. Any element point inside the
prefix now goes to the first content position, hosted by the text there
when there is some.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A marker action at any non-range selection built its node and dropped
it: EditorRef.insertMarker after a verse insert (which leaves a node
selection on the new verse), the marker menu, or formatPara's caller saw
nothing inserted and nothing logged. It now logs a warning, as formatPara
does for the same shape, so the refusal can be diagnosed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With a paragraph marker selected and a menu handler set:

- Any Enter opened the menu, so Shift+Enter and a host's Ctrl/Cmd+Enter
  shortcut never reached anything else. Only an unmodified Enter asks
  for the menu now; a modified one acts from the paragraph's text, as
  Enter does with no menu.
- A virtual keyboard's Enter names no key, so the beforeinput decided,
  and insertParagraph split the paragraph. It now asks for the menu as
  a hardware Enter does.

Also notes on $removeMarker why its callers claim the key even when the
merge is refused or impossible.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
$restoreGutterMarkerIfMissing returned as soon as a paragraph led with
any glyph, and found a displaced glyph only by its exact text. So a
leading glyph naming another marker (another paragraph's nodes pasted
in) was shown indefinitely, and a displaced glyph of an older marker was
missed after a retag: a second glyph went in front and the old one was
stranded mid-paragraph. The restore now keeps exactly one gutter glyph,
first, relabelled to the paragraph's marker, and removes any others.
That also covers a merge that moves such a stray into the previous
paragraph, since the transform runs there too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The press that tells the focus handler to stand down could stick on: it
was heard on the root only, ended only by pointerup, and counted any
button. A text drag or a touch scroll (pointercancel, no pointerup) or a
right-click whose release a native context menu swallowed left it set,
and from then on Tab or a host's focus() left the browser's caret drawn
at the document start while a marker was selected.

The press is now heard on the document, primary button only, and ended
by pointercancel too, as in DecoratorBoundarySelectionPlugin and
NoteShellCaretGuardPlugin. The focus handler's deferred pass is cleared
on unmount and re-checks that the editor is still editable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The gutter-glyph exemption from boundary snapping is for a click, which
the marker's own rules answer. It applied to range ends too, so a drag
from the glyph across the text left Lexical no selection and the
highlight was cleared. The glyph is now exempt only for a collapsed
landing.

The plugin's caret helper also drains selectionchange twice, as the
platform suite's dragSelect does, so one test's repair can't swallow
the next test's first selection change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- $collapseParaMarkerSelection said it had collapsed a marker selection
  whenever the orphan repair ran, including when the repair found no
  paragraph to put the caret in and left no selection. The EditorRef
  edits that call it then went ahead with none. It now reports whether
  there is a caret.
- A click on a note caller while a marker was selected put the caret in
  the selected paragraph, however far away: the caller's parent is its
  note, not a paragraph. The caret now goes just past the clicked
  node's place in its own paragraph (past the note), and to the selected
  paragraph only when there is no paragraph around it (a chapter
  number).
- $collapseParaMarkerSelection's TSDoc no longer says "Mutating" twice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
For a paragraph holding only its glyph (a \b, an empty \p, or the one
an Enter split leaves), $getParaMarkerSelectionLocationNode fell back to
the glyph, which the marker menu and scripture reference then read as a
position (the menu as being in marker text). It now falls back to the
paragraph itself.

The invariant test that claims to pin this ran on a non-empty paragraph
only, so it never reached the fallback. It now also runs on an empty
\p, and fails without the fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
While a paragraph marker is selected the browser holds no range, so
getMarkerMenuContext() reported no anchorRect, and a palette opened from
the marker had nowhere to go. It now reports the glyph's own rect.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Standard view's paragraph prefix is editable text, and Lexical
re-anchors a caret at the start of a paragraph's content onto the text
before it whenever it reads the DOM selection back (the
boundary-normalization finding in eten-tech-foundation/scripture-editors#548).
So the caret a merge places is not where it stays. These tests go through
the real editor: a guarded two-step Backspace, the read-back, typing, and
the settled USJ. The typed text lands at the join in all three shapes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jolierabideau

Copy link
Copy Markdown
Contributor Author

@katherinejensen00 Round 3 is addressed in 4f942db1…3f1e79c7 (source and tests) and 69f869f7 (rebuilt dist), on top of d49703db, which merges main.

13 of the 17 items are fixed, 2 are partly fixed (15 and 17), 1 is left as it is (16), and 1 is left to the tickets that already cover it (6), with reasons below. Every fix began with a jsdom test that failed on the old code, since you traced these in code only. Suites: shared 725, shared-react 1893, platform 2394, all passing. Lint and typecheck are clean. verify-committed-dist.mjs passes, and a second clean rebuild is byte-identical.

Merging main

Main had moved 4 commits, with conflicts in 12 files:

  • $mergeParaIntoPrevious: takes main's filter, which drops any leading marker flavor and its separator and allows a merge into the \id line. It keeps this branch's junction caret, widened to ParaLikeNode.
  • ParaMarkerPrefixCursorGuardPlugin: keeps this branch's $paraContentStartIndex / registerParaMarkerPrefixCursorGuard split. Main's book-prefix guards are registered from the plugin component.
  • ScriptureReferencePlugin: takes main's $resolvePosition-based "already here" check. It already reads a marker selection through $getSelectionLocationNode.
  • Everything else: both sides kept.

I re-tested marker selection against the two main changes that touch the same code:

  • Copy limit (8b0b0bbe): this found a real bug. The limit's $fit runs ahead of the marker plugin at CRITICAL. With a marker selected, it measured the one-glyph selection and passed it. The marker plugin then adopted the range the browser had moved to (after a right-click), and rich-text copied all of it, past the limit. Fixed in 4f942db1: the marker plugin now sends an adopted cut, copy or drag-start through the command again, so the limit sees the real range whatever the registration order. There are tests for copy and for cut.
  • Caret at an empty verse (d2b7a234): no conflict. That change is for editable verse markers, and marker selection only exists in gutter views, where verses are immutable. One edge to know about: for \li2 \v 2 \v 3 text (empty verse 2), selecting the marker reports verse 3, and Escape lands in verse 3. That is the same rule main's gutter click uses (skip every leading verse), so I left it.
  • One test changed: noteIndexAndHighlight's "applies the highlight without committing an editor update" failed about 1 run in 3 on the merged branch, never on main. The stray commit was the scrRef plugin's deferred caret placement from mount, which this branch's extra mount work pushes past the mount act. The test now lets a macrotask pass before it counts commits: 20 of 20 runs passed after the change.

High

# Resolution
1 Fixed (1cd90d57), by restoring the refusal. A drop with no range goes through $sanitizeAndInsert again, which inserts nothing and claims the drop. A selected marker has already moved the selection to the drop point by then. There are tests for a drop from no selection and from a node selection: the USJ is unchanged and preventDefault is called.
2 Fixed (94f35f1c). Main's merge now drops the merged paragraph's MarkerNode, which closes your exact repro. All three merge tests now assert the caret, and there are two new ones: your note-junction repro, which fails against the pre-merge merge body, and a previous paragraph holding only its Standard-view marker. In that second shape the caret went to the end of the marker's separator. A marker or separator junction now counts as no content. That change is tidier but turned out not to be needed: 3f1e79c7 shows text typed from the old landing still settles correctly (see #548 below).
3 Fixed (85d38fe4). (a) StructureKeyboardPlugin now answers DELETE_CHARACTER_COMMAND itself, through the same arming path a Backspace keydown takes. ⌃H arms on the first press and merges on the second under "guarded", and is refused under "protected". The marker plugin merges from a caret only under "off". (b) $getGutterParaWithCaretAtStart qualifies the paragraph through $getSelectableParaMarker, so a paragraph inside an \esb is excluded. (c) Both handlers check isEditable() first. There are tests for guarded, protected, read-only and inside an \esb. One caveat on (c): in a read-only editor, rich-text's own handler still runs a dispatched DELETE_CHARACTER, as it does for any text (Lexical behaviour, the same on main). The test pins that this plugin no longer merges.

Medium

# Resolution
4 Fixed (aa08afb9). When applyDOMRange resolves no point, it leaves the root's start. $adoptDomRange now treats that as no range. There's a test that drops on a verse number.
5 Fixed (2b1000bc), with a correction to the diagnosis. The hardcoded 1 never actually ran: insertBefore had already shifted the point to (para, 1), so the offset === 0 check missed it. Any element point inside the prefix now goes to the content start, hosted by the text there when there is some. An element point between two decorators didn't survive jsdom's selection read-back. I did not change $caretAtParaStart's element rule. With the pin fixed, (para, 2) (past the verse) already reads "not at start". That matches a text caret at the same spot, which arms the verse; comparing against $paraContentStartIndex would make it merge the paragraph instead.
6 Left as is, to PT-4121 and PT-4688. Both callers keep claiming the key. Let through, rich-text deletes the selected glyph itself (or, from a caret, the glyph before it), and the guard restores it. That is the empty undo step round-2 item 6 removed. The real gap is §I's visible refusal. No refusal signal exists in protected mode yet; the psc-para-marker-refused signal you mention belonged to the earlier refuse-on-Backspace design, which merge-on-delete replaced. PT-4121 and PT-4688 already cover most of these refusals, and core already has the rendering pieces, so I've left it to them rather than open a third ticket. $removeMarker now says why the callers claim.
7 Fixed (c20364f9). A logger.warn for any non-range selection, and the comment now says "any non-range selection". There's a test.
8 Fixed (75ab275a). Only a bare Enter asks for the menu; a modified one acts from the text, as Enter does with no menu. insertParagraph in beforeinput asks for the menu when one is set. There are tests for each modifier and for the soft-keyboard input. The TSDoc, the CHANGELOG and the prop doc are updated.
9 Fixed (461e09b7). The restore now keeps exactly one gutter glyph, first, relabelled to the paragraph's marker, and removes any others. That covers (a), (b) and the merge's mirror hole, since the transform runs on the merged paragraph. There are tests for both repros.
10 Fixed (60e5435d), with the sibling arrangement: document-level pointerdown/pointerup/pointercancel, the primary-button guard, a stored timer cleared on unmount, and the editability check in the callback. There's a test for each part.

Low

# Resolution
11 Fixed (638572a5). The glyph is exempt only for a collapsed landing. The test also exposed an order dependence in that suite: Lexical skips the first selectionchange after a repair's own write. putDomCaret now drains twice, as dragSelect does.
12 Fixed (360bfe9d). It returns $isRangeSelection($getSelection()) after the repair. There's a test; it needs an unrelated paragraph left in the document, because emptying the root leaves Lexical no selection to repair.
13 Fixed (360bfe9d). The caret goes past the clicked node's place in its own paragraph (past the note), and to the selected paragraph only when there is no paragraph around it. There's a test.
14 Fixed (b89c6d03). The fallback returns the paragraph, never the glyph. The invariant test now also runs on an empty \p, and fails without the fix.
15 Rect fixed (ff72248e): getMarkerMenuContext() anchors at the glyph's own rect. source left as "character", on purpose. onParaMarkerMenuRequest's documented route is to apply the pick with formatPara. Reporting "paragraph" would steer a host to applyMarkerMenuSelection instead, which splits a verse-led paragraph rather than retagging it (your 17.3). The existing test pins "character". I'd rather fix 17.3 before changing this.
16 Left as is. $getSelectedParaMarker is documented as safe in any read, including editorState.read(), which has no active editor to ask isEditable() of. Gating it there would break that contract for every caller.
17 Fixed: the duplicated "Mutating" line. Left: isPreventable stays structural, because the suite drives these handlers with plain-object events (preventable()) that instanceof Event would reject. The CRITICAL allowlist, the applyMarkerMenuSelection split, the isTypingKey fork, the efficiency items and the shared fixtures are each bigger than a nit. I've left them for a follow-up rather than widen this PR again.

Not numbered, but noted: the update listener's removeDomRangesInside on every update (your "also worth a look"). It needs a real browser to confirm the timing, so it goes in the manual QA pass below.

eten-tech-foundation/scripture-editors#548

That PR's boundary-normalization finding: in Standard view, Lexical moves a caret at the start of a paragraph's content onto the end of the text before it (the marker or its separator) whenever it reads the DOM selection back.

Decision: no code change for it in this PR.

  • Marker selection is unaffected. It exists only in gutter views, whose prefixes are decorators, which normalization skips.
  • The Standard-view merge caret this PR places is affected, but harmlessly. 3f1e79c7 pins it the way #548 says to: through the real editor, with a guarded two-step Backspace, the selection read-back, typing, and then the settled USJ, never the caret's node. The typed text lands at the join in all three shapes (after text, into a marker-only paragraph, after a trailing footnote). With the pre-round-3 placement put back, it still settles correctly, which is your correction on #548: the engine re-tokenizes typing at a marker's edge.
  • What jsdom can't show is a real browser's read-back. The Chrome check below covers that.

Still open before merge

  • Manual QA, and VoiceOver QA, including:
    • the axe aria-required-parent warning on role="option" with no listbox, and the id cleanup you noted;
    • in Chrome, a guarded two-step merge in Standard view followed by typing, to confirm #548's read-back in a real browser.

🤖 Generated with Claude Code

@katherinejensen00 katherinejensen00 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

One thing to fix, but it is minor, so going ahead and approving the changes.

One of the new tests is flaky. It's "lands at the merged text when the previous paragraph holds only its marker" (structureKeyboard.utils.test.ts:678). It failed for me once in two full runs, and 1 in 12 times when I ran that file alone. It fails the same way every time: the caret ends up at the end of the separator (" ", offset 1).

  • Cause: it's the #548 read-back race. Lexical sometimes reads the browser's selection back before the test checks the caret, and moves it onto the separator.
  • The test can't hold in a real browser either. Jolie's own guardedMergeTyping test says a caret check like this "proves nothing".
  • Fix: a few lines in the test only. Check the caret inside the same update that does the merge, or drop the check and rely on guardedMergeTyping.
  • This flake is on the PR branch itself, not something merging main brought in.

@katherinejensen00 reviewed 36 files and all commit messages, made 1 comment, and resolved 1 discussion.
Reviewable status: :shipit: complete! all files reviewed, all discussions resolved (waiting on jolierabideau).

jolierabideau and others added 3 commits October 21, 2026 10:40
The caret check ran after the commit, racing Lexical's DOM selection
read-back, which can move a caret at content start onto the end of the
separator before it. Asserting inside the update that places the caret
makes the check deterministic.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in the host's settle-clock suspension (PT-4611). Only the
committed platform dist conflicted; it is rebuilt in the next commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@katherinejensen00 katherinejensen00 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

@katherinejensen00 reviewed 9 files and all commit messages.
Reviewable status: :shipit: complete! all files reviewed, all discussions resolved (waiting on jolierabideau).

The previous rebuild left dist/index.d.ts as tsc's unrolled output, with
bare workspace imports consumers cannot resolve, and dropped
tsdoc-metadata.json.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jolierabideau
jolierabideau merged commit b5c29f5 into main Oct 21, 2026
5 of 6 checks passed
@jolierabideau
jolierabideau deleted the pt-4540-para-marker-selection branch October 21, 2026 17:47
timothy-mccormack added a commit that referenced this pull request Oct 22, 2026
…" in text

- StructureKeyboardPlugin's DELETE_CHARACTER_COMMAND handler (from #22)
  armed again on the fire's own dispatch, so a guarded selection holding
  a verse could never be deleted. The fire, and every edit the guard
  replays after a "delete" answer, now run in an update tagged
  CONFIRMED_DELETE_TAG, which that handler lets through under "guarded".
- The guard steps aside for a character delete protected structure's new
  command handler refuses, so it no longer asks for nothing.
- "Keep" before a paragraph that opens with a note puts the caret just past
  the note, in text: before it, typing was lost and an NBSP inserted.
- "Keep" after a paragraph that ends with hidden content puts the caret at
  the end of the visible text before it, where typing would land anyway.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
timothy-mccormack added a commit that referenced this pull request Oct 27, 2026
PT-4540 (#22) restores a paragraph's gutter glyph whenever it goes missing,
which covers most of PT-4121. Under structure protection, a few deletes
still removed or merged structure:

- Word and line deletes (Cmd+Backspace, Alt/Ctrl+Backspace, macOS Ctrl+K)
  extend the selection before removing it, past the caret-only keydown
  check. Cmd+Backspace on a verse-led line removed the verse and merged
  the line into the one above; Ctrl+K at a line's end pulled the next
  paragraph up, or swallowed a chapter marker. These now extend once,
  judge that range, and delete exactly it or refuse.
- A range covering a chapter marker counts as crossing a block.
- Delete in front of a gutter glyph, and Backspace at a first-block
  glyph's start, are refused instead of deleting and rebuilding the glyph.

Adds a real-Editor test of the locked paragraph-structure view.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
timothy-mccormack added a commit that referenced this pull request Oct 27, 2026
* PT-4121: Keep paragraph markers when the structure is locked

PT-4540 (#22) restores a paragraph's gutter glyph whenever it goes missing,
which covers most of PT-4121. Under structure protection, a few deletes
still removed or merged structure:

- Word and line deletes (Cmd+Backspace, Alt/Ctrl+Backspace, macOS Ctrl+K)
  extend the selection before removing it, past the caret-only keydown
  check. Cmd+Backspace on a verse-led line removed the verse and merged
  the line into the one above; Ctrl+K at a line's end pulled the next
  paragraph up, or swallowed a chapter marker. These now extend once,
  judge that range, and delete exactly it or refuse.
- A range covering a chapter marker counts as crossing a block.
- Delete in front of a gutter glyph, and Backspace at a first-block
  glyph's start, are refused instead of deleting and rebuilding the glyph.

Adds a real-Editor test of the locked paragraph-structure view.

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

* PT-4121: Address review findings on locked paragraph markers

- Delete in front of a line's glyph now steps past the glyph and deletes
  the line's first character instead of being refused (a silent no-op);
  an empty line is still refused.
- Ctrl+K / forward word delete at the end of the \id line is judged for
  structure before being handed to the book-prefix clamp, so it no
  longer deletes \c 1 or merges \h into the \id line.
- Word/line deletes over a range narrow past the \id prefix and a line's
  gutter glyph first, and refuse a range of nothing but glyphs, instead
  of rebuilding the glyph with an empty undo step.
- The word/line handler stands aside for opaque blocks itself rather
  than relying on mount order to lose its HIGH-priority tie.
- Tests: cover the chapter rule with a range reaching past \c 2, check
  the chapter Ctrl+K test against the right paragraph, and make the
  modify stub assert the alter/direction/granularity it receives.
- Document the calling context of $selectionSpansBlockBoundary.

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

* PT-4121: Refuse word/line deletes that extend into an opaque block

The opaque-block guard judges only the caret, so a word or line delete
from just outside a figure could extend into its caption and remove part
of it. The structure-locked word/line handler now re-checks the extended
range and refuses when it reaches into an opaque block.

Also: snapshot the caret on DELETE_CHARACTER only when it is actually
moved past a gutter glyph, test the gutter-glyph start once in the
backward-delete rule, and share the empty-paragraph test fixture.

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

* PT-4121: Format protectedParaMarker test

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

* PT-4121: Address review of the hidden-content guard under the lock

- Delete in front of a line's glyph, on a line whose content starts with
  a hidden figure, now asks before removing it: under the lock the
  hidden-content guard judges a forward delete from just past the glyph
  (on a copy, so "keep" leaves the caret in place), as the lock runs it.
- The guard and the lock judge a word or line delete's extent by one
  rule, $shouldRefuseExtendedDelete, which also refuses an extent that
  ends partway into an opaque construct: a confirmed word delete no
  longer removes a figure whose caption it reaches into.
- A confirmed line delete narrows past the line's gutter glyph, so the
  glyph is no longer deleted and rebuilt.
- Share the range snapshot helper; add $rangeReachesIntoOpaqueBlock.
- Document the calling context of $shouldBlockStructuralEdit and
  $shouldBlockSelectionReplacement, and why a word or line delete is
  measured twice when no hidden content is found.
- Tests: Delete and a forward character delete in front of a verse-led
  line's glyph are refused.

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

* PT-4121: Under the lock, refuse a word or line delete that leaves the line

When a word or line delete's measured extent leaves the caret's line,
the hidden-content guard used to ask and, on "delete", remove the hidden
content up to the line's edge - even though the lock refuses that
gesture (e.g. Cmd+Backspace mid-line on a verse-led line holding a
hidden figure). Under "protected" it now judges the full measured extent
and steps aside for the lock's refusal.

The exception is hidden content right at the caret: an Alt+Backspace
just after a hidden figure that starts a line still asks, and takes only
that figure, as before.

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

* PT-4121: Address Katherine's review of the locked word/line deletes

- A forward delete in front of a line's gutter glyph is now judged by
  $shouldBlockStructuralEdit itself, from just past the glyph, so every
  caller agrees: the keydown check, the character-delete handler, the
  hidden-content guard's step-aside, and MarkerEditPlugin's predicate.
  Delete in front of an empty line's glyph no longer asks about (and on
  "delete" removes) a hidden sidebar after it.
- It is refused outright when what follows the glyph is display-only -
  a verse marker, a milestone, or a hidden construct - instead of
  deleting it unseen.
- The word/line handler judges the caret before moving it, so a caret
  refusal never moves it; and where a line extension finds nothing to
  extend into (a line ending in a hidden figure) it extends one
  character and judges that, instead of Lexical's fallback merging the
  next line.
- Only the lock narrows a cut or confirmed delete past a line's glyph;
  unlocked, a cut copies the paragraph marker again.
- $shouldRefuseExtendedDelete drops its unused intent; the guard's
  extent carries an explicit leavesLine flag.
- Tests: guard and utils tests in shared-react for these rules; word
  delete stubs land where Chrome lands; both selection ends are checked
  on refusal. Each rule has a test that fails when it is reverted.
- Comments and docs: the \id hand-off, defense-in-depth for opaque
  extents, what "keep" does, and the chapter rule in clipboard docs.

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

* Rebuild the platform source map to match CI

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

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
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.

3 participants