Skip to content

PT-4885: Keep the line still and the caret after the number in an empty verse - #34

Merged
timothy-mccormack merged 8 commits into
mainfrom
pt-4885-empty-verse-caret-reflow
Oct 27, 2026
Merged

timothy-mccormack merged 8 commits into
mainfrom
pt-4885-empty-verse-caret-reflow

Conversation

@timothy-mccormack

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

Copy link
Copy Markdown
Contributor

Stacked on #33, which hardens the caret host so it is safe to keep alive between verses. Review that one first; this diff shows only PT-4885's own changes. A paranext-core PR carries the matching stylesheet rules, since the app styles the editor from its own vendored copy.

The bug

In Simple mode (paragraph-structure view), clicking or arrowing into an empty verse:

  • pushed the next verse number onto a new line, even though it fit before;
  • drew the caret at the start of that new line, in front of the next number, although typed text landed after the empty verse's number, where it belongs.

Why

  • The caret. EmptyVerseCaretGuardPlugin puts a caret host (a zero-width-space text node) after the empty verse's number. TextSpacingPlugin then added its structural trailing space to that host, because the host sits before the next verse. Spaced, the host looked typed into, so it was stripped and deleted in the same update that created it. The caret fell back to the element point between two verse decorators, and Chromium draws that at the start of the next verse. When the empty verse ends a line, that's the next line.
  • The reflow. ActiveTextPlugin removed the active verse's "…". That shrank the line, and it left the verse number's trailing zero-width space at paragraph level, where it is a line-break opportunity. A run of empty verses has none otherwise: every verse number starts with a zero-width space, which forbids a break before it, so the run wraps only where it overflows. One new break opportunity moves everything.

