Skip to content

PT-4121: Keep paragraph markers when the structure is locked - #30

Merged
timothy-mccormack merged 10 commits into
mainfrom
pt-4121-locked-marker-test
Oct 27, 2026
Merged

timothy-mccormack merged 10 commits into
mainfrom
pt-4121-locked-marker-test

Conversation

@timothy-mccormack

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

Copy link
Copy Markdown
Contributor

With the paragraph structure locked (structureProtectionMode: "protected", Simple mode), a paragraph's marker could still be deleted. PT-4540 (#22) fixed most of this: in the gutter view it restores a paragraph's glyph whenever it goes missing. This PR closes the remaining holes in the lock.

Word and line deletes: Cmd+Backspace, Alt/Ctrl+Backspace and macOS Ctrl+K extend the selection before removing it, so the keydown check, which only sees the caret, never judged what they removed:

  • Cmd+Backspace on a line that starts with a verse 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. At the end of the \id line it deleted \c 1, or merged \h into the \id line.

Under protection, StructureKeyboardPlugin now handles DELETE_WORD_COMMAND/DELETE_LINE_COMMAND itself, following the \id line's $clampLineDeletionPastBookPrefix: it judges the caret, extends once, judges that range, and deletes exactly it or refuses. It doesn't hand back to Lexical's own deleteLine, which would extend a second time from a re-seated caret. Before removing a range it narrows it past the display glyphs it starts in front of (the \id prefix, a line's gutter glyph).

It refuses:

  • a range made of nothing but glyphs, which would otherwise be deleted and rebuilt with an empty undo step;
  • a range that ends partway into an opaque block. This is defense in depth: OpaqueBlockGuardPlugin sees only the caret, but in the paragraph-structure view hidden constructs aren't rendered, so an extension can't actually land inside one there.

Where a line extension finds nothing to extend into (a line that ends in a hidden figure), it extends one character and judges that range too, so the line can't merge into the next. A refusal leaves both ends of the selection where they were.

On the \id line the handler judges the caret and then hands on: a line delete to $clampLineDeletionPastBookPrefix, a word delete to Lexical's own.

Forward delete in front of a line's glyph (where ArrowRight from the line before leaves the caret): $shouldBlockStructuralEdit judges it from just past the glyph. Every caller therefore agrees: the keydown check, the character-delete handler, the hidden-content guard and MarkerEditPlugin.

  • Text follows the glyph: it deletes the line's first character on the first press. It used to remove the glyph, which was rebuilt with an empty undo step.
  • A display-only node follows: a verse marker, a milestone or a hidden figure would otherwise be deleted unseen, so it is refused.
  • An empty line: refused, since it would merge the next line.

Smaller fixes:

  • A range that covers a chapter marker now counts as crossing a block. That refuses delete, paste, cut, drop and typing over it, not only deletes.
  • Backspace at the start of a glyph-led first block is refused, rather than deleting and rebuilding the glyph.

