Repository navigation
PT-4540: Make a paragraph's gutter marker selectable - #22
Conversation
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>
- 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
left a comment
There was a problem hiding this comment.
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:
getUsjMarkerActionfalls back toselection?.insertNodes([node])for any selection
that isn't a range (adaptors/usj-marker-action.utils.ts:503-505). Lexical's
NodeSelection.insertNodesinserts after the selected node and then removes it.
ParaMarkerPrefixGuardPluginthen sees a paragraph with no glyph and resets it to\p. - Repro:
\p \v 1 first/\li2 \v 2 second…. Click the\li2glyph, then call:insertMarker("wj")→{marker:"p", content:[{char wj}," ",{verse 2},…]}insertMarker("v")→\pwith a duplicated\v 2insertMarker("c")→ an empty\li2, then\c 2, then a\pholding v2applyMarkerMenuSelection({kind:"char", marker:"nd"})→ demoted to\pinsertMarker("q1")changes only the glyph text, so the screen and the USJ disagreeinsertNoteandinsertMarker("f")silently do nothing
- A user can reach it today, in core
mainwith no new host code:- The
CharacterMarkerBarrenders only whenviewOptions.hasGutterParaMarkersis set. - Its items call
editorRef.current?.insertMarker(marker)whenselectionState === undefined
(character-marker-menu.utils.ts:250). - A marker selection makes
getSelection()undefined, and soselectionStatetoo. - This PR's
onStateChangereportsblockMarker: "li2", which enables the bar. - So: click a gutter glyph, then pick
\wjin the bar, and the paragraph is demoted.
- The
- The PR's release-order note only covers
formatPara, so it doesn't protect this path. - Fix (either):
- Narrow the
getUsjMarkerActionfallback to$isRangeSelection. - Or, better (see item 14), have every
EditorRefmutator other thanformatParacollapse a
marker selection to the paragraph's content start ($advancePastParaPrefixes), or refuse
with alogger.warn, before it runs.
- Narrow the
- 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 wayOpaqueBlockGuardPluginalready 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
NodeSelectionand never commits
the browser's range. - Typing "x" then lands at the start of the selected
\li2paragraph, 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, andonSelectionChangefires with that caret. - The click then selects the marker.
$resolvePositionignores 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, leavingnull. - 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 wideningParaMarkerRefusedIntentbeyond 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
\li2marker into\ptext.onSelectionChangereceives the new
caret, butgetSelectedParaMarker()still returns"li2", and nothing corrects it later. A host
would show\li2in its paragraph control whileformatPararetags\p. - API shape (worth settling before it ships):
- A bare
stringcan't say which paragraph (two\li2s look the same). Widening it later is a
breaking change, so consider{ marker, location } | undefinednow. - A push signal for "marker selected vs. caret" would spare hosts from polling.
onStateChange's
blockMarkercan't tell the two apart.
- A bare
- 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.
$moveCaretToVerseStartreads 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
$guardCursorOnClicknow returns early for
glyph targets (:119). - Repro: read-only editor, click the
\li2glyph.- With this PR:
getSelection()={jsonPath:"$.content[3]", offset:0}. - With main's line restored:
{jsonPath:"$.content[3].content[1]", offset:0}.
- With this PR:
- 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 \):
isEditingKeytreats 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 aNodeSelection, and no browser caret exists. - Non-BMP keys (emoji, Adlam) aren't recognised as typing.
- Fix: collapse on
beforeinputrather 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.tsxandparaMarkerSelectionArms.test.tsx
guard against the marker-edit engine's settle clock and delete arms.MarkerEditPluginnever
registers in this view (markerModeis"hidden", gated atMarkerEditPlugin.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. $selectParaMarkeritself (inshared) 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.
- Creating the selection and protecting it are tied together only by a module-level registry and
- Consumers. Each one special-cases the selection by hand, and they've already drifted:
- The consumers are
StateChangePlugin:55,ActiveTextPlugin:151, :205,
ScriptureReferencePlugin:398andEditor.tsx:634, :717. StateChangePluginduplicates its snapshot emission.ScriptureReferencePluginopts out of the marker selection, whileActiveTextPlugintreats it
as a caret at the content start.
- The consumers are
- Refusals. They're a blocklist of commands, and items 1–3 and 5–6 slip past it.
- Suggestion:
- Move click-to-select into
ParaMarkerSelectionPluginso one plugin creates and protects the
selection. The cursor guard then goes back to one rule and needs no registry. - Put the registry beside
$selectParaMarkerinsharedand 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).
- Move click-to-select into
- 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-activedescendantpoints 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 notonParaMarkerMenuRequestis 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 noonSelectionChange", 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
NodeSelectionon an orphaned
glyph. Typing, Enter, Escape andfocus()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()andonStateChangekeep reporting the marker.- Ctrl+C is still refused.
removeDomRangesInsidewipes 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:193refuses 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
$findPreviousCaretParaskips theBookNode, so ← is claimed and nothing happens. The\idtext
was reachable by ← before this PR.- → from the end of the
\idline doesn't stop on the first marker either. So the "mirror" claim
doesn't hold here. - The tests at
ArrowNavigationPlugin.test.tsx:2761, :2775say "nothing before it takes a caret".
Their own fixture has caret-able\idtext, 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$selectParaEnduses 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
4emfallback in thebox-shadowoffset 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.ArrowNavigationPluginand$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:299now reads "arrow
navigation is the only caller; exported … forParaMarkerSelectionPlugin". 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:680is a 139-character line with a sentence spliced into the middle of it.paraMarkerSelectionOwner.ts:10lists only some of the refusals, and says "never exists" although
$selectParaMarkeris public.- The
paraMarkerSelectionIdletest 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.startsWiththrows on a keydown with nokey(some autofill and synthetic events).
That happens before Lexical's own guard and leaves an update pending. Useevent.key?..- The
instanceof Event/instanceof Nodechecks 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. setActiveDescendantremoves the root'saria-activedescendanton 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)
intosharednext to$getSelectableParaMarker. - Forward stop: it's decided in two places (
$stopAtNextParaMarkerand the note hop at
ArrowNavigationPlugin.tsx:1018-1027). - Marker-to-paragraph lookup: it's repeated at 8 sites with 4 different guards.
- Other cleanup:
$selectParaContentStarthas an unreachable fallback, and its name clashes with a different
platform helper.- Five exports have no users outside their own file.
ParaMarkerSelectionPluginimports 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-600ArrowNavigationPlugin.test.tsx:2738, 2780, 2808, 2942, 2966
- Priority type.
ParaMarkerPrefixCursorGuardPlugin.test.tsx:661types a priority as0 | 1.
Use Lexical'sCommandListenerPriority. nullvsundefined.nullis used whereundefinedworks:$getSelectedParaMarker(selection: BaseSelection | null)forcesselection ?? nullat
ActiveTextPlugin.tsx:205.$siblingOfreturnsLexicalNode | null(:347).- The test helper
activeDescendantreturnsnull(…test.tsx:59-61). It also lets the
assertions at :125 and :148 pass vacuously when both sides arenull.
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
onParaMarkerMenuRequestforwarding: it reaches<Editor>through bothMarginaland
Editorial, which spread their props.formatParaon a selected marker: it keeps the glyph's key, the paragraph's attributes, and
undo behaviour.- Host callback timing:
queueMicrotaskinrequestMenudoesn'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. StateChangePluginearly branch: it mirrors the normal branch, including the
getElementByKeyguard.- 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:
getUsjMarkerActionfalls back toselection?.insertNodes([node])for any selection
that isn't a range (adaptors/usj-marker-action.utils.ts:503-505). Lexical's
NodeSelection.insertNodesinserts after the selected node and then removes it.
ParaMarkerPrefixGuardPluginthen sees a paragraph with no glyph and resets it to\p. - Repro:
\p \v 1 first/\li2 \v 2 second…. Click the\li2glyph, then call:insertMarker("wj")→{marker:"p", content:[{char wj}," ",{verse 2},…]}insertMarker("v")→\pwith a duplicated\v 2insertMarker("c")→ an empty\li2, then\c 2, then a\pholding v2applyMarkerMenuSelection({kind:"char", marker:"nd"})→ demoted to\pinsertMarker("q1")changes only the glyph text, so the screen and the USJ disagreeinsertNoteandinsertMarker("f")silently do nothing
- A user can reach it today, in core
mainwith no new host code:- The
CharacterMarkerBarrenders only whenviewOptions.hasGutterParaMarkersis set. - Its items call
editorRef.current?.insertMarker(marker)whenselectionState === undefined
(character-marker-menu.utils.ts:250). - A marker selection makes
getSelection()undefined, and soselectionStatetoo. - This PR's
onStateChangereportsblockMarker: "li2", which enables the bar. - So: click a gutter glyph, then pick
\wjin the bar, and the paragraph is demoted.
- The
- The PR's release-order note only covers
formatPara, so it doesn't protect this path. - Fix (either):
- Narrow the
getUsjMarkerActionfallback to$isRangeSelection. - Or, better (see item 14), have every
EditorRefmutator other thanformatParacollapse a
marker selection to the paragraph's content start ($advancePastParaPrefixes), or refuse
with alogger.warn, before it runs.
- Narrow the
- Test: add a regression test that selects a marker and calls each mutator.
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>
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>
|
@katherinejensen00 Round 3 is addressed in 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. Merging mainMain had moved 4 commits, with conflicts in 12 files:
I re-tested marker selection against the two main changes that touch the same code:
High
Medium
Low
Not numbered, but noted: the update listener's eten-tech-foundation/scripture-editors#548That 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.
Still open before merge
🤖 Generated with Claude Code |
katherinejensen00
left a comment
There was a problem hiding this comment.
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:complete! all files reviewed, all discussions resolved (waiting on jolierabideau).
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
left a comment
There was a problem hiding this comment.
@katherinejensen00 reviewed 9 files and all commit messages.
Reviewable status: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>
…" 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>
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: 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>
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.
NodeSelectionof 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 whereParaMarkerSelectionPluginis mounted.psc-para-marker-selected), and the root'saria-activedescendantnames the glyph, which carriesrole="option"andaria-selected.insertMarker,insertNote,applyMarkerMenuSelectionand the typed-marker commits act there.onParaMarkerMenuRequestwhen it is set. Without it, Enter splits at that position and Alt+↓ acts like any other arrow."protected"structure. Under"guarded", selecting the marker is the arming step, so one press merges.formatPararetags the selected paragraph in place and keeps it selected.StateChangePluginandActiveTextPluginreport the owning paragraph.EditorRef.focus()returns focus to the editor.\p.\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.EditorRef.getSelectedParaMarker()andEditorProps.onParaMarkerMenuRequest. Every marker selection firesonSelectionChange(undefined), andgetSelection()returnsundefinedfor 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
restoreSelectionIfLostchange. Otherwise the toolbar dropdown retags the wrong paragraph after a gutter click. The Character Marker Bar path no longer depends on that, becauseinsertMarkernow collapses a marker selection first.Open before merge: manual and VoiceOver QA (including whether axe's
aria-required-parentflag onrole="option"without alistboxmatters 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