Skip to content

PT-4703: Ask before an edit removes content the view does not show - #27

Merged
timothy-mccormack merged 10 commits into
mainfrom
pt-4703-hidden-content-delete-guard
Oct 23, 2026
Merged

timothy-mccormack merged 10 commits into
mainfrom
pt-4703-hidden-content-delete-guard

Conversation

@timothy-mccormack

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

Copy link
Copy Markdown
Contributor

Summary

Fixes PT-4703: in views that hide content the editor does not model, deleting next to that content lost it silently.

Figures, sidebars, \periph and the other constructs carried as UnknownNodes are display:none in every view whose markerMode is not "editable" (all but Standard and Unformatted). Native editing next to them, reproduced in Chromium with the demo app:

  • Backspace just after a figure (or Delete just before one) emptied its caption and left an empty \fig shell. The next press was a silent no-op, because the caret was then inside the shell.
  • Backspace at the start of the paragraph after a hidden sidebar merged the paragraph into the sidebar, so the paragraph vanished from view.
  • Delete at the end of the paragraph before a hidden sidebar dissolved the sidebar into the paragraph, losing \esb and exposing its text.
  • A word or line delete, or any delete, typing, Enter, paste or cut over a selection, removed whatever hidden content it covered.

What changes

New EditorOptions.onHiddenContentDelete. When it is set, a new HiddenContentDeleteGuardPlugin (shared-react) catches each of those edits before it happens, holds it, and asks the host.

The request is { items, action, canSkip }:

  • items: the hidden constructs, as { tag, marker? }, in document order.
  • action: deleteBackward, deleteForward or replaceSelection.
  • canSkip: whether "keep" will move the caret past the hidden content, or cancel the edit.

The host answers "delete" or "keep":

  • "delete":
    • A character delete, and any delete that stops at a paragraph's edge, removes exactly the hidden run. It never merges or dissolves a paragraph.
    • A word or line delete inside a paragraph removes the hidden content it covers, then carries on.
    • An edit over a selection is replayed.
  • "keep":
    • When the only hidden content the delete would reach is the run right at the caret, and there is somewhere past it to go, the caret moves past it (canSkip: true).
    • Otherwise the edit is cancelled (canSkip: false).
    • A rejected or thrown handler, and any answer other than "delete", count as "keep".
  • Refused outright, because they cannot wait for an answer:
    • Dragging a selection that holds hidden content, and REMOVE_TEXT_COMMAND (the removal half of a drag-move or composition).
    • A cut over hidden content while copyLimit is set.
  • Opt-in: without the option the plugin registers nothing, so other hosts see no change.

The demo app wires the option to window.confirm.

Design notes for review

  • Detection:
    • For content right at the caret, detection is structural (hiddenContentDelete.utils.ts). It looks through inline wrappers, skips empty text, and never leaves a note. A caret just past a paragraph's gutter label counts as the paragraph start.
    • For word and line deletes, the extent is measured the way Lexical's own deleteWord/deleteLine measure it: Selection.modify on a cloned selection, because the browser's word breaks cross display:none content. The live selection is then marked dirty, so the native delete starts from the real caret.
  • Holding and resuming:
    • The edit is resumed only against the document and selection it was held against, and only while the editor is still editable.
    • It is dropped, and the drop logged, if the text changed, the held nodes were removed, the selection moved (including a node being selected), or the editor became read-only.
    • While a question is open, typing, deleting, pasting and cutting are refused, so the host's prompt should be modal and must settle.
    • The plugin logs a warning if a question stays open longer than a minute.
  • Interplay with other guards:
    • The handlers run at CRITICAL, so they precede StructureKeyboardPlugin's KEY_DOWN handler.
    • They step aside explicitly where OpaqueBlockGuardPlugin (a selection reaching into a construct) or protected structure already refuse the edit.
    • Guarded mode's two-step delete of a selection holding a verse marker keeps both its steps. The press that arms it, and a press the other way that cancels it, are left to StructureKeyboardPlugin. The question is asked on the press that deletes.
    • armedSelectionDeleteIntent (new, in StructureKeyboardPlugin.tsx) reads the armed direction from the root's existing data attributes.
  • Logging: the plugin takes the editor's logger. It logs handler failures, answers outside "delete"/"keep", every dropped answer with its reason, and long-open questions.

Known gaps

  • An IME composition started over a selection holding hidden content is held like typing, which ends the composition. On "delete" the selection is removed, and the user re-enters the composed text.
  • Copying a selection in a hidden-marker view still includes a hidden figure's caption as plain text. This is unchanged and out of scope.