The fix

  • Host DOM: the host's DOM element carries data-caret-host (CARET_HOST_ATTRIBUTE), copied from the node's mark by a mutation listener, so the stylesheet can target the host itself rather than whatever text follows a verse.
  • TextSpacingPlugin: a marked caret host is exempt (via $hasCaretHostMark, added here, which asks about the mark alone so the answer does not depend on transform order). Every sibling check looks past a host, so these land in the commit the app hears about, not the later host-removal commit:
    • text pasted in front of a host is spaced against the verse past it;
    • a space pasted after the host, a verse's whole content, is removed;
    • a char span pasted before the next verse gets its structural space (the host's transform dirties that verse, which the insert alone does not);
    • an annotation over a resting host writes no space into the empty verse.
  • EmptyVerseCaretGuardPlugin: a delete from a host between verses runs from the boundary the host stands for. With structure protection off, Delete used to remove only the placeholder, and the guard put a new one back, so it never reached the next verse's marker.
  • ActiveTextPlugin:
    • The active empty verse gets psc-empty-text-active instead of just losing psc-empty-text.
    • No focus box or active verse is drawn after a blur, though the guard's host removal commits after it.
    • A click on the ellipsis puts the caret into an existing host. A click inside an editable verse marker's own text, and a double or triple click, are left alone.
  • Stylesheet (usj-nodes.css):
    • The ellipsis is a fixed-width inline-block (--psc-empty-verse-ellipsis-width).
    • On the active verse it stays in place but transparent (forced-color-adjust: none), so the line's width and its break points don't change.
    • The caret host ([data-caret-host]) is pulled back over it by margin-inline-start: -width and pushes what follows forward by margin-inline-end: width. It takes no room, and its caret is drawn right after the number.
    • In every view, a host after a verse has text-wrap-mode: nowrap and a ::after word joiner, so its zero-width space adds no break opportunity. text-wrap-mode rather than white-space, which would turn a typed space into a no-break space.
    • The box rules skip .marker verses (visible markers), whose ::after is the verse number itself.
  • CHANGELOG: an Unreleased → Fixed entry, since a host that vendors usj-nodes.css needs the new rules.

Testing

  • Unit:
    • The TextSpacingPlugin cases run in both mount orders, and the paste cases assert on the paste's own commit.
    • Delete and Backspace from either host offset, with protection off, reach the verse markers in one undo step.
    • The host's DOM attribute, ActiveTextPlugin's blur and click handling, and each empty-verse CSS declaration on its selector (usj-nodes.css.test.ts, reading the class names and attribute from their constants) are covered too.
    • Reverting each fix fails at least one test.
    • Counts: shared 895, shared-react 2286, platform 4134 passed. Typecheck, eslint and prettier clean; committed dist rebuilt and verified.
  • Browser (platform demo, Chromium): a \p of 40 empty verses, placing the caret after each verse in turn.
    • Paragraph Structure view, at 433, 520 and 640px: no verse number moved, every host carried data-caret-host, and the caret was drawn about 2px past the number's glyph.
    • Markers view (markerMode: "visible"), at 433 and 640px: no verse number moved. With the two no-wrap rules disabled, 37 and 36 of 40 placements moved.
    • The earlier run (before review): 440 placements at 11 widths, plus mixed text, clicking and arrowing, with nothing moving.
  • Paratext 10 Studio (macOS): checked by hand before review. Not yet rechecked with these changes.

Known limitations

  • From the host machinery (PT-4885: Keep the caret host intact through paste, undo, blur and the keyboard #33), and already on main at a paragraph-end host; this PR makes them the common case:
    • every empty verse followed by another verse costs one ArrowRight press that moves nothing visible (host offset 0 to 1);
    • Shift+Arrow from inside a host never extends the selection, on any press;
    • a rare drop on the far side of the placeholder.
  • In an RTL paragraph whose text around an empty verse is Latin, the host's logical margins act on the wrong side, and the caret is drawn after the next verse's number. Typed text still lands after the right one.
  • An annotation over a resting host wraps the host, so the margin rule stops matching and the caret is drawn after the hidden ellipsis until the caret leaves. Nothing is saved wrongly.
  • Applying a peer's delta counts a host as one unit, so a remote op past a host lands one unit off. No paranext-core caller sends remote ops today.

🤖 Generated with Claude Code


This change is Reviewable

timothy-mccormack and others added 2 commits October 26, 2026 18:19
The transient caret host (a placeholder-only text node that gives an empty verse or a trailing collapsed note a caret to render in) was recognized only by the key one guard instance tracked, and its placeholder was stripped by content. That leaked the placeholder into saved Scripture, or deleted real zero-width spaces, in several ways:

- Pasted text merged with the host, carrying the placeholder in under the pasted node's key.
- Stripping removed every zero-width space from text that landed in the host, so a Thai or Khmer word break pasted or typed there was lost.
- With all three guards mounted, a second instance stripped again after the first.
- An undo that brought a host back left it untracked, so text typed into it kept the placeholder.

The host is now marked with node state, which also keeps Lexical from merging neighboring text into it. Only marked nodes are stripped, removed or adopted, and only the host's own placeholder is removed, where its position is known. An untracked host the caret rests in is adopted. Creating or removing a host is merged into the current undo step, so it never clears the redo stack.

Also:

- Blur removes the host without writing the DOM selection back (which stole focus) and leaves the caret at the boundary it stood for, not inside a collapsed note.
- Focus that returns without a selection change re-hosts the caret.
- Any range selection, even inside the placeholder, removes the host, so it can't be copied or quoted by a footnote.
- Delete and Backspace see through a bare host to the neighboring verse marker and the paragraph edges.
- The delta fast path counts a bare host as zero length, so the first keystroke into it no longer emits a delete for whatever follows.
- An unmarked zero-width space at a guarded boundary (loaded or typed as content) is reused rather than stacked behind, and never removed.

Prerequisite for PT-4885, which keeps the host alive between two empty verses.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
An update made outside any event resolves its selection from the DOM. The
focus re-host ran one from a microtask, and right after a focus the DOM may not
yet hold the selection just committed (jsdom puts it at the editor start), so
it could move the caret instead of hosting it. Under CI load this made
noteCaretPlacement's empty-note selectNote test flaky. Decide from the
committed state first and update only when a host is actually missing.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@timothy-mccormack
timothy-mccormack force-pushed the pt-4885-caret-host-hardening branch from 5fecc42 to db9ae39 Compare October 26, 2026 22:36
@timothy-mccormack
timothy-mccormack force-pushed the pt-4885-empty-verse-caret-reflow branch from 17440eb to 794b95c Compare October 26, 2026 22:36
@timothy-mccormack
timothy-mccormack marked this pull request as ready for review October 27, 2026 00:38
- Tests for typing at host offset 1, blur staying out of undo and the
  USJ-change handler, and $caretAtParaStart/$caretAtParaEnd with a host
  (each fails if its behavior is reverted).
- A host undo restored is removed on blur, or when the caret leaves it,
  even if no selection change adopted it first.
- The delta fast path diffs the previous node from its delta-doc
  contribution, so an empty char span's stand-in no longer deletes the
  next verse either.
- The focus re-host flushes pending updates before deciding, and does
  nothing once its effect is torn down.
- CaretHostRepair returns void; the $repairPast wrapper is gone;
  $hasCaretHostMark moves to the PR that uses it.
- Docs, comments and test placement brought in line with the code.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@timothy-mccormack
timothy-mccormack force-pushed the pt-4885-empty-verse-caret-reflow branch from 794b95c to 0d19617 Compare October 27, 2026 02:07

@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, Timothy. The diagnosis in the description is right, and the fix works where it's aimed:

  • No reflow, caret after the number. In the platform demo (Paragraph Structure view), I put the caret in each of 40 empty verses at 21 widths from 170 to 470px: 840 placements. No verse number moved, and the caret was always drawn right after its number. A second run at wider widths, in both LTR and RTL, gave the same result.
  • Both host CSS rules are needed. Removing the word joiner moved 21–30 of 40 verses, and removing text-wrap-mode: nowrap moved 33–40. The comment's claim that a run of empty verses has no other break opportunity is correct.
  • The TS changes are guarded by tests. Dropping the host self-exemption fails 4 tests, and reverting the ActiveTextPlugin change fails 1.

I've left inline comments with the Medium and Low items. Two Medium items should be addressed before merge: the Markers view reflow and Delete with protection off. Several of the Low items come from the host now surviving between two verses, which is the point of the fix. Where one already happens on main at a paragraph-end host, I've said so.

Everything was rechecked on 0d196171, after the rebase onto #33's latest commit.

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


Low: "Known limitations" understates the arrow-key behavior, which this PR makes common.

  • Dead ArrowRight: every empty verse followed by another verse now costs one ArrowRight press that does nothing visible. From host offset 0 the caret moves to offset 1, which is drawn at the same x. This happens in Simple and Formatted views; ArrowLeft is fine.
  • Shift+ArrowRight never extends, and not just on the first press. Each press selects the placeholder. The guard reads that range as having left the host and collapses it back. After 3 presses the selection was still collapsed at (host, 0).
  • Already on main at a paragraph-end host. This PR makes it the common case.

Suggest correcting the limitation to "every Shift+Arrow press", adding the dead ArrowRight, and ticketing both against the host machinery.

Comment thread packages/platform/src/usj-nodes.css Resolved
Comment thread packages/platform/src/usj-nodes.css Resolved
Comment thread packages/platform/src/usj-nodes.css Resolved
timothy-mccormack and others added 2 commits October 27, 2026 09:23
…rdening

# Conflicts:
#	packages/platform/dist/index.js
#	packages/platform/dist/index.js.map
…ty verse

In Simple (paragraph-structure) view, placing the insertion point in an empty verse reflowed the line, and drew the caret at the start of the next line instead of right after the verse number, although typed text landed in the right place.

Two causes:

- TextSpacingPlugin added its structural trailing space to the caret host that EmptyVerseCaretGuardPlugin puts after an empty verse's number. Spaced, the host looked typed into, so it was stripped and removed in the update that created it, and the caret fell back to the element point between two verse markers, which Chromium draws at the start of the next verse. That is the next line when the empty verse ends one. The host is now exempt, and text pasted in front of one is spaced against the verse past it.
- ActiveTextPlugin dropped the active verse's ellipsis. That shrank the line, and exposed the verse number's trailing zero-width space as a new line-break opportunity. A run of empty verses otherwise has none, so it wraps only where it overflows.

The active empty verse now gets psc-empty-text-active instead of losing psc-empty-text. The stylesheet keeps its ellipsis in place but transparent, as a fixed-width box. The caret host is pulled back over it by a margin of the same width and pushes what follows forward by the same amount, so it takes no room of its own and its caret is drawn right after the number. The host doesn't wrap and ends in a word joiner, so its zero-width space adds no break opportunity. The box rules skip visible-marker verses, whose ::after is the number itself.

Builds on the caret host hardening, which made a host that stays alive between verses safe.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- Mirror the caret-host mark onto the host's DOM as `data-caret-host`, and
  target the stylesheet's host rules at it. The no-wrap rules now apply in
  every view (Markers view reflowed), and real whitespace after a verse no
  longer matches.
- With structure protection off, a delete from an empty verse's host runs
  from the boundary the host stands for, so it reaches the verse marker
  instead of only removing the placeholder.
- TextSpacingPlugin looks past a host for a whitespace-only verse, a pasted
  char span before the next verse, and an annotation over a resting host, so
  each change lands in the commit the app hears about.
- ActiveTextPlugin draws no focus box after a blur, leaves clicks in an
  editable verse marker and double-clicks alone, and clicks into an
  existing host.
- Pin the empty-verse CSS contract, test both transform mount orders, add a
  CHANGELOG entry, and fix comments.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@timothy-mccormack
timothy-mccormack force-pushed the pt-4885-empty-verse-caret-reflow branch from 0d19617 to f497fe8 Compare October 27, 2026 14:11
@timothy-mccormack

Copy link
Copy Markdown
Contributor Author

On the arrow-key item in your summary: I corrected the description's known limitations. They now list the dead ArrowRight press, and say Shift+Arrow never extends on any press. Both come from the host machinery and are already on main at a paragraph-end host. Whether to ticket them is Tim's call. Each inline comment has its own reply; the changes are in f497fe8, rebased onto #33's merge of main.

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

Approving because there is nothing worth blocking the merge over. There are three things you may want to consider changing. The PR will still be approved and mergeable even if you make another commit to fix the three.

  1. An empty verse at the end of a paragraph now merges paragraphs on Delete. With protection off, Delete from there merges the next paragraph in and silently drops its marker (\q in my probe). Before this commit it did nothing.
    • My probe showed an ordinary paragraph-end Delete in that mode does the same, so this is consistent.
    • But it isn't tested, and the TSDoc on $deleteFromEmptyVerseHost only mentions reaching the verse marker. It's worth a test and a sentence there.
  2. Only single-character deletes are redirected. Ctrl+Delete and Ctrl+Backspace from the host probably still remove only the placeholder. I couldn't check this, because jsdom can't run word deletes. It's worth a manual check in the app.
  3. Nit: the same mutation listener is registered three times. Each of the three caret guards that use useTransientCaretHost registers it. Each copy runs over every text-node change on every commit, doing the same work.

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

…te listener

- Word and line deletes from an empty verse's host are redirected to the
  boundary the host stands for, like character deletes. Run from the host,
  they removed only the placeholder.
- Document and test what a forward delete does from an empty verse ending
  a paragraph with protection off: it merges the next paragraph in, as
  Delete at the end of any paragraph does in that mode.
- Register the host-attribute mutation listener once per editor rather
  than once per caret guard.

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

Copy link
Copy Markdown
Contributor Author

All three are handled in 92011d2.

  1. Delete from an empty verse that ends a paragraph: a new test runs it with protection off, and $deleteFromEmptyVerseHost's doc now says what happens. The next paragraph merges in and its marker goes, as Delete at the end of any paragraph does in that mode.
  2. Word and line deletes: DELETE_WORD_COMMAND and DELETE_LINE_COMMAND now get the same redirect as DELETE_CHARACTER_COMMAND: the host is removed and the delete runs from its boundary. jsdom can't extend a selection by word, so the four new tests intercept the re-dispatched command and check it starts at the boundary rather than in the host. Tim checked it by hand in Paratext 10 Studio on macOS, in Simple mode. Option+Delete, Option+Backspace and Cmd+Backspace from an empty verse each behave like plain Delete or Backspace there: the structure protection arms the verse marker, and a second press deletes it.
  3. The listener registered three times: the host-attribute listener is now registered once per editor and shared by all the guards, with a holder count so it's removed when the last one unmounts.

Locally: shared 895, shared-react 2291 and platform 4134 pass; typecheck, lint and prettier clean; committed dist verified.

Base automatically changed from pt-4885-caret-host-hardening to main October 27, 2026 15:33

@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 fixing those, Tim!

@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 da56685 into main Oct 27, 2026
8 of 9 checks passed
@timothy-mccormack
timothy-mccormack deleted the pt-4885-empty-verse-caret-reflow branch October 27, 2026 16:21
timothy-mccormack added a commit to paranext/paranext-core that referenced this pull request Oct 27, 2026
…ty verse (#2942)

The app styles the editor from its own vendored stylesheet, so the CSS
half of the PT-4885 fix lands here (paranext/scripture-editors#33 and
paranext/scripture-editors#34 carry the editor half). Both vendored
copies, `_usj-nodes.scss` and the demo `usj-nodes.css`, gain the rules:

- The empty-verse ellipsis is a fixed-width box
  (`--psc-empty-verse-ellipsis-width`: 13px in the app copy, deliberately,
  18px in the demo copy). The verse holding the caret keeps it but hides
  it.
- The caret host (`[data-caret-host]`) is pulled back over the hidden
  ellipsis by an equal margin, so the caret is drawn right after the
  number, and in every view a host after a verse takes `nowrap` and a
  trailing word joiner, so the line neither changes width nor wraps.
- The app copy gains the demo copy's RTL `.verse` / `.verse.marker`
  isolation rules, without which the caret was drawn beside the next
  verse's number in RTL projects.

Both headers record where the rules came from. The style tests pin each
load-bearing declaration on its exact selector list.

Checked by hand on macOS in LTR and RTL projects and with forced colors.

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