[tjcouch-sil]

Summary

Scripture-editors half of PT-4911. In the views that hide USFM markers (Simple mode's paragraph-structure view, the formatted view, block-verse):

• Copy no longer writes gutter paragraph markers (\q1 ) or hidden figure/unknown-construct text. A collapsed footnote's text stays in the plain-text copy, by design (catalog CB-6).
• Paste and drop are never refused any more. Every \, and every // scanning left to right (/// leaves /), is removed from the inserted text, on every insertion route (Lexical's node route, its plain-text route, drops, and the locked-structure html path). A / next to an existing / counts as forming //. A single / ("and/or", 1/2) is kept. Stray-marker (unmatched) nodes are left alone.
• Typing a single / works; \, and a / beside a /, are blocked. A / beside a / is judged across a comment or annotation mark's edge too.
• An optional line break counts as the // the file stores for it. The view shows nothing there, but a / against one saves as ///, and with a / on its other side as ////, two breaks, which hides both / after the next load. So a / typed or pasted against a break is refused or removed, and a delete that would bring a / against one is refused, as for any other /.
• A macOS transpose (Ctrl+T) never joins two / into //. Chromium raises it as a beforeinput insertTranspose, which Lexical applies past the filters, so /x/ could become //x. UnstorableTextPlugin refuses a transpose that would put a / against a / (an optional line break counts as //), judged as the Backspace and Delete at that caret ($transposeJoinsSlashes). It keeps the caret in place and reports source: "typing". Modelled in jsdom only; unverified on a real Mac.
• Deleting never joins two / into //. Deleting b from a/b/c saved a//c, which the next load reads as an optional line break (the view then showed ac). A delete whose result would put a / against a / it was not already touching is refused, and reported once through onUnstorableTextRemoved with the new source: "deletion". It covers Backspace and Delete with their word and line chords, keydown-less deletes, selection deletes, a selected paragraph marker, a paragraph join (guarded structure's first press), cut and a drag-move's removal. Under protected structure a join stays protection's own refusal. Known gaps (S5): IME composition, and Android Chrome's browser-applied Backspace.
• The host is told through a new EditorOptions.onUnstorableTextRemoved, called once per paste, drop or blocked keystroke that removed something. Hosts show the notice (paranext-core: companion PR below).
• Locked structure: a plain-text paste of several lines now joins them with one space instead of starting a new paragraph.
• Marker glyphs in pasted or dropped html (a drag across a paragraph break, an older copy) are dropped in these views, as the locked path already did, so a marker name never arrives as text.

UnstorableTextPlugin is mounted in every view and acts only where markers are hidden (isEnabled), so an editor that switches into a hidden-marker view keeps its delete handlers ahead of the other plugins' at the same priority. Mounted only in hidden views, it registered behind ParaMarkerSelectionPlugin's after a switch, and deleting a selected paragraph marker could join a/ and /c. The same fix is on the PT-4921 branch (#43).

Standard and Markers views are unchanged.

Companion: paranext/paranext-core#2969, which wires the notice and updates the data-fidelity catalog. Merge this first, then move platform-yalc.

Rebased onto main, which includes #29's PT-4197 work; this branch carries only PT-4911's commits. Two follow-ups for main's changes: HiddenViewCopyPlugin now writes a stored no-break space as ~ in its plain text unless allowInvisibleCharacters is on, as main's InvisibleCharactersPlugin does for these views (this plugin claims the copy ahead of it); and since main's StructureKeyboardPlugin inserts a protected paste through SELECTION_INSERT_CLIPBOARD_NODES_COMMAND, UnstorableTextPlugin filters that paste even without the sanitizer's own filter, which the editor still passes so a drop is reported as a drop. PT-4921 (lossless Ctrl+V, #43) is stacked on this.

Why review this

Part of the Standard-view epic's data-fidelity work: PT-4911 fixes catalog rows CB-1 and CB-5 found by the PT-4197 audit. Copying across a paragraph break in Simple view couldn't be pasted, a cut text was lost until Undo, and any paste with \ or / (a URL, "and/or") was silently refused.

Changes

• HiddenViewCopyPlugin + hiddenViewCopy.utils.ts: one copy/cut writer for hidden-marker views (plain text without gutter glyphs or unknown-construct text; html without glyph spans; the editor's own flavor unchanged, behind $hiddenViewLexicalFlavor, which PT-4921 changes). CopyLimitPlugin's over-limit copy uses the same predicate plus collapsed notes.
• UnstorableTextPlugin + unstorableText.utils.ts + unstorable-text.model.ts (shared-react): the filter, its paste/drop/typing routes, the delete check and the notice. Mounted in every view, acting only in hidden-marker ones, where it replaces CommandMenuPlugin (the Markers view keeps that). Word and line deletes are measured by $probeDeleteExtent (hiddenContentDelete.utils.ts), shared with HiddenContentDeleteGuardPlugin. StructureKeyboardPlugin takes $filterPastedNodes for its locked html path (hidden views only). HiddenContentDeleteGuardPlugin asks before a paste that will insert something.
• shared-react now depends on @lexical/clipboard (same version as packages/platform).
• Clipboard corpus (clipboardViewsCorpus.test.tsx): paragraph-structure rows now run off, guarded and protected; rows for "and/or", 1/2, a URL, ranges holding a figure; hidden-view copies checked for no gutter text, no caption, and the collapsed note's text. The 44 PT-4911 pins are gone.
• docs/clipboard-semantics.md S5 rewritten; CHANGELOG; committed dist and etc/platform-editor.api.md rebuilt (public API: onUnstorableTextRemoved and three types; UnstorableTextRemoved.removed is a readonly array, and the handler is called synchronously from the editor command or update that made the edit).

Decisions for the reviewer

• Locked structure + a stray marker: under protected (Simple's default), the locked html path's DOMPurify drops the <unmatched> tag, so a copied stray \* pastes as * (with the notice). Accepted by TJ for now. A two-line DOMPurify allowlist would keep it; unlocked and Ctrl+V-through-the-editor-format routes already keep it.
• Plain-text-only paste of a copied stray marker (\*) gives * with the notice, the same rule as \v 9 x → v 9 x.
• IME-composed \ or // is not filtered (documented in the plugin's TSDoc).
• Known, tracked in PT-4921: the html route still loses attributes and note details; a caption-less figure is left out of the editor's own clipboard format, so cut → paste back of a range holding one loses it (pinned under the PT-4921 rule).
• A refused delete during a drag-move leaves the text in both places: the drop is its own input event and still goes in, so the move becomes a copy, with the "not deleted" notice. Nothing is lost.
• A cut that first asks about hidden content has already copied: HiddenContentDeleteGuardPlugin copies before it asks, so if the removal is then refused for joining two /, the copy stays on the clipboard and nothing is removed (documented in S5's known gaps).
• Pre-existing, not changed here: under protected, a glyph-only html paste over a selection removes the selection (StructureKeyboardPlugin inserts an empty list).

Testing

• nx run-many -t typecheck lint: 0 errors. Vitest (--pool=forks --maxWorkers=4): shared 922 passed; shared-react 2387 passed, 1 skipped; packages/platform 5614 passed, 77 expected-fail, 126 skipped (run before the final review's fix commits; the touched suites were re-run after them and pass). Clipboard corpus: 826 passed, 73 expected-fail (PT-4921 60, PT-4388 13); with SE_TEST_LIBRARY_VIEWS=1 1125 / 91.
• After the code review: shared-react 2392 passed, 1 skipped; touched packages/platform suites 917 passed, 73 expected-fail.
• Deletion guard: unstorableText.utils.test.ts ($deletionJoinsSlashes, 24) and unstorableTextDeletion.test.tsx (99); shared-react 2411 passed, 1 skipped; platform src/editor 4879 passed, 4 expected-fail; corpus 826 / 73.
• After the /review-paratext round (optional-line-break rule, always-mounted plugin, shared delete-extent probe, readonly removed, new tests): nx run-many -t typecheck lint clean; shared-react 2417 passed, 1 skipped; packages/platform 5741 passed, 77 expected-fail, 127 skipped.
• Against main (run on the merged tree before the rebase; the rebase changed no PT-4911 source): nx run-many -t typecheck lint clean; shared 948 passed; shared-react 2467 passed, 1 skipped; packages/platform 6043 passed, 69 expected-fail, 143 skipped. Clipboard corpus: 833 passed, 66 expected-fail (PT-4921 60, PT-4388 6: main's work lets the 2SA-5 plain-text pastes through); with SE_TEST_LIBRARY_VIEWS=1 1132 / 84.
• Transpose refusal: $transposeJoinsSlashes utils rows and unstorableTextTyping.test.tsx transpose rows, each guard mutation-checked. shared-react 2483 passed, 1 skipped; platform unstorable, clipboard and paste suites 1324 passed, 66 expected-fail.
• Rebased onto main after the Scribe removal (scripture-editors#2) and PT-4982 (#2973); no Scribe-specific content left. nx clean; unstorable and clipboard suites 1386 + 84 expected-fail.
• node scripts/verify-committed-dist.mjs: current at e7a9373c.
• Hand QA in the app: not done.

AI Involvement

AI-assisted (Claude Code): implemented task by task by AI subagents from a written plan, each task spec- and quality-reviewed by a separate AI reviewer, then a whole-branch AI review and fix wave. TJ ruled on the open product questions.

Risk Level

Medium — changes every clipboard route in Simple mode's editable view; covered by the corpus suite in all three structure-protection modes.

🤖 Generated with Claude Code

---

This change is