[tjcouch-sil]

Summary

Editor-side half of Paratext 10's PT-4189 (footnotes edited in the footnotes pane in Standard view; core PR paranext/paranext-core#2805). Additive EditorRef API plus one focus fix; nothing removed.

Moved here from eten-tech-foundation/scripture-editors#556, which is closed with a pointer to this PR. The branch was rebased with --onto so it carries only its own commits; the old base (eten's #531, "apply annotations issued while a load is in flight") is not on this repository's main and did not come across.

Changes

• EditorRef.getNoteIndex(noteKey) — document-order index of a note (the coordinate a USJ-built notes list addresses; the same index noteCallerOnClick reports). $getNoteIndex in shared-react backs it and ImmutableNoteCallerNode reuses it.
• EditorRef.getNoteKey(noteIndex) — the inverse, so a host that addresses notes by index can hand replaceEmbedUpdate a key.
• EditorRef.highlightNote(noteKeyOrIndex | undefined) — applies PT9's caller_highlight class (already in usj-nodes.css) to one note's caller. NoteCallerHighlightPlugin re-applies after every commit (Lexical recreates the caller DOM on collapse toggles and replaceEmbedUpdate re-keys), follows an in-place replacement in the same commit, refuses to adopt a note across an external load, and never dirties the document. Two silent no-op modes are documented in the TSDoc (a note built expanded in editable marker mode has a plain text caller; the address is resolved eagerly, never retried).
• EditorRef.selectNoteTextOffset(noteKeyOrIndex, utf16Offset) — puts the caret at an offset within a note's own text, counting the note's content only. Every display artifact the active ViewOptions add around that content is skipped: marker glyphs in either marker mode, attribute display runs, engine-owned NBSP spacers, an opening glyph's NBSP separator prefix, and an expanded editable note's caller. See Why this belongs in the editor below.
• EditorRef.selectAfterNote(noteKeyOrIndex) — puts the caret immediately after a note (past its caller in a collapsed note), where PT9 leaves it once the user is done reading. Like applyUpdate, it carries SKIP_DOM_SELECTION_TAG when this editor's root does not hold DOM focus, so a host can park the Scripture caret while the user keeps typing in a note editor elsewhere; the selection is still recorded, so a later focus() lands on it. It skips a following GLYPH text node: a glyph's bytes are a picture of its own state (a verse number, a marker's syntax), so offset 0 there is a position inside the picture that the next keystroke splits — exactly what $normalizeSelectionOutOfGlyphText exists to prevent, and a note ending a verse is followed by precisely such a node. Those notes take the parent-offset branch instead.
• $getNoteIndex moves to its own leaf module (note-index.utils), re-exported from note.utils. ImmutableNoteCallerNode needs the index and note.utils needs ImmutableNoteCallerNode, so the two imported each other — which works only while every use stays inside a function body; the first module-level use, or a CJS evaluation order that loads the caller node first, fails at load with an uninitialized binding. No API change.
• A "category" field on selectNoteTextOffset (round 8, below).
• MarginalRef delegates all of them.
• Fixed: applyUpdate / replaceEmbedUpdate tag the update with SKIP_DOM_SELECTION_TAG when the editor does not hold DOM focus, so a host editing a note in a separate editor (the pane row editor) keeps its caret; explicit caret APIs (focus, setSelection, selectNote) are unchanged. Test fails without the tag. That rule now has one name (holdsDomFocus) shared by both sites rather than two copies.
• API report and CHANGELOG (Unreleased) updated. No version bump (release workflow owns it).
• Refactor: how many leading code units of a text node are an opening glyph's display separator is now read in one place, $separatorPrefixLength in markerSeparators.utils.ts, which already owns that convention. Three sites derived it independently: the note caret offset behind selectNoteTextOffset, $selectCharContentStart, and the collab emit path's note-content strip. The emit path keeps its narrower positional rule on top (only the span's own opener, its first child), so the ops it sends are unchanged. $selectCharContentStart now skips a leading NBSP only in the separator slot. Every caller already hands it the text straight after a span's opener, so their results do not change. New unit tests pin each guard in the helper; removing any one of them fails a test.
• The committed packages/platform/dist is rebuilt in its own commit. This repository commits each published package's build output so paranext-core can copy it out of a checkout without running this toolchain; eten-tech-foundation's did not, so the branch arrived without that rebuild.

Why selectNoteTextOffset belongs in the editor

The host captures a caret position over its own read-only rendering of a note (a footnotes pane row) and needs it resolved inside a live editor showing the same note. It was doing that by walking the editor's DOM behind a text-node filter — which worked only for the marker mode that filter had been verified against. Under markerMode: "editable" an opening glyph is a real editable text node inside the char span, and the span's first text child carries the NBSP display separator as a prefix; the walk counted both as note text, so every run shifted the caret, compounding per run. A prefix of a node cannot be dropped by a per-node filter at all.

Only the editor can tell its own display artifacts from content, by node type, so that is where the resolution now lives. The offset origin becomes the note's USJ text — stable across marker modes — which is what makes the two renderings agree.

Known gap, TODO(PT-4322): text a source wrote directly inside a note rather than inside an \ft-style run is not counted, because the walk requires a char-span ancestor (which is also what excludes the caller). A host that renders such text inline still drifts by its length.

Round 5 — automated review passes

Two /code-review passes over this branch and its consumer. Three fixes landed here, one of them a
behavior change in the shared ScriptureReferencePlugin that needed a decision first.

A caret before a verse number belongs to the verse before it (c73ed3d6)

The reported symptom is in the consumer: picking a footnote whose caller sits at the end of its
verse sent the Scripture caret back to the start of that verse. It is the common shape — a footnote
usually hangs off the verse's last word, so the next \v follows the note directly.

selectAfterNote parks the caret just past the note, which for such a note is the slot the next
verse's marker occupies. The host then publishes the note's own verse, and the plugin read that slot
as being in the next verse — so the publish looked like a cross-verse navigation and the plugin
moved the caret to the note's verse start.

The fix is here rather than in the host because the disagreement is internal to the plugin every
view shares: two readings of "which verse is the caret in" had drifted apart.

• $getEffectiveVerseForBcv treated a caret inside an editable verse marker as past the verse
  number unless the marker's text started with that number. Standard and Unformatted views render
  the whole marker (\v 3 ) as the verse node's text, so every position in it — offset 0 included,
  which is exactly where a verse-final note leaves the caret — read as the new verse.
  getVerseNumberPrefixLength now ends the prefix where the number does, wherever in the marker it
  sits, and keeps its documented 0 fallback for text that does not contain the number at all.
• $moveCaretToVerseStart's "already here" no-op read the verse off the caret's node alone
  ($findThisVerse), which is offset-blind, instead of through $resolveVerseNode +
  $getEffectiveVerseForBcv — the resolution $resolvePosition reports positions with. It asks the
  one question one way now, recorded as invariant I9 in that file's header. The no-op is gated
  on a verse node actually being resolved, never on the effective number alone: a document swap
  nulls the selection, which resolves to verse 0, and a navigation to verse 0 must still place a
  caret in the arriving document.

Pinned by three tests in ScriptureReferencePlugin.test.tsx — the caret stays put under editable
markers and under the immutable verse decorator, and navigating to the verse whose marker follows
the note still moves it — plus two in node-react-utils.test.ts for the prefix itself. Each half of
the fix is independently falsifiable: reverting either one fails the new tests.

Also fixed

• highlightNote resolved an index against a stale document (01f63874). It read the committed
  editor state, so a host that inserted or removed a note and highlighted by index in the same turn
  marked the wrong note, or none. It reads with editor.read now, which commits pending updates
  first, as getNoteIndex and getNoteKey already do.
• $selectNote missed an empty note's closer in the Markers view (6d5d1fe3). Selecting an
  expanded note with no content run (\f + \f*) lands the caret just before the closing glyph. The
  closer was found by looking for a closing marker node, which is what markerMode: "editable"
  builds; "visible" builds it as display-only typed text, so the caret went after \f* instead.
  The lookup recognizes both shapes, and a test pins both marker modes.
• A flaky caret test (81e074df): a fresh editor moves its caret to scrRef's verse start a few
  microtasks after the document loads, and the placement tests sometimes acted before that landed,
  overwriting the caret under test (~3 runs in 8). The render helper waits a macrotask for it now.

Round 6 — lyonsil's review (36 findings)

Every finding was checked. 35 are fixed with falsifiable tests. #23 is answered on its thread (a
reload deliberately drops the highlight for the host to re-address). Commits: 01edbdcf (+ dist
81fc0cbc), b8064029 (+ dist 94dcf375), and a0367cc6 (+ dist ab34b2cf) for the empty note.

• Parked carets that focus() could not find (Remove the scribe package #2/Flaky interaction tests: ScriptureReferencePlugin and marker-palette each failed once in CI #3/Separate the published artifact directory from the toolchain's scratch space (both are currently dist/) #5). Lexical 0.43 resets its pending update
  tags only after a commit that changed nodes. A tag on a selection-only commit therefore rides onto
  the NEXT commit: a leftover SKIP_DOM_SELECTION_TAG stopped focus() from focusing anything, and
  a leftover CURSOR_CHANGE_TAG got the next edit dropped from onUsjChange. The skipped DOM write
  also left a stale DOM selection inside the editor, which the next event-less update read back
  over the parked caret. New editorUpdate.utils (releaseTagsAfterNextCommit,
  clearStaleDomSelection, editorHoldsDomFocus, readLatest) fixes this for selectAfterNote,
  applyUpdate, commitPendingMarkerEdits, and the caret-guard repairs.
• The verse before a marker (Consider committing built dist/ like platform-bible-react, so consumers stop building at install time #4/Consume the editor from GitHub release tarballs instead of staged file: copies #6/PT-4313: Compensate every indented paragraph marker in the gutter view #10). A caret before a verse number reports the chapter's
  actual previous verse node (bridge 1-2, segment 2a, omitted verse) rather than number−1.
  $moveCaretToVerseStart asks $resolvePosition, so a heading before verse 1 is "already here"
  for verse 0.
• Typing into an empty note (Adopt this repository into the paranext organization #1). In a host's note editor, a keystroke typed into \f + \f* landed
  inside the closing glyph (x\f*): shown, never saved. A new EmptyNoteCaretGuardPlugin gives the
  content slot a transient caret host, so what is typed becomes the note's plain content
  (\f + x\f*). It acts only where the caller is protected from typing; where the caller is editable
  text, the end of it stays the caller's.
• Note caret APIs (Re-add transfer guide #7/PT-4752: Give the caret host identity in editor state #20/Read a press's button without naming PointerEvent #21). selectNote lands ahead of an explicitly closed last run's
  closer. selectNoteTextOffset counts text written directly in the note and never lands in an
  unmatched closer's glyph.
• Reads from inside an update (PT-4304: Add read-only block-verse view mode (#538) #8/Rebuild the committed platform dist after PT-4304 #9). getNoteIndex, getNoteKey and highlightNote read the
  in-flight state there instead of committing (and freezing) it.
• Also: the host is told about a caret parked while unfocused (PT-4197: Data-fidelity audit — composed round trip, USX-first net, corpus #29). commitPendingMarkerEdits
  settles without taking focus back (the host now settles the text on entering its pane, which
  retires PT-4370: Settled positions across the public position API #11's idle-settle focus steal). The highlight falls back to an editable caller (PT-4540: Make a paragraph's gutter marker selectable #22) and
  skips its walks when nothing was created (Rest the caret at an empty verse's editable marker, not between markers #24). Plus the TSDoc/refactor/test-hygiene items
  (Put a fallback chain behind every font the project stylesheet names #12/Fix the editor context menu and \id-line editing #14–PT-4537: Keep a visible caret in an empty verse #16/PT-4313: Mirror the core review of the gutter coverage test #18/Let a host suspend the gesture-free marker-settle clocks (unblocks PT-4611) #25–Treat implied paragraphs as transparent in USJ selection locations #28/PT-4121: Keep paragraph markers when the structure is locked #30–PT-4885: Keep the line still and the caret after the number in an empty verse #34/PT-4391: Keep a lone ~ between markers on save in every view #36–PT-4965: Put chapter 1's verses in a paragraph #40).

Round 7 — lyonsil's follow-ups (10 findings)

Every finding was checked against the code, and each fix has a test that fails without it. Replies
are on each thread. Commits: 59f95510, ba573d98, 7c75f96c, 8dfcc2dd, 7c5a7d11; dist
6c41a065, c3f5ea80 (verify-committed-dist clean). All three data-loss fixes below were already
on main, not introduced by this PR.

• A nested span that opens a run was lost on load (found while fixing R2-1). $applyUpdate
  built a run's first-op nested span with its glyphs beside it instead of inside it, and the
  marker engine then read them as the outer run's text: a note loaded into the footnote popover or
  a pane row as \ft \+nd LORD\+nd* said saved back as \ft LORD said on any edit. It now builds
  the same shape as a nested span mid-run, and text continuing a closed run goes inside its closer.
• Typing after an editable caller leaked the caller into content (PT-4974: Export the font part of the project stylesheet as generateUsjFontCss #42). What follows the
  caller's trailing separator is split into its own content node in the same commit, the caret
  following it.
• Keystrokes dropped from onUsjChange after a caret-only commit (PT-4911: Hidden-marker views copy prose and filter \ and // on paste #41, R2-2, R2-3). The scrRef
  placement and both caret guards release their cursor-change tag after committing; the scrRef one
  only when the caret actually moved.
• selectNote in a run holding a nested span (R2-1). Only a span's last child counts as its
  closing glyph.
• Unfocused-update paths (R2-4..R2-7). isFocused() uses the same focus check as the rest of
  EditorRef; the tag-release listener is disarmed when an update commits nothing; a DOM selection
  that matches Lexical's survives an unfocused update; an unfocused selectAfterNote reports the new
  verse through onScrRefChange.
• Smaller: the right-click menu claims the Escape that closes it, which the core PR's
  FootnoteEditor relies on; plugin order (R2-8).

Round 8 — fixes from TJ's hand QA (2026-09-25)

Commits acec819e..0e39a7f4, dist 0bab2a75 (verify-committed-dist clean), docs 791cf00f, 70291f25. Each fix has a test that fails without it.

• Text written directly in a note was lost when applied to a collapsed view (A5). NoteNodePlugin reset every plain text child of a collapsed note to the NBSP spacer, so the pane row editor's apply of \f + x\ft a\f* (or \f + x\f*) dropped the x. The apply still replaced the note node, so the host's session key stopped resolving and nothing saved again until the row was reopened. Only tagged spacers (and text the caret is typing into) are reset now. This also affected the round-6 empty-note typing (\f + \f* → plain content) once it reached the Scripture editor.
• A range could remove the protected note shell (A5). A double-click on the caller, a drag from the shell into the content, or select-all was grown to take in the whole \f + , and typing or deleting over it unwrapped the note. NoteShellCaretGuardPlugin now narrows such a range to the note's content; one wholly inside the shell collapses to its trailing edge.
• No caret past a note that ends an unclosed char span (A6). \p asdf \wj stuff\f + …\f* with no \wj*: a click past the end of the line lost the caret and focus, because the trailing-note guard only handled a note directly in its paragraph. It now walks up through inline ancestors that render nothing after the note. ArrowRight into the same spot left an invisible caret in the note's hidden closer; that landing now stays past the note.
• Deleting the backslash of an undeclared marker did nothing (B5). A char span whose marker the stylesheet does not declare (\df) was always kept whole through a Tier 2 rebuild, so the edited glyph never reached the tokenizer and was healed back to \+df. It is kept whole only while its own glyphs still spell it.
• Typing inside an existing note was reported as inserting it (A1). onUsjChange's insertedNodeKey is now reported only for a node the previous editor state did not have. This is what made the core host open the row editor at the end of an unclosed note the user was typing in.
• New API: selectNoteTextOffset(noteKeyOrIndex, utf16Offset, field?: "category") addresses a note's \cat value (C5); MarginalRef delegates it. (A getNoteCaret() added for a first cut of A1 was removed again in 0e690064, dist c73f9827: the host now edits an unclosed note in place, as PT9 does, so nothing reads it.) A new test pins an unclosed note staying unclosed and expanded through a note editor's apply.

Round 9 — TJ's round-8 hand QA (2026-09-28)

Commits fd45e7b2..2e6060ff, changelog, dist (verify-committed-dist clean). Each fix has a test that fails without it.

• An unclosed note's caller can be deleted (e3c2af75): the caller pattern needed a non-empty word, the whitespace display and the caller transform then looped over the empty slot, and the reverse adaptor leaked the slot's spaces into content. The caller slot is found by position (noteCallerSlot.utils.ts), the note keeps caller "", and the text shows \f \fr …. $createWholeNote builds the caller slot for an empty caller in editable expanded mode too. The "empty caller, only for note editing" warning is gone.
• Typing a note's own closer closes an unclosed note (9f29be04): the note-scoped rebuild tokenized the content without the note's opener, so \f* came back unmatched. It now closes the note there (collapsed in Standard view) and moves what followed the closer after the note; the read-only settle mirrors it.
• Caret after a typed undeclared marker (9f29be04): the caret restore counted a freshly built \df span (a Tier 2 sentinel) as one placeholder byte while the position was measured over its typed bytes, so the caret landed in the next closing glyph and later keystrokes edited it. Spans the rebuild did not preserve are counted byte by byte (FragmentAccumulator.preservedKeys).
• A drag across a protected shell (fd45e7b2): the edit commands narrow the range first, since Lexical re-reads a still-dragging range from the DOM for the edit.
• Caret inside a marker glyph (2e6060ff): selectNoteTextOffset(noteKeyOrIndex, utf16Offset, options?: { field?: "category"; glyph?: { index; offset } }) — replaces this PR's bare field argument, so nothing released changes.

Round 14 — lyonsil's round-13 follow-ups, and brought up to date with main (2026-10-12)

• Text typed right after a note's closing glyph was lost (follow-ups on Adopt this repository into the paranext organization #1 and Separate the published artifact directory from the toolchain's scratch space (both are currently dist/) #5) (3ef69481). A browser reading back a caret at the end of a line a note ends resolves it to the end of the note's \f*, so the next keystroke became \f*Z: invisible in a collapsed note and missing from getUsj() in every view. That covers clicking at the end of such a line in Unformatted view (already on main) and typing after closing a note that ends an unclosed \wj. Tier 1's split of text typed after a char span's own closer now also covers a note's own closer, so the text moves after the note as it is typed. Three tests put the caret where the readback lands (jsdom never reads it back), and each fails without the fix.
• Merged main (2acc7a02: Fix the editor context menu and \id-line editing #14 \id-line editing, Rest the caret at an empty verse's editable marker, not between markers #24 empty-verse caret). Conflicts were in this branch's settle code and were resolved by keeping both sides: the branch's note close and preservedKeys caret restore next to main's book-line rebuild, which now passes preservedKeys too. 3da2cc5d stubs Range rects in applyUpdateDomSelection.test.tsx, since main's caret change makes its focused case scroll a collapsed caret. Dist 7a4d6568; verify-committed-dist is clean.
• Gates: platform-editor 2346 / 3 skipped, shared-react 1766 / 1 skipped, shared 713, utilities 56. nx run-many -t typecheck lint is clean.

Round 13 — lyonsil's review at 8f97b1be (2026-10-01)

Commits ec1de9f0, 4bcb4a9d, 3bcb062e, 68fc5d6a, bff1152f (verify-committed-dist clean). Each fix has a test that fails without it. The 20 findings: fixed 1–5, 8, 10–17, 19–21 and 18 (a different way, below); declined 6 and 9.

• Note-shell deletes in a note editor (2, 3, 12). A forward Delete just before the note no longer removes its opening glyph and dissolves the note; a forward Delete right after the caller deletes the first content character; a forward line delete over wrapped content stops at the visual line instead of the closer.
• Caret after a note (1, 5). Typing \f* in a view that shows notes expanded leaves the caret after the note. selectAfterNote on a note that ends an unclosed \wj no longer descends into the note. Closing a note inside an unclosed span is reported through onUsjChange (a caret announcement tagged that commit as a caret move, so the close never reached the host).
• Reentrant calls (4, 17). takeOpsAfterNote called from onUsjChange reported stale state and, in the new test, looped without end; the apply now reports from the update's own onUpdate. The note-op reads use readLatest, so they are safe from onSelectionChange.
• A space typed after a note's caller (18). Standard view collapses space runs when it saves; this run was split across the caller and the content, so it saved as content. It now collapses on save, as Paratext 9 reformats \f + text to \f + text. A note with a category keeps it (it follows \cat*), and a no-break space stays.
• Two found while checking the clipboard E2E, which failed the same way on 8f97b1be. A range whose end lands inside a collapsed note (select to the end of the document from a paragraph a footnote ends) took half the note, so copy carried \f + without the content. It now takes the whole note. End, Ctrl+End and Cmd+Down in such a block selected the note instead of leaving the caret past it, so the next paste replaced it; the guard turns that into a caret past the note.
• Refactors and test style (8, 10, 11, 13, 19, 20, 21), CHANGELOG (14–16). Done. Declined: 6 (merging the closing-marker checks changes behaviour at each use) and 9 (a speed-up that needs a second record of which notes are protected). We are keeping the CHANGELOG, best-effort until it is complete.

Hand QA for this round (Standard view, Power mode, project editable; both PRs) — run by TJ 2026-10-12

1. Pane too small for a long note. Drag the footnotes pane to about one row tall. Press Enter on a long note's row, and click its caller in the text: the caret at the end of the note stays visible.
2. Pane beside the text. Change footnote pane location to beside the text. Scroll mid-chapter, then close the pane with its X and reopen it with Toggle Footnotes: the verses in view stay the same each time.
3. A closer typed mid-note, then undo and redo. In an unclosed note's row editor type \f* in the middle. Press Escape at once: the text after the closer is in the paragraph after the note, once. Repeat, but wait, then Ctrl+Z and Ctrl+Y in the row editor: the text moves into and out of the note each time, with no loop and no doubled text.
4. Closing a note inside an unclosed span. Make an unclosed \wj that ends in an unclosed footnote, and type \f* at the end of the footnote. The footnote closes and the change saves (reload the chapter). If the caret ends inside the footnote rather than after it, tell me.
5. Unformatted (Markers) view. Type \f* to close an inline note and keep typing: the new text goes in the paragraph, not the note's last run.
6. A space after the caller. In Markers view put the caret right after \f + and type a space. The space shows while editing; after saving and reloading it is gone. \f + xy saves as \f + xy.
7. Row editor deletes. In a note's row editor: arrow left out of the content to just before the note, then Delete: the note stays. Click right after the caller and press Delete: the first content character goes. In a note wrapped over several lines, a line delete stops at the visual line.
8. End key at a paragraph a footnote ends. In a paragraph that ends with a footnote press End, and in a chapter ending with one press Ctrl+End (Cmd+Down on a Mac): the caret is after the note, and typing or pasting goes after it. Then Ctrl+Home, Ctrl+Shift+End and copy: the clipboard holds the whole note.

Run by TJ 2026-10-12: 1-4, 7 and 8 passed. 5 and 6 can't be run as written: the app's Markers view is read-only (only the dev-editableMarkersView developer flag makes it editable). Users reach both cases only on an unclosed note in Standard view, which the text shows expanded, and tests already cover that case. For item 5, the caret landing after the closed note is item 4, which passed by hand, and the unclosed-note-close-undo E2E covers the text after the closer moving into the paragraph. Item 6's save is unit-tested in markerEditTier1.utils.test.tsx with Standard view's options and the note expanded. The collapse belongs to Standard view's whitespace rules, so it would not apply in Markers view anyway; the step named the wrong view.

Brought up to date with main (2026-09-30)

Merge 8f97b1be (#23, copy limit). Only the committed dist conflicted; it was rebuilt, and verify-committed-dist is clean. After the merge: platform-editor 2228 / 3 skipped and shared-react 1684 / 1 skipped pass; nx run-many -t typecheck lint and prettier --check . are clean.

Round 12 — TJ's round-11 hand QA (2026-09-30)

Commit 1a113a8e, dist 4ee4314e (verify-committed-dist clean).

• An undo of a closer typed into an unclosed note also removed the text typed just before it. In the app the marker palette commits \f* and the close in one update. Round 11's merge tag on the close joined that update to the previous undo step. The close is its own undo step again; a note editor's takeOpsAfterNote still joins it. The tests now commit the closer through commitTypedCloser after a separate typing step, as the hosts do.
• The close keeps the same note node. Content and attributes move into the existing note instead of a new one, so onUsjChange no longer reports the closed note as inserted. Hosts open their new-note editor on an inserted note.

Round 11 — TJ's round-10 hand QA (2026-09-30)

Commits 50aa4947, 91c76e55, dist e9d665ad (verify-committed-dist clean). Each fix has a test that fails without it.

• EditorRef.takeOpsAfterNote (50aa4947): removes what follows a note in its paragraph and returns its ops, merged into the undo step of the edit that left the text there. A note editor that closed its note mid-note gets one undo that opens the note again with the text inside. Before, undo put the text back after the note, where the host took it again. (Round 11 also merged the close itself into the closer's typing step; round 12 reverts that.)
• The closer in a note editor is protected like the opener (91c76e55, NoteShellCaretGuardPlugin). Before, a caret after \f* or at the row end stayed there, Backspace from there deleted the closer, forward Delete ran into it, and typing over a range inside it prepended to it. Now such a caret goes to the content's end, as a text point, because an element point at the closer's index resolves into the closer. Deletes there move the caret instead of deleting. A forward delete with nothing before the closer is refused, and a word or line delete stops at it. Only range narrowing existed for the closer before this change, as far back as the guard goes.

Round 10 — TJ's round-9 hand QA (2026-09-28)

Commits c76b532f..b834e3bc, dist 33e0bce1 (verify-committed-dist clean). Each fix has a test that fails without it.

• Deletes at a protected shell's edge (c76b532f): with the caret at the shell's trailing edge (where a drag or a click in the shell leaves it), Backspace, a word delete or a line delete took the caller token. Refused, or stopped at the shell's edge.
• Forward Delete through an opening glyph (984d92a3): the press removing a glyph's last character also removed the separator, and $charTextNodeTransform read the separator NBSP as the empty-char placeholder and jumped the caret to the span's end. One character per press now, caret in place.
• Undeclared marker typed in a note with \cat (e6ccf4cf): a note rebuild spliced the sentinel \df span back inside the open \ft, and the caret restore landed on \cat. Inside a note an undeclared span is re-tokenized, since the tokenizer reads it as a char span there. (Paragraph context still keeps it whole.)
• getOpsAfterNote (b834e3bc): reads what follows a note in its paragraph; $getReplaceEmbedOps deletes the old embed before further inserts, so a note editor that closed its note mid-note can apply the rest after the note.

Brought up to date with main (2026-09-24)

origin/main is merged in (a48bcf79), picking up #13 (copy/paste fidelity), #18, and #21. Conflicts: Editor.tsx insertNote now uses main's discrete update together with this branch's $rememberExpandedNote. CHANGELOG.md keeps both sides' Fixed entries. The committed packages/platform/dist is rebuilt, and verify-committed-dist passes.

Testing

Full local run of what CI runs, at the rebased tip:

• nx run-many -t test — all 9 projects green: @eten-tech-foundation/platform-editor 1714, shared-react 1654 (1 skipped), shared 675, utilities 56, plus the demos. After the separator-prefix refactor: platform-editor 1718, shared-react 1654 (1 skipped), shared 684, utilities 56, plus typecheck and lint, and verify-committed-dist is clean at 6ad4a091. Includes noteIndexAndHighlight.test.tsx, applyUpdateDomSelection.test.tsx, and noteCaretPlacement.test.tsx — the last renders under STANDARD_VIEW_MODE, i.e. markerMode: "editable", deliberately (that is the mode the caret bug lived in), and — since the review pass — under the expanded note mode a host's own note editor actually uses.
• nx run-many -t typecheck lint, prettier --check ., nx format:check
• node scripts/rebuild-committed-output.mjs followed by node scripts/verify-committed-dist.mjs — the committed output is current and reproduces byte-for-byte on a second rebuild
• At the merged tip (a48bcf79): nx run-many -t test all 9 projects green (platform-editor 2005 / 3 skipped, shared-react 1676 / 1 skipped, shared 710, utilities 56), nx run-many -t lint typecheck, prettier --check ., and verify-committed-dist clean
• Round 7 tip (c3f5ea80): platform-editor 2021 / 3 skipped, shared-react 1679 / 1 skipped, shared 710; nx run-many -t typecheck lint and prettier --check clean; verify-committed-dist clean
• Round 12 tip (4ee4314e): platform-editor 2095 / 3 skipped; nx run-many -t typecheck lint clean; verify-committed-dist clean
• Round 11 tip (e9d665ad): platform-editor 2094 / 3 skipped, shared-react 1684 / 1 skipped; nx run-many -t typecheck lint clean; verify-committed-dist clean
• Round 10 tip (33e0bce1): platform-editor 2071 / 3 skipped, shared-react 1684 / 1 skipped, shared 710; nx run-many -t typecheck lint clean; verify-committed-dist clean
• Round 9 tip: platform-editor 2058 / 3 skipped, shared-react 1684 / 1 skipped, shared 710; nx run-many -t typecheck lint clean; verify-committed-dist clean
• Round 8 rework tip (c73f9827): platform-editor 2038 / 3 skipped; nx run-many -t typecheck lint clean; verify-committed-dist clean
• Round 8 tip (70291f25): platform-editor 2042 / 3 skipped, shared-react 1684 / 1 skipped, shared 710; nx run-many -t typecheck lint clean (0 errors); verify-committed-dist clean
• Consumed by the core branch and hand-QA'd there (round 1; the round-2 and round-3 QA of the caret APIs is listed on the core PR)

AI-assisted — session 1, session 2, session 3, session 4, session 5, session 6, session 7, session 8, session 9, session 10, session 11; the human directed scope and reviewed. Round 13: session 12, session 13. Round 14: session 14.

🤖 Generated with Claude Code

---

Code Review Summary — automated pass, 2026-09-16

Review model: Claude Opus 5 (1M context) · Base: origin/main · Files changed: 17

This PR was reviewed together with its consumer, paranext-core#2805 — six parallel
analysis passes in total, two of them (API/correctness, style/tests) on this repo. The full
cross-repo summary, including the core half's findings and the open decisions for the review
meeting, is in the same block on core#2805. Below is what applied here.

Fixed in 5a639930

• A real defect: selectNoteTextOffset's documented no-content fallback landed nowhere.
  $selectNote's expanded branch is getChildren().reverse().find($isCharNode)?.selectEnd(), which
  for a note with no content run at all (\f + \f*) is a complete no-op — the caret stayed outside
  the note and the next keystroke landed in the surrounding text. It now lands at the child slot
  content would occupy, just before the closing glyph. Found by a test written during the review.
  CHANGELOG entry added under Fixed.
• The caret tests ran in a view mode the only consumer never uses. noteCaretPlacement.test.tsx
  rendered under STANDARD_VIEW_MODE, which is noteMode: "collapsed", while the consumer's note
  editor runs noteMode: 'expanded' — a materially different interior, where the adaptor builds the
  caller as a plain TextNode and folds a \cat category into an attribute display run. Both of
  those skips are promised in editor.model.ts and had zero coverage in either repo. An
  expanded describe block now covers the caller skip, the \cat skip, a \fp paragraph-break
  crossing, and the no-content fallback.
• "does not mark the document dirty" tested nothing. onUsjChange fires only when the
  deserialized USJ differs, so a highlight held in node state would dirty the editor and still pass;
  and the test never asserted the highlight applied, so a no-op highlightNote passed it twice
  over. It now counts commits via registerUpdateListener and asserts the highlight landed.
• The glyph-avoidance test asserted only not.toBe("verse"), which also passes for a caret left
  before the note or back in the preceding text. It now asserts the caret's actual position (the
  para-anchored slot immediately after the note). Added the missing positive pre-assertion to
  "clears when the highlighted note leaves the document" too.
• Documentation that had drifted or was missing: selectNoteTextOffset's focus behavior (see
  below) and its collapsed-note constraint; the EXPERIMENTAL: prefix on getNoteIndex,
  getNoteKey and highlightNote; the caller highlight described as "a thin top-and-bottom border"
  in three places when .caller_highlight also paints #ffffb5 (plus a warning that a host
  vendoring its own usj-nodes.css needs the rule, or the API is a silent visual no-op — verified
  core's copies do carry it); and why holdsDomFocus is deliberately broader than isFocused.
• A backward-facing comment asserting a constraint that never existed. The $getNoteIndex
  re-export was annotated "re-exported here because this is where callers have always found it" —
  the symbol was created by this branch's own a88a0dc3 and moved out three commits later, so
  post-merge that reads as a backwards-compatibility constraint nobody would dare remove. It now
  states the real reason (the barrel exports note.utils, not the leaf), and
  NoteCallerHighlightPlugin imports $getNoteIndex from the leaf rather than re-coupling to the
  heavy module.
• A polling comment added to markerMenuHarness.test.tsx read as self-contradictory; reworded to
  name the engine's deferred settle clock, matching its sibling 40 lines above. No behavior change.

Refuted

• selectNoteTextOffset is missing selectAfterNote's SKIP_DOM_SELECTION_TAG focus guard
  was raised as a Critical. The asymmetry is correct, not an omission: selectNoteTextOffset falls
  back to $selectNote, which has never carried the guard, so adding it would make the fallback
  path behave differently from selectNote within the same call. Its job is "put the caret into
  a note this host is about to focus" — the only consumer, placeInitialCaret in core's
  footnote-editor.component.tsx, pairs it with focus() unconditionally. selectAfterNote is the
  opposite case: driving the Scripture caret from the pane, where focus must not move. Fixed as a
  documentation gap instead: the TSDoc now states the asymmetry and tells hosts to pair it with
  focus().

Dismissed, with reasons

• $noteDataTextStart re-derives the NBSP separator-prefix offset that charStack.utils.ts and
  editor-delta.adaptor.ts each derive independently. Centralizing it into one
  $separatorPrefixLength in markerSeparators.utils.ts is right — that module declares itself the
  owner of the representation, and any divergence is silent caret drift — but it touches the emit
  path's stricter variant and belongs in its own change. Flagged for follow-up. (Done
  2026-09-18 in 1097b210. The emit path keeps its stricter rule on top of the shared helper.)
• holdsDomFocus/isFocused unification: documented instead, since changing isFocused's meaning
  affects existing consumers.
• Test-helper duplication (tagsOfUpdatesDuring, renderEditor, the zero-DOMRect Range
  polyfill — now on its 7th copy in the package): a package-wide cleanup, not this PR's.
• getNoteIndex/getNoteKey each walking the whole document: one chapter's worth of notes.
• applyUpdateDomSelection.test.tsx never exercising applyUpdate directly or its source: "remote" branch: a worthwhile addition, but the collab path needs more setup than a review pass
  should improvise. Flagged for follow-up.

Gates after the fixes

• nx run-many -t test --projects=platform-editor,shared-react — 1717 passed (98 files)
• nx run-many -t typecheck lint — pass (2 pre-existing no-console warnings in demos/)
• rebuild-committed-output then verify-committed-dist — clean. etc/platform-editor.api.md
  is unchanged: no public type signature moved.

---

This change is 

[lyonsil]

Round 3 review of this PR at 8f97b1b, covering the whole branch against main: 20 findings. Their numbers are this round's own and do not refer to findings from earlier rounds. Each comment shows the severity the reviewer settled on; 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.

On the CHANGELOG findings (#14, #15, #16): if we'd rather drop the CHANGELOG and rely on the git history, as we do in all our other repos, that would be fine too.

Findings that could not be attached to a line in this diff

#14 (low · checked and confirmed) packages/platform/CHANGELOG.md:145 - The CHANGELOG's Fixed list has no entry for four user-visible fixes this PR makes.

What happens: these commits change behavior a user sees but add nothing under ### Fixed (CHANGELOG.md:145): 984d92a (forward Delete through an opening glyph goes one character at a time), c76b532 (a backward delete at a protected shell's edge keeps the caller), 91c76e5 (a host note editor's closing glyph is protected), and e6ccf4c (an undeclared marker typed in a note stays a sibling of the run it ends).

Why it matters: the CHANGELOG is how a host picking up a new version of this package learns what changed in editing behavior. Its Unreleased entries move under the version heading at publish, so a fix left out now is never recorded.

Fix: add a Fixed entry for each of the four, in the file's existing voice.

How this was checked: All four commits (984d92a, c76b532, 91c76e5, e6ccf4c) are in this PR (none is an ancestor of the merge base), and each is a user-visible fix. I read the whole Unreleased section (packages/platform/CHANGELOG.md:11-260) and grepped for delete, Backspace, separator, closer, closing glyph and undeclared. No entry covers forward Delete through an opening glyph, a backward delete at a protected shell's edge removing the caller, or a note editor's closing glyph being protected. Lines 148 and 149 are about the unclosed-note caller and typing a closer, and line 153 is about the caret after an undeclared marker, not the other three fixes. The nearest entry for e6ccf4c is line 152-153 (caret after typing \df ), but e6ccf4c fixes a different symptom: the undeclared span spliced back inside the open \ft (showing as \+df) in a note with a \cat run, and the caret landing on \cat. So that one is also missing. The anchor line 145 (### Fixed) was not changed by this PR (blame d5412cb is in the base).

Not attached to a line: not on a changed line; cannot be posted inline

(AI-assisted, with my guidance)

[tjcouch-sil]

Round 13 is pushed (ec1de9f0, 4bcb4a9d, 3bcb062e, 68fc5d6a, bff1152f), with a thread reply on each inline finding. Fixed 1–5, 8, 10–17 and 19–21; #18 is fixed a different way (collapse on save); #6 and #9 are declined, with reasons in their threads.

Two bugs outside the review, found while checking the clipboard E2E (clipboard-usfm-round-trip.spec.ts failed the same way on 8f97b1be): a range whose end lands inside a collapsed note took half the note, and End / Ctrl+End in a block a footnote ends selected the note instead of leaving the caret past it. Both are fixed in this round with tests.

CHANGELOG: kept, as best-effort until it is complete (without it, users of the package cannot see what changes between versions).

The hand QA list for this round, covering both PRs, is in the description.

[lyonsil]

@lyonsil reviewed 44 files and all commit messages, made 1 comment, and resolved 17 discussions.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on tjcouch-sil).

[lyonsil]

@lyonsil resolved 2 discussions.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on tjcouch-sil).

[lyonsil]

@lyonsil reviewed 24 files and all commit messages, and made 1 comment.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on tjcouch-sil).