Interaction with HiddenContentDeleteGuardPlugin (from main, #27): that guard runs ahead of the lock and assumed the lock had no word or line handler. Under "protected":

  • It steps aside wherever the lock refuses. That's judged from the caret (glyph-aware, as above) for every delete, and by the browser's measured extent for a word or line delete, using the same $shouldRefuseExtendedDelete the lock uses. The lock then refuses before the host is asked.
  • One exception keeps PT-4703: Ask before an edit removes content the view does not show #27's behavior: an extent that only leaves the line, with hidden content right at the caret, is still asked about. That delete stops at the line's edge and removes only hidden content, never markers.
  • A confirmed line delete is narrowed past the line's glyph, so the glyph isn't deleted and rebuilt.

Unlocked ("guarded") and "off" behavior is unchanged, including what a cut copies.

Testing

  • protectedParaMarker.test.tsx runs 34 cases on the real <Editor> in the locked paragraph-structure view. The refusal cases press twice and assert the same USJ, the same glyph node, both ends of the selection unmoved, and no undo step.
  • shared-react has its own cases for these rules: guard steps-aside, the unlocked cut, the glyph and extent rules, and the chapter rule. nx test shared-react alone covers them.
  • jsdom has no Selection.modify, so the word and line cases stub RangeSelection.modify with where Chromium's extension lands. The stub asserts the alter, direction and granularity it is called with.
  • Each behavior rule has a test that fails when it is reverted. That was checked by mutating each one, including the chapter rule, the extension arguments, the guard's step-asides and the exception, the caret move before extending, the unlocked cut, the display-only refusal, and the one-character fallback.
  • Full test, lint and typecheck pass for shared, shared-react, platform-editor and utilities. dist is rebuilt with rebuild-committed-output.mjs.
  • Manual check in Platform.Bible (Simple mode, Paragraph Structure view, structure protected, Psalm 1), on 65559897:
    • Refused, with no change and no undo step: Ctrl+K at a line's end, before \c, and at the end of the \id line; Cmd+Backspace on a verse-led line.
    • Allowed, with the marker kept: Delete in front of a line's glyph removes the text's first character on the first press; Cmd+Backspace mid-line on a \q2 removes back to the text's start, and a second press is refused.

Known gaps, not addressed here (all pre-existing, or ticketed):

  • Under "guarded", a word or line delete still removes a verse marker or merges paragraphs in one press, with no arming step.
  • A collapsed caret at a root-level point next to a chapter (reachable with arrow keys) lets Delete or Backspace remove the chapter marker.
  • Enter over a range, a virtual-keyboard Enter, and an IME commit ending in a newline can still split a paragraph.
  • REMOVE_TEXT_COMMAND (e.g. Safari IME reconversion) over a cross-paragraph range is not judged.
  • A range spanning a root-level block other than a chapter (a table, an opaque block) still counts as one paragraph.
  • A verse followed by a character-style run (\v 16 \wj …) isn't recognised as adjacent to the caret, so Backspace there can delete the verse.
  • On a line whose text starts with a character style (\q2 \wj …), a refused glyph-only word or line delete collapses the selection instead of restoring it.
  • Delete at (para, 1), just past a glyph and in front of a milestone, still removes the milestone.
  • Plain Backspace or Delete over a glyph-only range still rebuilds the glyph with an undo step.
  • The hidden-content exception above removes every hidden node up to the line's edge, which can include one from the previous verse. main does the same.
  • Cmd+Backspace on a verse-led line is refused outright, rather than deleting back to just after the verse.
  • When a delete arrives through beforeinput and is refused, the target range the browser applied stays selected.
  • In Platform.Bible's Simple mode, Option+Backspace right after a figure removes it without the hidden-content question. This reproduces with scripture-editors main in the app, but not in a plain browser on either branch.

🤖 Generated with Claude Code


This change is Reviewable

@timothy-mccormack timothy-mccormack left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Review findings from a /code-review pass. Inline comments are tagged:

  • Blocking (3): a forward-delete regression at (para, 0); Ctrl+K / word delete at the end of the \id line deleting \c 1 or merging \h; and tests that never reach the new chapter clause.
  • Should fix in this PR (4): the modify stub ignoring its arguments, the non-collapsed branch skipping glyph narrowing, a latent HIGH-priority tie, and missing calling-context TSDoc.

Older gaps found along the way (a collapsed caret beside a chapter, Enter/IME splitting under the lock, "guarded" line/word deletes, REMOVE_TEXT_COMMAND) were not introduced here and will be tracked separately.

🤖 Generated with Claude Code

@timothy-mccormack
timothy-mccormack marked this pull request as ready for review October 24, 2026 22:26

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

@irahopkinson+AI made 7 comments and resolved 7 discussions.
Reviewable status: 0 of 6 files reviewed, all discussions resolved.

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

@irahopkinson+AI made 8 comments.
Reviewable status: 0 of 6 files reviewed, 7 unresolved discussions (waiting on timothy-mccormack).


a discussion (no related file):
A review of the locked paragraph-marker changes at the current head, with 8 findings. Each comment shows the severity it settled at; "checked and confirmed" means the finding was verified against the code, and "needs a human call" means it could not be settled either way and is yours to judge. Several findings sit in HiddenContentDeleteGuardPlugin, where the guard paths fixed earlier in StructureKeyboardPlugin have counterparts that still behave the old way.

(AI-assisted, with my guidance)


libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx line 357 at r2 (raw file):

      // one that reaches a verse or another block; asking first would remove that range on
      // "delete" without its say.
      if (extent?.range && structureProtectionModeRef.current === "protected") {

#1 - high · checked and confirmed

On a locked line that starts with a verse and holds a hidden figure, Cmd+Backspace mid-line shows the host's "delete hidden content?" question, and answering "delete" removes the figure, although the lock refuses that gesture.

What happens: $onKeyDown (HiddenContentDeleteGuardPlugin.tsx:441) calls $holdCaretDelete at CRITICAL priority. In Chrome, $deleteExtent's probe lands in the previous paragraph, so $isInCaretContainer is false and it returns { hidden } with no range (:704-705). The lock check only runs if (extent?.range && …) (:357), so it is skipped. $hold asks the host, and on "delete" $removeHidden removes the figure (:383).

Why it matters: This is the Chrome measurement the PR targets (test :469). The lock is supposed to refuse before the question is asked, as the test at :536 asserts, but here the question appears and content is removed.

Fix: In $deleteExtent (HiddenContentDeleteGuardPlugin.tsx:704-705), add a leftContainer: true field to the returned DeleteExtent when !$isInCaretContainer(probe.focus, selection). In $holdCaretDelete (:357), return false when structureProtectionModeRef.current === "protected" and extent?.leftContainer is set, in addition to the existing extent?.range check, so the lock refuses before $hold asks the host (the refusal must leave the document and undo stack unchanged). Add a test to packages/platform/src/editor/protectedParaMarker.test.tsx, modelled on the test at :536 (verse and hidden figure in q1, host answering "delete"), that lands a lineboundary extension at the end of the s1 text, dispatches DELETE_LINE_COMMAND backward, and asserts the USJ is unchanged and the host handler was not called. Then rebuild the committed dist with node scripts/rebuild-committed-output.mjs.

How this was checked: When the line extension leaves the caret's paragraph, $deleteExtent returns { hidden: $hiddenNodesToParaEdge(...) } with no range (HiddenContentDeleteGuardPlugin.tsx:704-705), so the lock check at :357 (if (extent?.range && ...)) is skipped. The caret-position check in $onKeyDown (:449-452) does not fire mid-line, so $hold asks the host and "delete" runs $removeHidden (:381-383). The existing tests do not cover this shape: the test at :469 has no hidden figure (hidden is empty, so the guard returns false and the lock refuses), and the test at :536 lands the extension in q1 with a range. I ran a probe with the :536 fixture (verse + figure in q1, host answering "delete") but a lineboundary extension landing at the end of s1 and DELETE_LINE_COMMAND backward; expectRefused failed because the figure was removed from the saved USJ.

Other findings in this file: #3, #4


#3 - low · checked and confirmed

When the host provides onHiddenContentDelete, a locked word delete whose reach lands inside a figure's caption is asked about and carried out, instead of being refused as it is without a handler.

What happens: The lock check in $holdCaretDelete judges the extent only with $shouldBlockStructuralEdit(range, intent) (HiddenContentDeleteGuardPlugin.tsx:360). It does not apply the opaque-block refusal that $guardExtendingDelete adds (StructureKeyboardPlugin.tsx:332), and $selectionReachesIntoOpaqueBlock reads only $getSelection(), so it cannot be asked about range. The extent stays in the paragraph, $hold asks, and on "delete" $removeRange and $removeHidden run (:382-383).

Why it matters: The same keystroke behaves differently depending on whether the host wired a handler (test :502 covers only the no-handler case), and the cost is a confirmed deletion of the figure.

Fix: Export a range-taking $rangeReachesIntoOpaqueBlock(range) from OpaqueBlockGuardPlugin.tsx, with TSDoc stating its calling context, and call it next to $shouldBlockStructuralEdit at :360. Add a with-handler test in protectedParaMarker.test.tsx and rebuild the committed dist.

How this was checked: I added a with-handler twin of the caption test at protectedParaMarker.test.tsx:502 (handler answering "delete", same figure document, same stubbed word extension landing in the caption) and ran it. The handler was called once and the saved USJ came back as Before after, so the figure and its caption were removed. Without a handler the same keystroke is refused (:502 test). The cause is at HiddenContentDeleteGuardPlugin.tsx:357-361, which judges the extent only with $shouldBlockStructuralEdit. $guardExtendingDelete in StructureKeyboardPlugin.tsx:332 also applies $selectionReachesIntoOpaqueBlock, which reads only $getSelection() (OpaqueBlockGuardPlugin.tsx:204-211) and cannot judge the measured range. The anchor lines were added by this PR (git diff shows them as insertions). Severity stays low because it needs a host that wires onHiddenContentDelete, a locked editor, and a word or line delete whose reach ends inside a caption, but the result is a confirmed loss of the figure.

Other findings in this file: #1, #4


libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx line 730 at r2 (raw file):

 * plugin narrow an edit's range, for an edit that acts on it before they do.
 */
function $narrowEditRange(selection: RangeSelection): void {

This comment is about the code on this line, which this pull request does not change.

#4 - low · checked and confirmed

Confirming "delete" for a Cmd+Backspace mid-line on a line with no verse that holds a hidden figure deletes the line's gutter glyph and rebuilds it as a new node.

What happens: The measured extent starts at (para, 0), in front of the glyph, and the lock check allows it (one paragraph, no verse). On "delete", $removeRange narrows only through $narrowEditRange ($narrowSelectionPastBookPrefix, $confineRangeToProtectedNote, HiddenContentDeleteGuardPlugin.tsx:730-733), so removeText takes the glyph and ParaMarkerPrefixGuardPlugin restores it as a new node.

Why it matters: The marker survives, but the glyph is deleted and rebuilt, which the PR's own tests pin as a defect (they assert the same glyph node), and the undo step carries the churn.

Fix: In $narrowEditRange, also call $narrowSelectionPastGutterGlyph(selection) from structureKeyboard.utils.ts. Add a test in protectedParaMarker.test.tsx asserting glyphKeyOf is unchanged after a confirmed delete, and rebuild the committed dist.

How this was checked: Ran a probe in the protected-structure test harness: a q2 line with no verse and a hidden figure, caret mid-line, line-delete extension landing at (para, 0), host answering "delete". The confirmation prompt fired once and the gutter glyph's node key changed afterward (glyph same false), so the glyph was deleted and rebuilt. On "delete", $holdCaretDelete runs $removeRange (HiddenContentDeleteGuardPlugin.tsx:382,717), which narrows only through $narrowEditRange (:730-733: book prefix and protected note). Nothing there moves the start point past the glyph, unlike the guard path at StructureKeyboardPlugin.tsx:337. The paragraph markers survive, so the cost is node churn and a heavier undo step, not data loss. The lines at :730-733 are not changed by this PR.

Other findings in this file: #1, #3


packages/platform/src/editor/protectedParaMarker.test.tsx line 602 at r2 (raw file):

  });

  it("Delete in front of a line's glyph deletes the text's first character", async () => {

#10 - low · checked and confirmed

No test covers a forward Delete or a forward character delete with the caret in front of the glyph of a verse-led line, so a regression that lets Delete remove the verse under the lock would pass the suite.

What happens: $movePointPastGutterGlyph places the caret with $caretHostAtBoundary(para, 1) (structureKeyboard.utils.ts:153-155). On a verse-led line that gives (para, 1, element) before an ImmutableVerseNode, and the refusal then depends on $caretAdjacentToVerseMarker reading children[1]. The forward tests (protectedParaMarker.test.tsx:602, :629) use only q2, which has no verse, and :376 uses an empty line.

Why it matters: Test-only, with no behavior effect today; a change to the caret-host rule could let Delete remove a verse under the lock unnoticed.

Fix: In packages/platform/src/editor/protectedParaMarker.test.tsx, next to "a forward delete in front of an empty line's glyph", add two expectRefused(mounted, "q1", ...) cases with mountLocked() and the caret placed by update(mounted.lexical, () => { $paraOf("q1").select(0, 0); }). One uses pressKey(mounted.lexical, "Delete") and the other dispatch(mounted.lexical, DELETE_CHARACTER_COMMAND, false). Each must fail if the forward $caretAdjacentToVerseMarker term in $shouldBlockStructuralEdit (structureKeyboard.utils.ts) is removed. A forward DELETE_WORD_COMMAND case is optional and does not pin this rule.

How this was checked: The forward tests at protectedParaMarker.test.tsx:602 and :629 use only the verse-free q2, and :376 uses an empty line. On a verse-led line, $movePointPastGutterGlyph (structureKeyboard.utils.ts:149-157) moves the caret to (para, 1) before the verse, and refusal then rests on $caretAdjacentToVerseMarker(selection, "forward") at structureKeyboard.utils.ts:332-335. I mutated that call to false in a scratch worktree and the whole existing file still passed (23 of 23). Probe tests with the caret at (q1, 0), using pressKey "Delete" and DELETE_CHARACTER_COMMAND forward, pass on the unmodified code and fail under the mutation, so the gap is real and those two cases close it. A forward DELETE_WORD_COMMAND at (q1, 0) passed under the mutation too, because the extended range containing the verse is refused by Rule 1, so it does not pin this rule.


libs/shared-react/src/plugins/usj/structureKeyboard.utils.ts line 307 at r2 (raw file):

}

/**

This comment is about the code on this line, which this pull request does not change.

#9 - low · checked and confirmed

The TSDoc of $shouldBlockStructuralEdit does not state its calling context, although this PR edits its deleteBackward rule and adds a call that passes it a range that is not the current selection.

What happens: CLAUDE.md, Code Style: "Every exported $-prefixed function must document its calling context in its TSDoc." $shouldBlockStructuralEdit (structureKeyboard.utils.ts:314) is exported and its TSDoc (:307-313) has no Read-only or Mutating line. The PR edits its deleteBackward rule (:323-327), and HiddenContentDeleteGuardPlugin.tsx:360 now calls it on a $rangeFrom range.

Why it matters: Maintenance only: a caller has to read the body to learn that the function is a pure read and safe on a detached range.

Fix: Add a line to the TSDoc of $shouldBlockStructuralEdit in libs/shared-react/src/plugins/usj/structureKeyboard.utils.ts: "Read-only: safe in any read (editor.getEditorState().read(), an editor.update(), or a command handler); accepts a selection that is not the current one, such as one built with $rangeFrom." Add the same Read-only line to $shouldBlockSelectionReplacement just above it. Then run node scripts/rebuild-committed-output.mjs so the committed packages/platform/dist matches.

How this was checked: The TSDoc of $shouldBlockStructuralEdit (structureKeyboard.utils.ts:307-313) has only a summary, @param and @returns, with no Read-only or Mutating line, while CLAUDE.md:270 requires every exported $-prefixed function to state its calling context. The omission predates the PR (the base TSDoc is identical), but the PR edits the function's body (new gutter-glyph clause in the deleteBackward case, :323-327) and adds a caller, HiddenContentDeleteGuardPlugin.tsx:360, that passes a $rangeFrom range instead of the current selection. The PR's other new or edited helpers in the same file ($selectionSpansBlockBoundary, $narrowSelectionPastGutterGlyph, $moveCaretPastGutterGlyph) do carry the context line, so this one is the outlier. The anchor lines are unchanged by the PR. Impact is maintenance only.


libs/shared-react/src/plugins/usj/StructureKeyboardPlugin.tsx line 56 at r2 (raw file):

 * Mutating (the returned function): call inside `editor.update()`.
 */
function $snapshotRange(selection: RangeSelection): () => void {

#6 - low · checked and confirmed

The new $snapshotRange re-implements the endpoint copy that $rangeSnapshot in HiddenContentDeleteGuardPlugin.tsx already performs, so a change to how selection points are snapshotted must be made in two places.

What happens: $snapshotRange copies {key, offset, type} for anchor and focus and sets them back (StructureKeyboardPlugin.tsx:56-63). HiddenContentDeleteGuardPlugin.tsx:749-767 already has $rangeSnapshot and $rangeFrom for the same job, built on PointSnapshot from structureKeyboard.utils.ts:49.

Why it matters: Maintenance only, with no behavior effect: a change to point snapshot semantics has to be made in two places.

Fix: Move $rangeSnapshot and the RangeSnapshot interface from HiddenContentDeleteGuardPlugin.tsx into structureKeyboard.utils.ts (next to PointSnapshot), export them, and document $rangeSnapshot as "Read-only: safe inside editor.read() or editor.update()". Rewrite $snapshotRange in StructureKeyboardPlugin.tsx to call $rangeSnapshot(selection) and restore with selection.anchor.set(...) / selection.focus.set(...) from the returned snapshot, keeping its in-place restore (do not substitute $rangeFrom, which creates a new range and drops invalid points). Then run node scripts/rebuild-committed-output.mjs so the committed packages/platform/dist matches.

How this was checked: $snapshotRange is new in this PR (StructureKeyboardPlugin.tsx:56-63, called at :276 and :313). Its snapshot half copies {key, offset, type} for anchor and focus, exactly what the private $rangeSnapshot at HiddenContentDeleteGuardPlugin.tsx:749-752 already does with the shared PointSnapshot type (structureKeyboard.utils.ts:49). The restore half is not a duplicate of $rangeFrom (:755-766): that builds a new, validity-checked RangeSelection, whereas $snapshotRange re-sets the live selection's points in place, so only the snapshot copy is genuinely duplicated. Maintenance-only, no behavior effect.

Other findings in this file: #2, #7


libs/shared-react/src/plugins/usj/StructureKeyboardPlugin.tsx line 274 at r2 (raw file):

        // forward delete is judged — and, if allowed, run by Lexical's own handler — from just past
        // it, so it removes the line's first character instead of the glyph.
        let restore: (() => void) | undefined;

#2 - medium · checked and confirmed

Pressing Delete in front of a locked line's glyph, when the line's content starts with a hidden figure, removes the figure without the hidden-content question.

What happens: HiddenContentDeleteGuardPlugin's delete handler (CRITICAL, :447) judges the caret at (para, 0); $hiddenRunAtCaret meets the gutter glyph first and finds no hidden run. Only afterwards does $handleDeleteCharacter call $moveCaretPastGutterGlyph (StructureKeyboardPlugin.tsx:277), which sets (para, 1, element) because UnknownNode is an inline ElementNode with no text host (structureKeyboard.utils.ts:153-155). The handler returns false, and Lexical's deleteCharacter then deletes forward across the figure.

Why it matters: Hidden content is removed silently on any \p \fig… line reached with ArrowRight from the line before.

Fix: Make HiddenContentDeleteGuardPlugin judge a forward delete from the caret as it will be deleted from: $hiddenRunAtCaret (hiddenContentDelete.utils.ts:63) must treat a caret at (para, 0) in front of the paragraph's gutter glyph as sitting just past the glyph, for the Delete keydown path ($onKeyDown, :430-445) and the DELETE_CHARACTER_COMMAND path (onDelete, :447-459) alike. The fix must not move the caret before the hold in a way that a refused or "keep" answer leaves displaced, and must leave Backspace behavior unchanged. Add a test to packages/platform/src/editor/protectedParaMarker.test.tsx (a \q2 line starting with a figure, caret at (para, 0), Delete: the host question is asked and a "keep" answer leaves the figure in place), and rebuild the committed packages/platform/dist with node scripts/rebuild-committed-output.mjs. Any new or changed exported $-prefixed helper needs its calling context in TSDoc.

How this was checked: I ran a probe on the real platform Editor in the locked gutter view: a \q2 line whose content starts with a figure, caret at (para, 0), Delete pressed, host handler set to answer "keep". The handler was called 0 times; the guard saw the caret at (para,0:element), and at the extension step the caret was already (para,1,element), i.e. past the glyph and directly before the figure; the figure was gone from the saved content. $hiddenRunAtCaret (hiddenContentDelete.utils.ts:63) starts from the gutter glyph, which is neither an UnknownNode nor empty text, so it finds no run; the caret is only moved past the glyph afterwards by $moveCaretPastGutterGlyph (StructureKeyboardPlugin.tsx:277, structureKeyboard.utils.ts:149-155). The forward move is new in this PR (git show 7bd11cf9:structureKeyboard.utils.ts has no gutter-glyph helper): at base the same Delete removed the glyph, which is rebuilt, and left the figure intact, so this PR introduces the silent figure removal.

Other findings in this file: #6, #7


libs/shared-react/src/plugins/usj/StructureKeyboardPlugin.tsx line 322 at r2 (raw file):

          }
          if ($findMatchingParent(selection.anchor.getNode(), $isBookNode)) return false;
          selection.modify("extend", isBackward, granularity);

#7 - low · checked and confirmed

A word or line delete in protected mode measures its extent through the browser twice when the cursor is not next to hidden content, once to look for hidden content and again to decide what to remove.

What happens: $deleteExtent clones the caret and runs probe.modify("extend", …) (HiddenContentDeleteGuardPlugin.tsx:696). When nothing is hidden it returns false, and $guardExtendingDelete then runs selection.modify("extend", …) again (StructureKeyboardPlugin.tsx:322) — the double extension the comment at :293-295 warns against.

Why it matters: One extra forced layout per word or line delete, and the two measurements agree only because they start from the same points. Mostly maintenance.

Fix: Recommended: keep the two measurements and fix the comment at StructureKeyboardPlugin.tsx:293-295 to say that the one-extension rule applies within $guardExtendingDelete only, and that $deleteExtent (HiddenContentDeleteGuardPlugin.tsx:696) has already measured the same extent from the same caret when no hidden content was found, so the repeat is deliberate. Avoid adding a shared cache of the measured extent: any such cache must be cleared at the end of every keystroke's update and must not be consulted for a selection whose points differ from the cached ones. The comment must not contain Jira IDs or task labels. Any source change in libs/shared-react requires rebuilding the committed output with node scripts/rebuild-committed-output.mjs.

How this was checked: For a collapsed-caret word or line delete in protected mode, HiddenContentDeleteGuardPlugin's $holdCaretDelete (HiddenContentDeleteGuardPlugin.tsx:342-353) calls $deleteExtent, which clones the selection and runs probe.modify("extend", ...) (:696) on the browser selection. When no hidden content is found it returns false (:359), the command falls through, and $guardExtendingDelete runs selection.modify("extend", isBackward, granularity) (StructureKeyboardPlugin.tsx:322) again; the line is added by this PR (the function did not exist at the merge base). Both measurements start from the same caret (selection.dirty = true at HiddenContentDeleteGuardPlugin.tsx:698 re-seats the live selection), so they agree. The cost is one extra forced layout per word or line delete, plus a comment (:293-295) about extending once that is only true within $guardExtendingDelete. Maintenance and minor performance only.

Other findings in this file: #2, #6

@timothy-mccormack

Copy link
Copy Markdown
Contributor Author

All 8 findings are addressed in 29c27840 and 65559897. Each one has a test that fails without its fix. The shared, shared-react, platform-editor and utilities suites, typecheck and lint all pass, and the committed dist is rebuilt with rebuild-committed-output.mjs.

#1: fixed, with one deliberate exception. Under the lock the guard now judges the browser's full measured extent, not only the part inside the line, and steps aside for the lock's refusal. Your case (Cmd+Backspace mid-line on a verse-led line holding a figure) is refused with no question. Your suggested test is in, as "Cmd+Backspace on a verse-led line holding a hidden figure, even if the host would confirm it".

The exception is #27's tested case, "stops a word delete at the paragraph's edge, taking only the figure there": hidden content sits right at the caret. Alt+Backspace just after a figure that starts a line still asks, and takes only that figure. No structure is lost, and the user is deleting exactly what is next to the caret. Both halves of the condition, extent.range || !run, are pinned: each one fails a test when removed.

#2: fixed. Under the lock, a forward delete is judged from just past the gutter glyph, on a copy of the caret, as the lock runs it. "keep" and refusals leave the caret where it was, and Backspace is unchanged. New test: "Delete in front of a line's glyph asks before removing a hidden figure that starts the line".

#3: fixed. I added $rangeReachesIntoOpaqueBlock(range) and one shared predicate, $shouldRefuseExtendedDelete(extent, intent), which covers structure plus opaque reach. The guard and $guardExtendingDelete both use it, so the two paths can't drift. The caption test now runs with no host and with a host answering "delete".

#4: fixed. $narrowEditRange also calls $narrowSelectionPastGutterGlyph. The test asserts the glyph node is unchanged after a confirmed line delete.

#6: done as suggested. RangeSnapshot and $rangeSnapshot now live in structureKeyboard.utils.ts, and $snapshotRange builds on them, keeping its in-place restore.

#7: comment fixed, no cache. The comment now says the extend-once rule is about $guardExtendingDelete's own measure-then-remove, and that the second measurement after the guard's probe is deliberate.

#9: done. $shouldBlockStructuralEdit and $shouldBlockSelectionReplacement now state that they are read-only, and that the selection need not be the current one.

#10: done. Delete and a forward DELETE_CHARACTER_COMMAND at (q1, 0) are refused. Both fail when the forward $caretAdjacentToVerseMarker term is removed.

🤖 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.

🤖 Claude-generated. This was written by Claude (an AI model), using several AI review passes and an adversarial verification round. A human directed the review and posted it. The findings were checked with probes, but please push back on anything that looks wrong.

Review of PR #30 (head 65559897)

Hi Timothy,

Thanks for this. Extending once, judging that range, and then removing exactly that range or refusing is the right design, and the comments explain why. Several things I checked came out sound:

  • Every refusal path in the new word/line handler restores both ends of the selection.
  • The lock checks for opaque blocks itself, so it doesn't depend on mount order.
  • There is no import cycle.
  • Each new exported $ helper documents its calling context.
  • The chapter rule doesn't break triple-click + Backspace on the line before a \c.
  • A word delete on the \id line can't leave the line in real Chrome.

Ira's earlier findings (on d1f0343a) are addressed. Nothing below repeats them, though items 1, 2 and 4 are side effects of those fixes.

Requested changes: three inline comments

  1. Medium. Under the lock, Delete in front of an empty line's glyph can ask about the hidden sidebar after it, and on "delete" remove it. Main doesn't do this.
  2. Medium. Two of the hidden-content guard's new branches can be removed without any test failing, and the shared-react test files weren't touched.
  3. Medium. The word/line handler's restore() after a caret-check refusal, and the caret move before it, can be removed without any test failing.

How this was checked.

  • Confirmed means reproduced, in one of three ways:
    • jsdom probes on the real locked <Editor>, run against both this branch and main;
    • mutation runs against 295 related tests;
    • Chrome 155, using Selection.modify on the editor's own DOM.
  • Traced means the code was read but not run.
  • About half of the candidate findings were dropped or downgraded in the adversarial pass.

Tests on the PR head:

  • shared-react: 2202 passed.
  • platform-editor: 4100 passed. One unrelated test, blockVersePositions, timed out under load and passes on its own.
  • protectedParaMarker: 28 of 28 passed.

All probes were deleted, and nothing on the branch was changed.


Optional suggestions (Low / Nit)

None of these block the merge. They're suggestions to review: take them, ticket them, or push back as you see fit. Some are paths this PR's new code now reaches but that already misbehaved on main; I've said so where that applies. The numbering continues from the inline comments.

4. Cut leaves out the paragraph label in unlocked modes when a host is set

Low · Confirmed (jsdom, compared with main) · HiddenContentDeleteGuardPlugin.tsx:747

Adding $narrowSelectionPastGutterGlyph to $narrowEditRange (the fix for Ira's #4) also changes what cut puts on the clipboard in "guarded" and "off". That contradicts "Unlocked … behavior is unchanged."

$onCut (:544-553) narrows the live selection in every mode, before it checks for hidden content. Triple-click a \q2 line and cut:

  • Main, any mode: \q2 nor stand….
  • This PR, with onHiddenContentDelete set: nor stand….
  • This PR, without a host: still \q2 nor stand….

Ctrl+C on the same selection still includes the label. A glyph-only cut with a host now writes nothing and isn't prevented. The document ends up the same either way.

Suggestion: pick one of these and update the description.

  • Gate the glyph narrowing to "protected".
  • Keep it in every mode, but move it to the always-on CUT narrowing in ParaMarkerPrefixCursorGuardPlugin, so it doesn't depend on whether a host is set.

5. On a line that starts with a character style, a refused glyph-only delete collapses the selection

Low · Confirmed (jsdom) · structureKeyboard.utils.ts:173

On [glyph, \wj Words…], :173 writes (q2, 1, element), while the range's other end normalizes to (text, 0, text) inside the char node.

  • isCollapsed() compares spellings, so the "nothing but glyphs" check at StructureKeyboardPlugin.tsx:343 misses.
  • removeText() then removes nothing but leaves the selection collapsed instead of restoring it.
  • With a host in "guarded", a cut of the same range writes an empty clipboard.
  • Red-letter \q2 \wj … lines are common.

Suggestion:

  • Decide "nothing left" by what lies between the points, not by how they're spelled. For example, treat the range as empty when its text content is empty and it contains no decorators.
  • Add a \wj case.

6. Delete in front of a glyph now reaches an invisible milestone

Low · Confirmed (jsdom) · structureKeyboard.utils.ts:171

On a \q1 \qt-s |…\* text line ([glyph, MilestoneNode, Text]), Delete at (q1, 0) now moves the caret to (q1, 1, element) and removes the milestone.

  • Nothing changes on screen. The USJ loses \qt-s, which orphans \qt-e, and an undo step is recorded.
  • On main this already happens from (q1, 1). This PR extends it to (q1, 0).
  • A figure-only line with no host behaves the same way: Chrome's character extension crosses the hidden figure into the next line.

Suggestion: move past the glyph only when $caretHostAtBoundary(para, 1) returns a text host; otherwise refuse.

7. Ctrl+K at the end of a line that ends in a hidden figure can still merge the next line

Low · Confirmed in Chrome (the extension); traced (the merge) · StructureKeyboardPlugin.tsx:331

Take \p Some text \fig…\fig* followed by \q1, with no host and the caret at Some text|.

  • The caret check passes, and the lineboundary extension stays collapsed, because the figure is display:none.
  • The fallback, selection.deleteCharacter, then extends one character into the next paragraph and merges it.
  • This is a variant of the "Ctrl+K at a line's end" case the PR fixes. Plain Delete already has the same hole on main.

Suggestion:

  • Extend by "character", judge with $shouldRefuseExtendedDelete, then remove it, the same way as the main path.
  • Or list it as a known gap.

8. Two word-delete stubs land where Chrome never lands

Low · Confirmed in Chrome · protectedParaMarker.test.tsx:491 and :599

Both tests stub a word-back from B|lessed to (q1, 0).

  • Chrome stops at |Blessed (text offset 0), because the verse number renders between zero-width spaces, which form a word boundary.
  • So Alt/Ctrl+Backspace there really deletes "B", and that's allowed.
  • The risky real case is untested: the caret at offset 0, right after a hidden figure that sits next to a verse. That case would also cover item 2.

Suggestion: re-stub to where Chrome lands, and update the "steps back over the verse's span" comments.

9. The figure-caption cases can't happen in the view the lock applies to

Low · Confirmed (CSS and Chrome) · protectedParaMarker.test.tsx:531

In the paragraph-structure view, hidden figures are display:none and non-editable (usj-nodes.css:2213-2216).

  • A word-back over one lands at |Before , not in the caption.
  • The opaque-extent check (Ira's #3) is fine as defense in depth.
  • But the PR description and the comment at StructureKeyboardPlugin.tsx:307-309 present it as fixing something users can do.

Suggestion: call it defense in depth in one line, or name the view where it can happen and test it there.

10. Comment: "keep" can move the caret

Low · HiddenContentDeleteGuardPlugin.tsx:353

"The caret stays where it is if the answer is 'keep'" isn't true when canSkip holds: $keep calls $placeCaretPastHiddenRun, as the test at protectedParaMarker.test.tsx:720 shows.

Suggestion: "…so it is judged from there, on a copy: the live caret moves only if the answer moves it."

11. Comment: the step-aside exception takes more than "just that content"

Low · Confirmed (jsdom) · HiddenContentDeleteGuardPlugin.tsx:367

The exception takes every hidden node up to the paragraph's edge, including across a verse marker.

  • Example: on q1 [\v 2, "Blessed ", FIG1, \v 3, FIG2, "is the man"], Cmd+Backspace at |is asks about both figures. "Delete" then removes FIG1, which belongs to verse 2.
  • This happens identically on main; the exception keeps it rather than adding it.

Suggestion:

  • Reword the comment. The message of commit 65559897 says the same thing.
  • Consider limiting hidden to run.nodes in this branch, or ticket it.

12. The \id-line comment is wrong for word deletes

Low · Traced · StructureKeyboardPlugin.tsx:302

$clampLineDeletionPastBookPrefix is registered only for DELETE_LINE_COMMAND, so a word delete on the \id line goes to Lexical's own deleteWord.

  • In Chrome a word extension can't leave that line except from its very end, which the caret check refuses. So the behavior is fine; only the comment is wrong.
  • The JSDoc at :75-77 ("performs word and line deletes itself") also misses the \id and opaque-block hand-offs.

Suggestion:

  • Say "a line delete goes on to $clampLineDeletionPastBookPrefix, a word delete to Lexical's own".
  • Optionally tighten the 22-line block (:288-309). Keep the note Ira asked for about the deliberate second measurement, but shorten it to one sentence.

13. $handleDeleteCharacter's header comment no longer holds

Low · StructureKeyboardPlugin.tsx:272 (the stale text is at :260-265)

The header says the command "gets the answer that keydown would have". It now judges a forward delete from past the glyph, which $handleKeyDown (:113) doesn't.

Suggestion: add "…except that under "protected" a forward delete in front of a line's glyph is judged from just past it."

14. The chapter rule also changes paste, cut, drop and typing

Low · Traced · structureKeyboard.utils.ts:129

$selectionSpansBlockBoundary feeds $shouldBlockSelectionReplacement. So a range covering \c is now refused for paste, cut, drop and typing over it, not just for deletes. That's reasonable.

Suggestion:

  • Say so in the "Smaller fixes" bullet.
  • Update docs/clipboard-semantics.md:80 to "a range spanning a paragraph boundary or covering a chapter marker, or one containing a verse marker".

15. The PR description is behind the last two commits

Low

  • The hidden-guard paragraph doesn't mention two later changes:
    • the exception from 65559897 (item 11);
    • from 29c27840, that Delete in front of a figure-led line's glyph now asks, and that a confirmed line delete is narrowed past the glyph.
  • "Unlocked … unchanged" isn't true for cut (item 4).
  • "22 cases": the file has 28.
  • "The refusal cases press twice…": the \id case at :452 doesn't use expectRefused and doesn't check the caret.

16. The DeleteExtent.measured doc is wrong, and range and intent are redundant

Nit · HiddenContentDeleteGuardPlugin.tsx:116

  • The doc says range "stops short" when the extension leaves the paragraph. In fact it is absent then (:723).
  • range: otherwise range equals measured, so (extent.range || !run) is really a hidden "stayed in the line" flag. An explicit leavesLine would read better.
  • intent: the intent parameter of $shouldRefuseExtendedDelete is never used in practice, because only non-collapsed ranges reach it.

17. Assertions that can pass vacuously

Nit · protectedParaMarker.test.tsx:328

  • caretOf compares only the focus. An anchor that moved in a range refusal (:433, :466) goes unnoticed.
  • glyphBefore is never checked to be defined. The "keeps the marker" tests (:653, :676, :702, :747) don't assert it the way expectRefused does at :345. "Not deleted and rebuilt" therefore passes as undefined === undefined if the lookup ever breaks.

18. Naming and smaller comment nits

Nit

  • StructureKeyboardPlugin.tsx:58: $snapshotRange returns a restore function, next to $rangeSnapshot, which returns data. A name like $restorerFor would be easier to tell apart.
  • structureKeyboard.utils.ts:369: "Both handlers" should name them (StructureKeyboardPlugin and HiddenContentDeleteGuardPlugin).
  • Repeated rationale: "the glyph would be deleted and rebuilt" appears about four times. Keep it once, on $movePointPastGutterGlyph.
  • structureKeyboard.utils.ts:383: $structuralDeleteTarget still says it is a "Mirror of $shouldBlockStructuralEdit", but it has no counterpart for the new first-block glyph clause.
  • Test helper name: pressKey at protectedParaMarker.test.tsx:282 has the same name as the pressKey in react-test.utils.tsx, which dispatches only KEY_DOWN_COMMAND. Consider pressKeyThroughDom.
  • Test names:
    • :452 also dispatches a word delete.
    • The :359 describe covers the figure-caption cases, which threaten no marker.

19. Follow-up, not for this PR: give the protected-delete verdict one owner

Low · HiddenContentDeleteGuardPlugin.tsx:351

The guard now predicts the lock's decision in about eight places and copies its caret move. Item 1 is what it looks like when those copies drift.

Suggestion: a single $protectedDeleteVerdict(...) in structureKeyboard.utils.ts, which both plugins call. It would own the glyph pre-move, the caret check, the extent rule and the run exception.

Pre-existing, maybe worth tickets:

  • Plain Backspace/Delete over a glyph-only range still rebuilds the glyph with an undo step, while a word or line delete on the same range is now refused.
  • The (para, 1) variants of item 6.
  • The cross-verse figure removal in item 11.

@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 7 files and all commit messages.
Reviewable status: all files reviewed, 10 unresolved discussions (waiting on irahopkinson+AI and timothy-mccormack).

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

@irahopkinson+AI made 7 comments and resolved 7 discussions.
Reviewable status: all files reviewed, 3 unresolved discussions (waiting on timothy-mccormack).


libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx line 357 at r2 (raw file):

Previously, timothy-mccormack wrote…

The exception is #27's tested case, "stops a word delete at the paragraph's edge, taking only the figure there": hidden content sits right at the caret. Alt+Backspace just after a figure that starts a line still asks, and takes only that figure. No structure is lost, and the user is deleting exactly what is next to the caret. Both halves of the condition, extent.range || !run, are pinned: each one fails a test when removed.

Both fixed at 65559897. #1: $deleteExtent now keeps measured when the extension leaves the line, and the guard steps aside when $shouldRefuseExtendedDelete(measured, …) holds, so the lock refuses before the host is asked ("Cmd+Backspace on a verse-led line holding a hidden figure, even if the host would confirm it"). #3: $shouldRefuseExtendedDelete includes $rangeReachesIntoOpaqueBlock, and the caption test now runs with and without a handler.

The exception for hidden content at the caret makes sense. One note on "both halves are pinned": the other review's item 2 reports that changing (extent.range || !run) to (!run) still passes every test, so that thread is the place to settle it.


libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx line 730 at r2 (raw file):

Previously, irahopkinson+AI (Agent AI for Ira Hopkinson) wrote…

This comment is about the code on this line, which this pull request does not change.

#4 - low · checked and confirmed

Confirming "delete" for a Cmd+Backspace mid-line on a line with no verse that holds a hidden figure deletes the line's gutter glyph and rebuilds it as a new node.

What happens: The measured extent starts at (para, 0), in front of the glyph, and the lock check allows it (one paragraph, no verse). On "delete", $removeRange narrows only through $narrowEditRange ($narrowSelectionPastBookPrefix, $confineRangeToProtectedNote, HiddenContentDeleteGuardPlugin.tsx:730-733), so removeText takes the glyph and ParaMarkerPrefixGuardPlugin restores it as a new node.

Why it matters: The marker survives, but the glyph is deleted and rebuilt, which the PR's own tests pin as a defect (they assert the same glyph node), and the undo step carries the churn.

Fix: In $narrowEditRange, also call $narrowSelectionPastGutterGlyph(selection) from structureKeyboard.utils.ts. Add a test in protectedParaMarker.test.tsx asserting glyphKeyOf is unchanged after a confirmed delete, and rebuild the committed dist.

How this was checked: Ran a probe in the protected-structure test harness: a q2 line with no verse and a hidden figure, caret mid-line, line-delete extension landing at (para, 0), host answering "delete". The confirmation prompt fired once and the gutter glyph's node key changed afterward (glyph same false), so the glyph was deleted and rebuilt. On "delete", $holdCaretDelete runs $removeRange (HiddenContentDeleteGuardPlugin.tsx:382,717), which narrows only through $narrowEditRange (:730-733: book prefix and protected note). Nothing there moves the start point past the glyph, unlike the guard path at StructureKeyboardPlugin.tsx:337. The paragraph markers survive, so the cost is node churn and a heavier undo step, not data loss. The lines at :730-733 are not changed by this PR.

Other findings in this file: #1, #3

Fixed at 65559897: $narrowEditRange now calls $narrowSelectionPastGutterGlyph, pinned by "Cmd+Backspace mid-line over a hidden figure, once the host confirms, leaves the glyph untouched". The other review's item 4 notes that this also changes what cut copies in the unlocked modes when a host is set.


libs/shared-react/src/plugins/usj/StructureKeyboardPlugin.tsx line 56 at r2 (raw file):

Previously, irahopkinson+AI (Agent AI for Ira Hopkinson) wrote…

#6 - low · checked and confirmed

The new $snapshotRange re-implements the endpoint copy that $rangeSnapshot in HiddenContentDeleteGuardPlugin.tsx already performs, so a change to how selection points are snapshotted must be made in two places.

What happens: $snapshotRange copies {key, offset, type} for anchor and focus and sets them back (StructureKeyboardPlugin.tsx:56-63). HiddenContentDeleteGuardPlugin.tsx:749-767 already has $rangeSnapshot and $rangeFrom for the same job, built on PointSnapshot from structureKeyboard.utils.ts:49.

Why it matters: Maintenance only, with no behavior effect: a change to point snapshot semantics has to be made in two places.

Fix: Move $rangeSnapshot and the RangeSnapshot interface from HiddenContentDeleteGuardPlugin.tsx into structureKeyboard.utils.ts (next to PointSnapshot), export them, and document $rangeSnapshot as "Read-only: safe inside editor.read() or editor.update()". Rewrite $snapshotRange in StructureKeyboardPlugin.tsx to call $rangeSnapshot(selection) and restore with selection.anchor.set(...) / selection.focus.set(...) from the returned snapshot, keeping its in-place restore (do not substitute $rangeFrom, which creates a new range and drops invalid points). Then run node scripts/rebuild-committed-output.mjs so the committed packages/platform/dist matches.

How this was checked: $snapshotRange is new in this PR (StructureKeyboardPlugin.tsx:56-63, called at :276 and :313). Its snapshot half copies {key, offset, type} for anchor and focus, exactly what the private $rangeSnapshot at HiddenContentDeleteGuardPlugin.tsx:749-752 already does with the shared PointSnapshot type (structureKeyboard.utils.ts:49). The restore half is not a duplicate of $rangeFrom (:755-766): that builds a new, validity-checked RangeSelection, whereas $snapshotRange re-sets the live selection's points in place, so only the snapshot copy is genuinely duplicated. Maintenance-only, no behavior effect.

Other findings in this file: #2, #7

Fixed at 65559897: $rangeSnapshot and RangeSnapshot now live in structureKeyboard.utils.ts, and $snapshotRange uses them with its in-place restore.


libs/shared-react/src/plugins/usj/StructureKeyboardPlugin.tsx line 274 at r2 (raw file):

Previously, irahopkinson+AI (Agent AI for Ira Hopkinson) wrote…

#2 - medium · checked and confirmed

Pressing Delete in front of a locked line's glyph, when the line's content starts with a hidden figure, removes the figure without the hidden-content question.

What happens: HiddenContentDeleteGuardPlugin's delete handler (CRITICAL, :447) judges the caret at (para, 0); $hiddenRunAtCaret meets the gutter glyph first and finds no hidden run. Only afterwards does $handleDeleteCharacter call $moveCaretPastGutterGlyph (StructureKeyboardPlugin.tsx:277), which sets (para, 1, element) because UnknownNode is an inline ElementNode with no text host (structureKeyboard.utils.ts:153-155). The handler returns false, and Lexical's deleteCharacter then deletes forward across the figure.

Why it matters: Hidden content is removed silently on any \p \fig… line reached with ArrowRight from the line before.

Fix: Make HiddenContentDeleteGuardPlugin judge a forward delete from the caret as it will be deleted from: $hiddenRunAtCaret (hiddenContentDelete.utils.ts:63) must treat a caret at (para, 0) in front of the paragraph's gutter glyph as sitting just past the glyph, for the Delete keydown path ($onKeyDown, :430-445) and the DELETE_CHARACTER_COMMAND path (onDelete, :447-459) alike. The fix must not move the caret before the hold in a way that a refused or "keep" answer leaves displaced, and must leave Backspace behavior unchanged. Add a test to packages/platform/src/editor/protectedParaMarker.test.tsx (a \q2 line starting with a figure, caret at (para, 0), Delete: the host question is asked and a "keep" answer leaves the figure in place), and rebuild the committed packages/platform/dist with node scripts/rebuild-committed-output.mjs. Any new or changed exported $-prefixed helper needs its calling context in TSDoc.

How this was checked: I ran a probe on the real platform Editor in the locked gutter view: a \q2 line whose content starts with a figure, caret at (para, 0), Delete pressed, host handler set to answer "keep". The handler was called 0 times; the guard saw the caret at (para,0:element), and at the extension step the caret was already (para,1,element), i.e. past the glyph and directly before the figure; the figure was gone from the saved content. $hiddenRunAtCaret (hiddenContentDelete.utils.ts:63) starts from the gutter glyph, which is neither an UnknownNode nor empty text, so it finds no run; the caret is only moved past the glyph afterwards by $moveCaretPastGutterGlyph (StructureKeyboardPlugin.tsx:277, structureKeyboard.utils.ts:149-155). The forward move is new in this PR (git show 7bd11cf9:structureKeyboard.utils.ts has no gutter-glyph helper): at base the same Delete removed the glyph, which is rebuilt, and left the figure intact, so this PR introduces the silent figure removal.

Other findings in this file: #6, #7

Fixed at 65559897: the guard now judges a forward delete from a copy moved past the glyph, so "keep" leaves the caret alone ("Delete in front of a line's glyph asks before removing a hidden figure that starts the line"). The other review's item 1 follows on from this: the step-aside checks still use the unmoved caret.


libs/shared-react/src/plugins/usj/StructureKeyboardPlugin.tsx line 322 at r2 (raw file):

Previously, irahopkinson+AI (Agent AI for Ira Hopkinson) wrote…

#7 - low · checked and confirmed

A word or line delete in protected mode measures its extent through the browser twice when the cursor is not next to hidden content, once to look for hidden content and again to decide what to remove.

What happens: $deleteExtent clones the caret and runs probe.modify("extend", …) (HiddenContentDeleteGuardPlugin.tsx:696). When nothing is hidden it returns false, and $guardExtendingDelete then runs selection.modify("extend", …) again (StructureKeyboardPlugin.tsx:322) — the double extension the comment at :293-295 warns against.

Why it matters: One extra forced layout per word or line delete, and the two measurements agree only because they start from the same points. Mostly maintenance.

Fix: Recommended: keep the two measurements and fix the comment at StructureKeyboardPlugin.tsx:293-295 to say that the one-extension rule applies within $guardExtendingDelete only, and that $deleteExtent (HiddenContentDeleteGuardPlugin.tsx:696) has already measured the same extent from the same caret when no hidden content was found, so the repeat is deliberate. Avoid adding a shared cache of the measured extent: any such cache must be cleared at the end of every keystroke's update and must not be consulted for a selection whose points differ from the cached ones. The comment must not contain Jira IDs or task labels. Any source change in libs/shared-react requires rebuilding the committed output with node scripts/rebuild-committed-output.mjs.

How this was checked: For a collapsed-caret word or line delete in protected mode, HiddenContentDeleteGuardPlugin's $holdCaretDelete (HiddenContentDeleteGuardPlugin.tsx:342-353) calls $deleteExtent, which clones the selection and runs probe.modify("extend", ...) (:696) on the browser selection. When no hidden content is found it returns false (:359), the command falls through, and $guardExtendingDelete runs selection.modify("extend", isBackward, granularity) (StructureKeyboardPlugin.tsx:322) again; the line is added by this PR (the function did not exist at the merge base). Both measurements start from the same caret (selection.dirty = true at HiddenContentDeleteGuardPlugin.tsx:698 re-seats the live selection), so they agree. The cost is one extra forced layout per word or line delete, plus a comment (:293-295) about extending once that is only true within $guardExtendingDelete. Maintenance and minor performance only.

Other findings in this file: #2, #6

Fixed at 65559897: the comment in $guardExtendingDelete now says the hidden-content guard measures the same extent first and the second measurement is deliberate.


libs/shared-react/src/plugins/usj/structureKeyboard.utils.ts line 307 at r2 (raw file):

Previously, irahopkinson+AI (Agent AI for Ira Hopkinson) wrote…

This comment is about the code on this line, which this pull request does not change.

#9 - low · checked and confirmed

The TSDoc of $shouldBlockStructuralEdit does not state its calling context, although this PR edits its deleteBackward rule and adds a call that passes it a range that is not the current selection.

What happens: CLAUDE.md, Code Style: "Every exported $-prefixed function must document its calling context in its TSDoc." $shouldBlockStructuralEdit (structureKeyboard.utils.ts:314) is exported and its TSDoc (:307-313) has no Read-only or Mutating line. The PR edits its deleteBackward rule (:323-327), and HiddenContentDeleteGuardPlugin.tsx:360 now calls it on a $rangeFrom range.

Why it matters: Maintenance only: a caller has to read the body to learn that the function is a pure read and safe on a detached range.

Fix: Add a line to the TSDoc of $shouldBlockStructuralEdit in libs/shared-react/src/plugins/usj/structureKeyboard.utils.ts: "Read-only: safe in any read (editor.getEditorState().read(), an editor.update(), or a command handler); accepts a selection that is not the current one, such as one built with $rangeFrom." Add the same Read-only line to $shouldBlockSelectionReplacement just above it. Then run node scripts/rebuild-committed-output.mjs so the committed packages/platform/dist matches.

How this was checked: The TSDoc of $shouldBlockStructuralEdit (structureKeyboard.utils.ts:307-313) has only a summary, @param and @returns, with no Read-only or Mutating line, while CLAUDE.md:270 requires every exported $-prefixed function to state its calling context. The omission predates the PR (the base TSDoc is identical), but the PR edits the function's body (new gutter-glyph clause in the deleteBackward case, :323-327) and adds a caller, HiddenContentDeleteGuardPlugin.tsx:360, that passes a $rangeFrom range instead of the current selection. The PR's other new or edited helpers in the same file ($selectionSpansBlockBoundary, $narrowSelectionPastGutterGlyph, $moveCaretPastGutterGlyph) do carry the context line, so this one is the outlier. The anchor lines are unchanged by the PR. Impact is maintenance only.

Fixed at 65559897: $shouldBlockStructuralEdit and $shouldBlockSelectionReplacement both carry the Read-only calling-context line.


packages/platform/src/editor/protectedParaMarker.test.tsx line 602 at r2 (raw file):

Previously, timothy-mccormack wrote…

🤖 Generated with Claude Code

Fixed at 65559897: "%s in front of the glyph of a line that starts with a verse" covers Delete and a forward delete with no keydown from (q1, 0).

@timothy-mccormack

Copy link
Copy Markdown
Contributor Author

@katherinejensen00 The three requested changes are answered in their threads. This covers the optional items, all in 670d5724. Full test, lint and typecheck pass (shared-react 2215, platform-editor 4107), and dist is rebuilt.

Done:

  • 4. The glyph narrowing in cut and confirmed deletes is limited to "protected", so an unlocked cut copies the paragraph marker again. Pinned by "copies the line's marker in a cut when the structure is not protected".
  • 6. In front of a glyph, a forward delete is refused when what follows is display-only: a decorator (verse marker, milestone) or a hidden construct. A character style such as \wj is still deleted into, so I didn't use "text host only", which would refuse red-letter lines. Tests cover the milestone and figure-led lines. A figure-led line is now refused rather than asked about.
  • 7. Where a line extension stays collapsed, the handler extends one character and judges that range, instead of Lexical's fallback merging the next line. Tested with a line ending in a hidden figure.
  • 8. Both word-back stubs now land where Chrome does. "B|lessed" became a caret at "|Blessed", which is refused from the caret. The hidden-figure case is your item 2 shape.
  • 9. The opaque-extent check is described as defense in depth, in the code and in the PR description.
  • 10, 11, 12, 13. Comments fixed:
    • 10: "keep" can move the caret.
    • 11: the exception takes every hidden node up to the line's edge.
    • 12: the \id hand-off is "a line delete to $clampLineDeletionPastBookPrefix, a word delete to Lexical's own", and the component JSDoc names both hand-offs.
    • 13: the header holds again, because the keydown check is now glyph-aware too.
  • 14. The PR description and docs/clipboard-semantics.md say a range covering a chapter marker is refused for paste, cut, drop and typing.
  • 15. The PR description is rewritten for the current head.
  • 16. There's now an explicit leavesLine flag, the DeleteExtent docs are corrected, and $shouldRefuseExtendedDelete drops intent. It now uses $shouldBlockSelectionReplacement, which is the same check for any range.
  • 17. caretOf checks both ends, and every "keeps the marker" test asserts its glyph lookup is defined.
  • 18. $snapshotRange is now $restorerFor, "Both handlers" names them, pressKey is now pressKeyThroughDom, the test names are fixed, and the "Mirror of" note on $structuralDeleteTarget is corrected.

Listed as known gaps (in the PR description), as you suggested:

  • 5: a refused glyph-only range on a \wj-led line collapses the selection.
  • 11: cross-verse removal. It's the same on main.
  • 19: one owner for the protected-delete verdict. Moving the forward-delete rule into $shouldBlockStructuralEdit removes one of the copies you counted.
  • Pre-existing items: the glyph-only rebuild on plain Backspace or Delete, and the (para, 1) milestone variant.

🤖 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.

Thanks for making those changes, Tim!

@katherinejensen00 reviewed 9 files and all commit messages, made 1 comment, and resolved 3 discussions.
Reviewable status: :shipit: complete! all files reviewed, all discussions resolved (waiting on timothy-mccormack).

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

@irahopkinson partially reviewed 5 files.
Reviewable status: 8 of 10 files reviewed, all discussions resolved (waiting on katherinejensen00).

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

:lgtm: once the GHA builds are working.

@irahopkinson made 1 comment.
Reviewable status: 8 of 10 files reviewed, all discussions resolved (waiting on katherinejensen00).

@timothy-mccormack
timothy-mccormack enabled auto-merge (squash) October 27, 2026 00:49
timothy-mccormack and others added 10 commits October 26, 2026 20:51
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>
- 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>
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>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- 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>
… 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>
- 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>
… helper

Lost when rebasing onto main: it came in through a merge commit the rebase dropped.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@timothy-mccormack
timothy-mccormack force-pushed the pt-4121-locked-marker-test branch from 36605ff to 4e75984 Compare October 27, 2026 00:59

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

:lgtm:

@katherinejensen00 reviewed 5 files and all commit messages, and made 1 comment.
Reviewable status: :shipit: complete! all files reviewed, all discussions resolved (waiting on timothy-mccormack).

@timothy-mccormack
timothy-mccormack merged commit 1eb3192 into main Oct 27, 2026
6 checks passed
@timothy-mccormack
timothy-mccormack deleted the pt-4121-locked-marker-test branch October 27, 2026 02:00
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