Testing

  • HiddenContentDeleteGuardPlugin.test.tsx (52 tests):
    • Keep and delete for inline and block runs, in both directions, and canSkip.
    • Word and line extent, including a block run under a line delete (never replayed).
    • Selection delete, typing, Enter, paste, cut (including the clipboard write) and input-event text.
    • The IME placeholder, drag and REMOVE_TEXT refusal, and the copy-limit cut.
    • Protected and guarded modes, including arm / wrong-direction cancel / fire, and figure-only selections.
    • Pending refusal, and editing resuming after an answer or a drop.
    • Stale, moved (range and node selection), no-selection and read-only drops.
    • Logging, opt-in, and Shift+Delete.
    • Reverting each of the three fixes from the last review round makes its targeted test fail.
  • hiddenContentDelete.utils.test.ts (25 tests) covers detection and caret placement.
  • HiddenContentDeleteGuardPlugin.gate.test.tsx (2 tests) runs the real Editor: it asks in Formatted view and never in Standard view.
  • Full suites pass for shared, shared-react and @eten-tech-foundation/platform-editor. Typecheck and lint are clean. rebuild-committed-output followed by verify-committed-dist reports the output current.
  • Verified in Chromium with the demo app, in Formatted view and in Paragraph Structure view with guarded protection:
    • Figure, keep and delete.
    • Sidebar at both paragraph edges, keep and delete. Paragraph markers stay intact, and undo restores the sidebar in one step.
    • Alt+Backspace across a figure, and Cmd+Backspace.
    • Typing, paste and cut over a selection.
  • Verified in Platform.Bible (Simple mode, with PT-4703: Confirm before the editor deletes content the view hides paranext-core#2891) against a project with a \fig in Gen 1:4 and an \esb between 1:5 and 1:6.

Release

paranext/paranext-core#2891 wires the option into Platform.Bible and needs this on platform-yalc first. No dependencies changed, so no lockfile PR is needed.

AI Involvement

AI-assisted. Claude reproduced the bug, wrote the guard and tests, and ran several self-review rounds. A human checked the behavior in the app.

🤖 Generated with Claude Code


This change is Reviewable

In every view but Standard, figures, sidebars, \periph and the other
constructs the editor carries as UnknownNodes are hidden, and native
editing removed them silently:

- Backspace after a figure (or Delete before one) emptied its caption,
  left an empty shell, and stuck the caret inside it.
- Backspace at the start of the paragraph after a hidden sidebar merged
  the paragraph into the sidebar; Delete at the end of the paragraph
  before one dissolved the sidebar into the paragraph.
- A word or line delete, or any edit over a selection, removed whatever
  hidden content it covered.

With the new EditorOptions.onHiddenContentDelete set,
HiddenContentDeleteGuardPlugin catches each of these, holds the edit,
and asks. On "delete" the edit goes ahead; a character delete removes
exactly the hidden construct, never merging or dissolving a paragraph.
On "keep" a caret stopped at the hidden content skips past it and
anything else is cancelled. Word and line deletes are measured the way
Lexical measures them (Selection.modify), so content further along is
named too. Dragging a selection that holds hidden content is refused.
Without the option, editing is unchanged.

The demo app wires the option to window.confirm.

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

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

🤖 [Claude AI Review] — PR #27

Perspective Blocking Warning Suggestion
Security 0 0 1
Scope 0 0 1
UX 0 3 2
Contracts 0 1 2
Tests 0 4 5
Architecture 0 1 2
Clarity 0 1 6
Total 0 10 19

Panel: security, scope, ux, contracts, tests, architecture, clarity. 8 decision-needed findings are inline; the rest are informational and listed below. Committed dist/ was regenerated and the API report matches the source (contracts check).

Informational findings

**[Tests]** (warning) — HiddenContentDeleteGuardPlugin.tsx

🤖 Claude AI · [Tests] (warning)

libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx

INSERT_PARAGRAPH_COMMAND and INSERT_LINE_BREAK_COMMAND over a selection that holds hidden content are intercepted, but no test pressing Enter over such a selection checks that the guard asks and replays the break on 'delete'. Deleting the handler registrations at lines 443-452 would leave every test passing.

**[Security]** (suggestion) — hidden-content-delete.model.ts

🤖 Claude AI · [Security] (suggestion)

libs/shared-react/src/plugins/usj/hidden-content-delete.model.ts

HiddenContentItem.marker and tag come straight from the loaded or pasted document ($hiddenContentItems in hiddenContentDelete.utils.ts:194-199). The TSDoc never says these strings are untrusted, so a host could reasonably assume they are always short known markers like fig or esb and render them into its confirmation prompt as HTML.

This PR adds no unsafe DOM sinks: the demo handler uses window.confirm (plain text), and no innerHTML, eval, or URL/style sinks were added in the changed files. A one-line TSDoc note ("document-derived, render as text") would cover the downstream risk.

**[Scope]** (suggestion) — HiddenContentDeleteGuardPlugin.tsx

🤖 Claude AI · [Scope] (suggestion)

libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx

The guard also catches INSERT_PARAGRAPH_COMMAND and INSERT_LINE_BREAK_COMMAND (Enter / Shift+Enter) over a selection that holds hidden content. The PR description and the EditorOptions.onHiddenContentDelete TSDoc list delete, typing, paste and cut over a selection, but never name Enter. It fits the stated goal, since Enter over a selection removes the selection, but hosts would only find out about it by reading the code.

Every other change stays within the stated scope. All PR goals are covered.

Adding 'or Enter' to the TSDoc and the CHANGELOG would make the coverage explicit.

**[UX]** (suggestion) — HiddenContentDeleteGuardPlugin.tsx

🤖 Claude AI · [UX] (suggestion)

libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx

$snapshot builds the text of the whole document, and $isStillCurrent builds it again on resume (line 568). For a whole book that is a full-tree walk and a large string each time. It runs only when an edit is held, not on every keystroke, so the cost is small. Comparing the editor-state identity, or a counter bumped by an update listener, would detect a changed document without walking the tree.

**[UX]** (suggestion) — HiddenContentDeleteGuardPlugin.tsx

🤖 Claude AI · [UX] (suggestion)

libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx

While a question is open, typing, deleting, pasting and cutting are dropped with no feedback, and a handler promise that never settles leaves the editor unable to take edits indefinitely. This is documented as the host's job (the handler must settle). A short note in the platform EditorOptions TSDoc that the prompt should be modal, and that the editor refuses edits until it answers, would help hosts avoid a stuck editor.

**[Contracts]** (suggestion) — hidden-content-delete.model.ts

🤖 Claude AI · [Contracts] (suggestion)

libs/shared-react/src/plugins/usj/hidden-content-delete.model.ts

HiddenContentDeleteHandler is a public function type exported from platform and copied into paranext-core's dist/index.d.ts, but its TSDoc has no @param request or @returns. The prose already covers the behavior: the promise must settle, and a rejected promise counts as "keep". Adding @param request and @returns tags would complete the public surface docs.

**[Contracts]** (suggestion) — hidden-content-delete.model.ts

🤖 Claude AI · [Contracts] (suggestion)

libs/shared-react/src/plugins/usj/hidden-content-delete.model.ts

"keep" means different things depending on the edit: a character or word delete moves the caret past the hidden content, while a line delete is cancelled. Both are reported with the same deleteBackward/deleteForward action, so the host cannot tell which will happen when it phrases its prompt. This is fine as it stands. If hosts later need to word the 'keep' choice precisely, a separate line-delete action (or a flag) would be an additive change.

**[Tests]** (suggestion) — HiddenContentDeleteGuardPlugin.test.tsx

🤖 Claude AI · [Tests] (suggestion)

libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.test.tsx

$isStillCurrent drops the held edit in four cases: the anchor or focus is no longer valid, a hidden node is detached, or the root text changed. Only the text-change case is tested. A case where the hidden node is removed while the question is open (an undo, say) would show that the check is not only text-based. So would a case where the selection's node is replaced while the text stays the same.

**[Tests]** (suggestion) — HiddenContentDeleteGuardPlugin.tsx

🤖 Claude AI · [Tests] (suggestion)

libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx

Two things that can happen while a question is open have no test: the plugin is unmounted or disabled (for example, the user switches to the editable view), and the answer arrives after that. A test could unmount or flip isEnabled before resolving the answer with 'delete', then check that the document is unchanged and nothing throws.

**[Tests]** (suggestion) — HiddenContentDeleteGuardPlugin.test.tsx

🤖 Claude AI · [Tests] (suggestion)

libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.test.tsx

Word and line deletes are only tested by dispatching DELETE_WORD_COMMAND or DELETE_LINE_COMMAND directly. The keystroke path through granularityOf (Ctrl+Backspace off Apple counts as a word delete, then a hold, then a DELETE_WORD_COMMAND replay on 'delete') is never exercised, and neither is the 'delete' answer for a word delete, which removes the hidden content and then re-dispatches the word command under bypass.

**[Tests]** · **[Clarity]** (suggestion) — hiddenContentDelete.utils.test.ts

🤖 Claude AI · [Tests] · [Clarity] (suggestion)

libs/shared-react/src/plugins/usj/hiddenContentDelete.utils.test.ts

This uses the half-flat tree-building shape. Hoist only the bare node and append children inside the root chain: para = $createParaNode("p"); $getRoot().append(para.append(fig));. Line 294 (sidebar = $createUnknownNode("sidebar", "esb").append(...) followed later by $getRoot().append(..., sidebar, ...)) has the same issue.

[Clarity] This uses the half-flat tree-building shape that CLAUDE.md discourages. Hoist only the bare constructor and put the children inside the root chain: para = $createParaNode("p"); $getRoot().append(para.append(fig));.

CLAUDE.md Code Style: hoist only the bare $createXNode(...) and put the children inside the root chain.

**[Tests]** · **[Clarity]** (suggestion) — HiddenContentDeleteGuardPlugin.test.tsx

🤖 Claude AI · [Tests] · [Clarity] (suggestion)

libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.test.tsx

The test helpers $figure and $sidebar are duplicated in both test files and don't follow the $create<X>Node naming convention. Rename them (for example $createFigureNode / $createSidebarNode) and consider sharing them from one test-utils module.

[Clarity] The test helpers $figure and $sidebar do not follow the $create<X>Node naming that CLAUDE.md asks test helpers to use (e.g. $createFigureNode, $createSidebarNode). They are also copied verbatim into hiddenContentDelete.utils.test.ts (lines 32-40). A shared test helper would keep the two fixtures from drifting apart.

CLAUDE.md Code Style: construct Lexical nodes via $create<X>Node helpers; test helpers follow the same pattern.

libs/shared-react/src/plugins/usj/hiddenContentDelete.utils.test.ts:32 — identical copy

**[Architecture]** (suggestion) — Editor.tsx

🤖 Claude AI · [Architecture] (suggestion)

packages/platform/src/editor/Editor.tsx

HiddenContentDeleteGuardPlugin adds another CRITICAL CUT_COMMAND handler, but this mount-order comment above CopyLimitPlugin still lists only MarkerEditPlugin, OpaqueBlockGuardPlugin and StructureKeyboardPlugin. Behavior is correct today (it sits after CopyLimitPlugin alphabetically, and refuses any cut over hidden content when copyLimit is set), but the list is now incomplete for whoever reorders plugins next.

**[Clarity]** (suggestion) — HiddenContentDeleteGuardPlugin.tsx

🤖 Claude AI · [Clarity] (suggestion)

libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx

The registration effect is about 300 lines. It defines about a dozen closures that all share the isPending/isBypassed/isDisposed flags. One possible split: move the handler factory into a function such as registerHiddenContentGuard(editor, refs) that returns the unregister callback. The hold/settle machinery would then read separately from the per-command policy. Also, $isProtectedFromReplacement (line 371) is defined below the handlers that call it (lines 332, 342, 356, 391, 406). That works, because the handlers only run later, but it makes the file harder to read top to bottom.

**[Clarity]** (suggestion) — HiddenContentDeleteGuardPlugin.tsx

🤖 Claude AI · [Clarity] (suggestion)

libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx

Handler naming is inconsistent. $onKeyDown, $onTextInsertion, $onPaste and $onCut carry the $ prefix. onDelete and onBreakOverSelection do not, yet the handlers they return run in the same command-dispatch context and call $judgedSelection/$holdCaretDelete. Naming the factories after what they return (e.g. $deleteHandler(...)), or otherwise signalling that the returned closures are $ context, would make the convention consistent.

**[Clarity]** (suggestion) — HiddenContentDeleteGuardPlugin.tsx

🤖 Claude AI · [Clarity] (suggestion)

libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx

This sentence is hard to parse: the trailing ', and native handling' reads as part of the StructureKeyboardPlugin clause. Suggested rewording: 'so that they precede both native handling and StructureKeyboardPlugin (whose guarded two-step delete would otherwise ...)'. On line 127, the @param isEnabled text 'Whether hidden content is hidden' is close to circular. 'Whether the current view hides UnknownNode content' says the same thing more usefully.

**[Clarity]** (suggestion) — HiddenContentDeleteGuardPlugin.tsx

🤖 Claude AI · [Clarity] (suggestion)

libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx

The if (isBypassed) return false; check at line 381 is redundant: $judgedSelection() on the next line already returns undefined while bypassed. The duplicate check suggests the two paths differ when they do not, so it could be removed.

libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:285 — $judgedSelection already checks isBypassed

Comment thread packages/platform/src/editor/Editor.tsx Resolved
timothy-mccormack and others added 2 commits October 15, 2026 08:37
HiddenContentDeleteRequest gains a required `canSkip`. On "keep", a
caret delete whose whole extent is the hidden content at the caret moves
past it, but a word or line delete reaching hidden content further along
is cancelled, and both send deleteBackward/deleteForward. A host
labelling its "keep" button from `action` alone could offer "Skip over
it" for an edit that would then be cancelled.

The plugin reports `canSkip` from whether the held edit has a skip
($keep), so the flag cannot drift from what "keep" does.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- Resume a held edit from a fresh microtask after focus, in two ordered
  discrete updates: the removal commits before a word or line delete is
  replayed, so the replay measures a DOM that no longer holds the hidden
  content. The old order held only because each command priority level
  runs in its own update.
- Report canSkip: false for a block run with no paragraph beyond it (a
  chapter marker, the document's edge), so "keep" cancels instead of
  leaving the caret to ask again on every press.
- Under guarded structure protection, leave the first press over a
  selection holding a verse marker to arm the two-step delete, and ask
  on the press that fires.
- Drop the held edit if the editor became read-only or the caret moved
  while asking.
- Keep pasted files when replaying a paste.
- Name the safe read form on the read-only helpers; drop the ticket ID
  from the plugin's TSDoc.
- Test paste and cut over hidden content, and the platform Editor's
  view gate (asks in Formatted view, never in Standard view).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
timothy-mccormack and others added 2 commits October 16, 2026 13:13
- Ask only on the guarded press that fires: a press in the other
  direction cancels the armed selection delete, so leave it to
  StructureKeyboardPlugin. armedSelectionDeleteIntent (replacing
  isSelectionDeleteArmed) reports the armed direction, and sits above
  StructureKeyboardPlugin's TSDoc so the component's doc is its own again.
- Recognize Lexical's composition placeholder outside Firefox and
  WebKit (a zero-width space), so a held IME start inserts nothing.
- Take the editor's logger: report handler failures, answers that are
  neither "delete" nor "keep", every dropped answer with its reason,
  and a question still open after a minute.
- Count a node selected while asking as a move, so the held edit is
  dropped; only no selection at all is focus leaving for the prompt.
- Make the request and its items readonly; say what an unknown action,
  a thrown handler, and a never-settling handler mean.
- Correct the docs: content is hidden in every view whose markerMode is
  not "editable" (Unformatted too), the keep/delete outcomes for block
  runs and line deletes, Enter among the held selection edits, the
  CUT/PASTE mount-order dependency, and the CHANGELOG.
- Test: editing resumes after an answer or a drop, logging, node
  selection vs no selection, a block run under a line delete, guarded
  wrong-direction cancel and figure-only selections, protected mode
  still asking, the cut's clipboard write, a plain cut under a copy
  limit, Enter over a selection, and the composition placeholder.

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

StructureKeyboardPlugin registers PASTE at HIGH, not CRITICAL, and the
guard steps aside for both refusals it shares CRITICAL with, so its
order among them does not matter; say so instead of claiming a mount
order dependency. Skip the one-minute warning once the guard has been
torn down, when nothing is held any more.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@timothy-mccormack
timothy-mccormack marked this pull request as ready for review October 16, 2026 18:04

@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 two adversarial verification rounds. 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 #27 (round 1)

Hi Timothy,

The guard does what it sets out to do for the cases in the PR description:

  • Backspace or Delete next to a hidden figure asks first.
  • The sidebar merge and dissolve no longer happen.
  • A merge across a paragraph boundary keeps a figure on the far side. This was checked in real Chromium.
  • Detection is cleanly separated in hiddenContentDelete.utils.ts, and the hold/resume path fails safe: a throw, a rejection or an unknown answer all count as "keep", and the drop is logged.
  • The gate test uses the real <Editor> through EditorRefPlugin, as CLAUDE.md asks.
  • CI is green, and the PR's suites pass: 52, 25 and 2 tests.

Two things should block the merge:

  • In guarded mode, a paragraph merge becomes "erase the paragraph" (item 1). If the paragraph has a hidden figure and no verse marker, the second press asks about "replacing the selection". "Delete" then empties the paragraph's visible text. "Keep" means the merge can never happen. This was reproduced in jsdom and in Chromium. Without the guard, the same presses merge and keep the figure.
  • Commit 8136397c deleted the CHANGELOG's whole ### Changed section (item 2). That section held about 12 entries from other PRs, several of them breaking-change notes, and the merge with main drops them without a conflict.

Items 3, 4 and 6 should be fixed before merge or ticketed explicitly:

  • In item 3, a confirmed line delete can still merge a paragraph into a hidden sidebar.
  • In item 4, "keep" can put the caret inside hidden content.
  • Item 6 is the tests that would let both of those through.

The rest are Low or Nit. Several of them are paths the guard doesn't cover yet rather than regressions, and I've said so where that's the case.

How this was checked. Findings marked Confirmed were reproduced with throwaway jsdom probes on the PR's plugins, or in Chromium 145 against the demo app. Traced means the mechanism was followed through this PR's code and Lexical 0.43's source (line numbers given), but not run. Every finding went through two rounds of adversarial review, and several were dropped, downgraded or reworded as a result. I haven't repeated anything you already answered in the earlier threads, except where noted. All probes were deleted, and nothing on the branch was changed.

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

Index

# Severity Attach at Issue
1 High libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:408 Guarded paragraph merge erases the paragraph instead of merging it
2 High packages/platform/CHANGELOG.md:73 The Unreleased ### Changed section was deleted
3 Medium libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:366 The replayed line delete isn't re-checked, so it can merge into a hidden sidebar again
4 Medium libs/shared-react/src/plugins/usj/hiddenContentDelete.utils.ts:181 "Keep" can put the caret inside hidden content
5 Low libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:437 Protected-mode step-aside assumes a refusal that only exists at KEY_DOWN
6 Medium libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.test.tsx:173 Tests that pass with the code they cover removed; the real Selection.modify path is never run
7 Low libs/shared-react/src/plugins/usj/StructureKeyboardPlugin.tsx:49 Reading another plugin's tooltip DOM attributes as its state
8 Low libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:399 Paths the guard doesn't cover yet
9 Low libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:381 A read-only editor asks on cut and paste, then drops the answer
10 Low libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:573 Chord mapping is looser than Lexical's, which swallows Alt+Backspace (Undo)
11 Low libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:213 The host's handler runs synchronously inside a Lexical update
12 Low libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:136 "Order among the other CRITICAL CUT and PASTE handlers does not matter" is not true
13 Low libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:500 Asked-about edits that then do nothing; a held edit's staleness check misses verse changes
14 Low libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:100 Doc volume and two inaccurate docs
15 Low libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:192 Design question: could the no-handler default be safe too?
16 Low libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:317 Undo: following up on the existing thread
17 Low libs/shared-react/src/plugins/usj/hiddenContentDelete.utils.ts:103 Smaller edge cases
18 Nit libs/shared-react/src/plugins/usj/HiddenContentDeleteGuardPlugin.tsx:70 Cleanup and test-helper conventions

I'm marking this Request changes so it doesn't merge before this round is addressed. The 18 items are inline comments, each numbered to match the index above.

What's good

  • Detection and editing are kept apart. The utils' TSDoc states each calling context correctly, and the module reuses $placeCaretAtEnd, $advancePastParaPrefixes, isEditingKey, $selectionReachesIntoOpaqueBlock and the $shouldBlock* predicates rather than rewriting them.
  • It's hard for a host to break. A throw, a rejection or an unknown answer counts as "keep" and is logged. The handler, mode, limit and logger are held in refs, so a fresh handler doesn't re-register. A resume is checked against keys, text, selection and editability.
  • canSkip lets a host label its button honestly, and the items / action shape can grow without breaking anyone.
  • Earlier review threads were answered with tests, and those tests do fail when their fixes are reverted.
  • The platform package exports only the types; the plugin stays internal.

Comment thread packages/platform/CHANGELOG.md Resolved
timothy-mccormack and others added 2 commits October 21, 2026 11:05
…t-delete-guard

# Conflicts:
#	packages/platform/dist/index.js
#	packages/platform/dist/index.js.map
- Guarded selection deletes fire through DELETE_CHARACTER_COMMAND, so the
  guard no longer reads StructureKeyboardPlugin's tooltip attributes
  (armedSelectionDeleteIntent is gone) and stops judging selections at
  KEY_DOWN. A guarded paragraph merge next to a figure merges again rather
  than asking to erase the paragraph; "keep" clears the arm and its hint;
  guarded Shift+Delete is asked about.
- A word or line delete removes its measured extent and the hidden content
  in one update: one undo restores both, and a delete already at a line's
  start, or one whose extent leaves the paragraph, takes only the hidden
  content instead of falling back to a paragraph-merging character delete.
- "Keep" never puts the caret inside a figure, footnote or character span
  it skipped; it prefers a text point, which survives Lexical's read-back.
- Delete chords match Lexical's exactly (isExactShortcutMatch), so
  Alt+Backspace (Undo off Apple) and unbound chords pass through.
- Delete and Enter commands over a protected selection are asked about;
  protected structure refuses only at KEY_DOWN.
- The handler is called a task after the keystroke, outside its update.
- A cut narrows its range (the id prefix, a note's shell) before copying.
- A read-only editor, a paste the command menu refuses, and a paste of files
  alone are not asked about.
- A held edit is dropped when what it covers changes (a verse marker added
  inside it included), judged before focus returns; no root element is
  logged as a drop.
- A delete at an expanded note's far edge is followed out into its
  paragraph; a paragraph's marker label is in the way of a Backspace.
- Restore the CHANGELOG's Unreleased "Changed" section; fold the guard's
  Fixed entry into Added; trim the plugin, option and model docs.
- Tests: command-level refusals while pending, Selection.modify-measured
  word/line deletes, undo, the paste replay's clipboard copy, the guarded
  merge, caret placement next to trailing and leading hidden content.

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

Copy link
Copy Markdown
Contributor Author

@katherinejensen00 this round is done in e79217e, after merging main in (ee9b7fd). Each of the 18 threads has a reply.

Left for follow-up tickets (the details are in each thread):

  • Protected mode doesn't refuse delete and Enter commands over a selection (item 5).
  • StructureKeyboardPlugin's drop position (item 8).
  • A node-level fix to UnknownNode so the default is safe without a handler (item 15).
  • The legacy marker menu's key priority while it's open, and milestones (item 17).

One thing I couldn't check in jsdom: where "keep" has no text to land in, such as a paragraph that ends with a footnote, the caret falls back to an element point. Lexical can normalize such a point into the adjacent element when it reads the selection back from the DOM, so it's worth checking in Chromium with your probe setup.

@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! Just three more things to look at:

1. On top of current main, the guarded two-step delete of a verse selection never fires

High · Confirmed (4 failing tests on the merged tree, plus jsdom probes) · libs/shared-react/src/plugins/usj/StructureKeyboardPlugin.tsx:126

#22 (PT-4540, the selectable gutter marker), which is now on main, added a DELETE_CHARACTER_COMMAND handler at HIGH to StructureKeyboardPlugin. That handler ($handleDeleteCharacter) runs $handleTwoStepDelete for deletes that arrive as commands. Its comment states the assumption it relies on: "After a keydown this plugin claimed, no delete command follows."

This PR's fire breaks that assumption. It clears the arm and then dispatches DELETE_CHARACTER_COMMAND. Main's handler then sees a selection that holds a verse and nothing armed, so it arms again instead of deleting. Both sides merge without a conflict, so a rebase won't flag this.

What happens on the merged tree:

  • Without a handler (every host today). The second Backspace or Delete re-arms, so a selection holding a verse can never be deleted in guarded mode.
  • With the guard, a keyboard delete. The second press asks. On "delete", the guard's bypassed replay reaches main's handler and re-arms, so the answer does nothing.
  • With the guard, a command-level delete (macOS Ctrl+H, the context menu, beforeinput). Every press asks, and every "delete" re-arms.
  • With the guard, a cut over a verse and a figure. The copy happens and the guard asks. "Delete" removes nothing and leaves the selection armed, so the cut acts as a copy.

Failing tests on the merged tree:

  • StructureKeyboardPlugin.test.tsx:760: "first Backspace arms (no delete), second Backspace deletes the whole selection"
  • StructureKeyboardPlugin.test.tsx:788: "second Backspace keeps the \id line's prefix…"
  • HiddenContentDeleteGuardPlugin.test.tsx:1202: "lets the guarded two-step delete of a selection holding a verse arm, and asks on the press that fires"
  • packages/platform/src/editor/Editor.test.tsx:758: "undo after a verse-spanning delete" (its setup is a guarded Delete, Delete)

Suggested fix: merge main, then make $handleDeleteCharacter let through a delete that has already been confirmed. Two deletes count as confirmed:

  • the fire's own dispatch;
  • the guard's replays (delete, cut, and typing or composition over the selection) after the user answered "delete".

A re-entrancy flag covers only the fire. The replays run later, so they need something that outlasts the fire, for example a record of the fired selection's points that the replay's restored selection matches. How to do it is your call. Whatever the approach, the four tests above have to pass with main's handler in place.

2. "Keep" before a paragraph that opens with a footnote: the next keystroke is lost and an NBSP is inserted

Medium · Confirmed (Chromium 145) · libs/shared-react/src/plugins/usj/hiddenContentDelete.utils.ts:400

This follows up your open question about the element-point fallback.

Setup: Delete at the end of first, where a hidden sidebar comes next and the paragraph after it opens with a footnote. Answer "keep".

  1. $placeCaretAtVisibleStart finds no text before the note, so it falls back to an element point at (para, 0).
  2. The user then types. Typing "Z" gives U+00A0 | note | "second", and typing "Hello" gives " ello"{note}second.

So the first character is lost and an invisible no-break space ends up in the text.

Natively, a DOM caret at that spot gives Lexical a null selection, and the typed text is simply dropped. The underlying fragility is older than this PR, but "keep" is what puts the caret there.

The other fallbacks don't put the caret inside hidden content:

Case Caret after "keep" Typing
Block before the sidebar ends with a footnote Zero-width placeholder after the note Lands after the note. Good
Block after the sidebar starts with a figure (para, 0) Lands after the figure, caption untouched. Fine
Block before the sidebar ends with a figure (para, 2) Lands before the figure, caption untouched. See item 3

Suggested fix:

  • Where the visible start is just before a note, give the caret a text host there. The trailing-note case already gets a zero-width placeholder, so the same mechanism should work.
  • Add a test for keep, then type, in this case.

It takes a rare combination to hit, so a ticket is a reasonable alternative.

3. "Keep" after a trailing figure: typed text lands before the figure

Low · Confirmed (Chromium 145) · libs/shared-react/src/plugins/usj/hiddenContentDelete.utils.ts:389

When the block before the sidebar ends with a figure, $placeCaretAtVisibleEnd leaves the caret at an element point after the figure. Typing then lands before the figure, in the text that precedes it. The figure is hidden, so the user sees no difference, and nothing is corrupted.

Two ways to fix it:

  • Make it deliberate: when the last leaf is hidden, place the caret at the end of the visible text before it. A text point is also the robust choice.
  • Or say in the TSDoc that the caret may end up on either side of hidden content.

@katherinejensen00 reviewed 21 files and all commit messages, made 2 comments, and resolved 23 discussions.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on timothy-mccormack).


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

          if ($isRangeSelection(selection)) {
            $narrowSelectionPastBookPrefix(selection);
            editor.dispatchCommand(DELETE_CHARACTER_COMMAND, intent === "deleteBackward");

1. On top of current main, the guarded two-step delete of a verse selection never fires

High · Confirmed (4 failing tests on the merged tree, plus jsdom probes) · libs/shared-react/src/plugins/usj/StructureKeyboardPlugin.tsx:126

#22 (PT-4540, the selectable gutter marker), which is now on main, added a DELETE_CHARACTER_COMMAND handler at HIGH to StructureKeyboardPlugin. That handler ($handleDeleteCharacter) runs $handleTwoStepDelete for deletes that arrive as commands. Its comment states the assumption it relies on: "After a keydown this plugin claimed, no delete command follows."

This PR's fire breaks that assumption. It clears the arm and then dispatches DELETE_CHARACTER_COMMAND. Main's handler then sees a selection that holds a verse and nothing armed, so it arms again instead of deleting. Both sides merge without a conflict, so a rebase won't flag this.

What happens on the merged tree:

  • Without a handler (every host today). The second Backspace or Delete re-arms, so a selection holding a verse can never be deleted in guarded mode.
  • With the guard, a keyboard delete. The second press asks. On "delete", the guard's bypassed replay reaches main's handler and re-arms, so the answer does nothing.
  • With the guard, a command-level delete (macOS Ctrl+H, the context menu, beforeinput). Every press asks, and every "delete" re-arms.
  • With the guard, a cut over a verse and a figure. The copy happens and the guard asks. "Delete" removes nothing and leaves the selection armed, so the cut acts as a copy.

Failing tests on the merged tree:

  • StructureKeyboardPlugin.test.tsx:760: "first Backspace arms (no delete), second Backspace deletes the whole selection"
  • StructureKeyboardPlugin.test.tsx:788: "second Backspace keeps the \id line's prefix…"
  • HiddenContentDeleteGuardPlugin.test.tsx:1202: "lets the guarded two-step delete of a selection holding a verse arm, and asks on the press that fires"
  • packages/platform/src/editor/Editor.test.tsx:758: "undo after a verse-spanning delete" (its setup is a guarded Delete, Delete)

Suggested fix: merge main, then make $handleDeleteCharacter let through a delete that has already been confirmed. Two deletes count as confirmed:

  • the fire's own dispatch;
  • the guard's replays (delete, cut, and typing or composition over the selection) after the user answered "delete".

A re-entrancy flag covers only the fire. The replays run later, so they need something that outlasts the fire, for example a record of the fired selection's points that the replay's restored selection matches. How to do it is your call. Whatever the approach, the four tests above have to pass with main's handler in place.

timothy-mccormack and others added 2 commits October 21, 2026 16:46
…t-delete-guard

# Conflicts:
#	packages/platform/CHANGELOG.md
#	packages/platform/dist/index.js
#	packages/platform/dist/index.js.map
…" in text

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

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

Copy link
Copy Markdown
Contributor Author

@katherinejensen00 all three are done in 486a68d, after merging main with #22 in (43d21ad).

1. The guarded verse-selection delete never firing. I went with an update tag rather than a record of the fired selection's points. StructureKeyboardPlugin's fire dispatches its delete in an update tagged CONFIRMED_DELETE_TAG, and so does every edit the guard replays after a "delete" answer: delete, cut, and typing or composition over the selection. $handleDeleteCharacter lets a tagged delete through under "guarded". The tag belongs to the dispatching update, so nothing outlives it and there's no stale record to clear after a "keep".

  • Your four tests pass with main's handler in place. Removing the handler's tag check fails the three in shared-react; the platform one didn't run once those failed, and passes with the check in place.
  • New tests with the guard mounted under "guarded": a command-level delete and a cut over a verse and a figure are removed on "delete" rather than re-armed. Dropping the guard's tag fails both.
  • PT-4540: Make a paragraph's gutter marker selectable #22's handler also refuses DELETE_CHARACTER_COMMAND under "protected" now, so the guard steps aside for that command there again. Otherwise it would ask, and the answer would do nothing. Word and line deletes and Enter are still asked about, since nothing refuses them at the command level.

2. "Keep" before a paragraph that opens with a footnote. The caret now goes to the start of the text just after the note, a text point, rather than to the element point before it. Typing lands after the note, with nothing lost and no NBSP. I didn't add a caret host before the note: the transient host is tied to TrailingNoteCaretGuardPlugin's selection-change lifecycle, and a host the guard inserted itself would have nothing to clean it up. Tests: a utils test of the caret position, and a plugin test of "keep" and then typing.

3. "Keep" after a trailing figure. I made it deliberate: hidden content that ends the block before the sidebar is passed over, so the caret sits at the end of the visible text before it, a text point, which is where typing lands anyway. A trailing note still gets the boundary after it, which TrailingNoteCaretGuardPlugin hosts, as in your table.

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

The changes look good. There are two low priority findings that aren't worth holding the merge up over so I will approve the pr.

Two Low items. Neither blocks the merge, and either could be a jira ticket.

  1. A delete command over a verse skips the guarded arm step.
    Under "guarded", a delete that arrives as a command rather than a keypress (macOS Ctrl+H, the context menu) over a selection holding a verse and a figure:
  • asks right away, and the question names only the figure;
  • on "delete", removes the verse too, with no arm step first.

Without the guard, main arms first and deletes on the second command. The keyboard path is fine: it arms, then asks when it fires. The new test "removes a selection holding a verse for a delete command, rather than arming it" locks in the command-path behavior.

Suggested fix: under "guarded", have the guard ignore an untagged DELETE_CHARACTER_COMMAND whose selection StructureKeyboardPlugin would arm. That plugin then arms it, and the fire comes back tagged, so the guard asks at that point. Then update the test to expect "arm, then ask."

  1. "Keep" can still leave the caret where item 2's bug happened.
    The fix for item 2 moves the caret just past a note that opens the next paragraph. It still ends up at an element point with no text to land in when another note or hidden content follows that note:
  • forward, a paragraph that opens with note, note, text (say, a footnote then a cross-reference), or with note, figure, text;
  • backward, a paragraph that ends with text, note, figure.

That's the spot where item 2 lost the first keystroke and inserted a no-break space. I only traced this through $placeCaretAtVisibleStart, $placeCaretAtVisibleEnd and $selectAfter; I haven't run it in Chromium. The layouts are rare, so a ticket with a test that answers "keep" and then types in each layout would be enough.

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

…t-delete-guard

# Conflicts:
#	libs/shared-react/src/plugins/usj/NoteShellCaretGuardPlugin.tsx
#	packages/platform/dist/index.d.ts
#	packages/platform/dist/index.js
#	packages/platform/dist/index.js.map
@timothy-mccormack

Copy link
Copy Markdown
Contributor Author

@katherinejensen00 #11 landed on main after your approval, and #27 conflicted with it, so I merged main in (1c1ca76). One change touches code you approved; could you glance at it before I merge?

#11 rewrote NoteShellCaretGuardPlugin's range narrowing. $narrowSelectionOutOfShell is now $confineRangeToProtectedNote, and it confines any range that touches a protected note to that note's content, rather than only trimming the shell. I took #11's version unchanged and exported it, as the old function was, and the guard now calls it in the same two places: before a cut's copy, and before a word or line delete's range is removed. Against 486a68d, the guard's diff is just that rename. The effect is that the guard confines a range exactly as NoteShellCaretGuardPlugin will downstream, so a cut's copy and its removal still take the same range.

Merged tree: all tests in shared, shared-react and platform pass, and typecheck and lint are clean. dist/ was regenerated with extract-api.

@katherinejensen00

Copy link
Copy Markdown
Contributor

Looks good. Thanks for handling that merging!

@timothy-mccormack
timothy-mccormack merged commit fe399c3 into main Oct 23, 2026
5 of 6 checks passed
@timothy-mccormack
timothy-mccormack deleted the pt-4703-hidden-content-delete-guard branch October 23, 2026 14:26
timothy-mccormack added a commit to paranext/paranext-core that referenced this pull request Oct 23, 2026
)

Wires the editor's EditorOptions.onHiddenContentDelete (paranext/scripture-editors#27) to a modal, destructive platform.confirm. In views that hide figures, sidebars and other content the editor cannot display, Backspace, Delete, word and line deletes, and edits over a selection ask before removing it. The keep button reads Skip over, Don't delete, or Cancel edit, matching what the editor will do. The prompt names the content as USFM with counts, and comes from the web view's live localized strings. The guard is off while the editor is read-only.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants