Skip to content

PT-4614: Add no verses above chapter text when starting chapter 1 - #37

Merged
katherinejensen00 merged 5 commits into
mainfrom
pt-4614-first-chapter-text
Oct 28, 2026
Merged

katherinejensen00 merged 5 commits into
mainfrom
pt-4614-first-chapter-text

Conversation

@katherinejensen00

@katherinejensen00 katherinejensen00 commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Summary

EditorRef.insertFirstChapter(verseCount) now leaves the verses out when the chapter content already holds text or a verse. Before, it put them above that content, so a book typed or imported without chapter markers got all its text in the last verse.

Follow-up to #35, from review of the paranext-core half (#2948). The host used to make this call itself, from saved USJ with its own list of front-matter markers, and that list could disagree with where the stylesheet starts chapter content. For \mt1, \b, \ip Intro, the chapter starts at \b (it needs a chapter), the host counted \ip as front matter, and the introduction landed after the last verse. Only the editor knows where chapter content starts, so it now decides both.

Where to look

  • packages/platform/src/editor/markerEdit/firstChapter.utils.ts: $isDocumentText, $holdsChapterContent, and the versesToAdd line in $insertFirstChapter.
  • packages/platform/src/editor/markerEdit/chapterLineEditing.test.tsx: the new "over content already in the chapter" block, plus one hidden-markers case.
  • editor.model.ts doc and the CHANGELOG's Unreleased entry for insertFirstChapter.
  • The second commit is the dist rebuild.

Details

  • What counts: anything from where \c 1 goes to the end of the document: text, a verse, a note, a milestone, or a figure, table or other block the editor keeps whole. A section heading or a em counts too, since anything there already belongs to chapter 1.
  • What doesn't count: display glyphs (markers, attribute runs, a note's caller; the shared $isDisplayAnnotationCarrier), whitespace, a zero-width space, and no-break spaces, including Standard view's ~. So an empty paragraph still gets its verses, and the result is the same in every view mode.
  • Callers that ask for no verses (the \ menu and the \c marker action) skip the scan.
  • The caret with no verses follows the existing rule: end of the chapter line where markers show, else the start of the following paragraph.

AI Involvement

Written with Claude Code (Claude Opus 5.5) and reviewed by a separate adversarial review pass, whose findings were fixed before opening. The author chose to move this decision into the editor. Commits carry Co-Authored-By trailers.

Testing

  • chapterLineEditing.test.tsx: 124 passed, including new cases for text, text past the start block (the \b/\ip example), an existing verse, an empty paragraph, whitespace and a zero-width space only, titled front matter, and text in a hidden-markers view, a heading only, and, in all three views, an uncaptioned figure, a milestone, an empty footnote and a paragraph of no-break spaces. Mutation-checked: removing any one content check (verse, note, milestone, figure, display glyphs, Standard view's ~) turns tests red.
  • ESLint on the changed files, and tsc on the package's lib config.
  • The full packages/platform suite runs in CI.

Risk Level

Low. Only insertFirstChapter with a verse count changes, and only where the chapter content already holds something.

🤖 Generated with Claude Code


This change is Reviewable

katherinejensen00 and others added 2 commits October 27, 2026 16:14
`insertFirstChapter(verseCount)` put its empty verses above whatever
followed the front matter. A book typed or imported without chapter
markers already holds its text there, so all of it ended up in the last
verse. The host tried to prevent that with its own list of front-matter
markers, which could disagree with where the stylesheet starts chapter
content: for `\mt1`, `\b`, `\ip Intro`, the chapter starts at `\b`, the
host counted `\ip` as front matter, and the introduction landed after
the last verse.

The editor now leaves the verses out itself when the chapter content,
from where `\c 1` goes to the end of the document, already holds text
or a verse. Markers, whitespace and caret-holding zero-width spaces are
not text, so an empty paragraph still gets its verses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@irahopkinson irahopkinson left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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


a discussion (no related file):
I reviewed the source changes in this PR (firstChapter.utils.ts, its tests, the EditorRef.insertFirstChapter doc and the changelog entry), and checked that the rebuilt dist matches the source. There are 7 findings, each as its own comment on the line it concerns. Each comment shows the severity it settled at; checked and confirmed means the finding was verified against the code, and needs a human call means it could not be settled either way and is yours to judge.

(AI-assisted, with my guidance)


packages/platform/src/editor/markerEdit/firstChapter.utils.ts line 128 at r1 (raw file):

/**
 * Whether `node` is text of the document, as opposed to a marker glyph, whitespace, a zero-width

#3 - low · checked and confirmed

The $isDocumentText TSDoc says Standard view never saves attribute text, but that text is saved as an attribute value.

What happens: the TSDoc at firstChapter.utils.ts:128 describes attribute display runs as "the attribute text Standard view shows but never saves". That text is saved, just not as running text: \w word|gloss\w* saves lemma="gloss".

Why it matters: maintenance only; a reader could conclude attribute runs are throwaway display and treat them that way elsewhere.

Fix: reword the $isDocumentText TSDoc to "the attribute text Standard view shows, which is saved as an attribute value rather than as text".

How this was checked: The TSDoc at packages/platform/src/editor/markerEdit/firstChapter.utils.ts:128 was added by this PR (git diff shows the line as an addition) and says Standard view shows attribute text "but never saves" it. docs/standard-view-invariants.md:40 lists attribute-run text among the display bytes that make up the document, and the attribute display grammar section (around line 311) describes it round-tripping into attribute values (for example a bare |gloss on \w becomes the lemma attribute). The text is therefore saved, as an attribute value rather than as running text. The code in $isDocumentText is correct; only the comment misleads. Impact is maintenance only.

Other findings in this file: #1, #4, #5, #6, #7


packages/platform/src/editor/markerEdit/firstChapter.utils.ts line 131 at r1 (raw file):

 * space holding a caret, or the attribute text Standard view shows but never saves.
 */
function $isDocumentText(node: LexicalNode): boolean {

#4 - low · checked and confirmed

$isDocumentText keeps its own list of display-only text that $isDisplayAnnotationCarrier already maintains, and the copy treats a note's editable caller as document text where the shared helper does not.

What happens: $isDocumentText (firstChapter.utils.ts:131) hand-lists $isMarkerNode, $isImmutableUnmatchedNode, $isAttributeDisplayRun and an AttributeRunNode ancestor. $isDisplayAnnotationCarrier (libs/shared/src/nodes/features/displayAnnotations.utils.ts:81, exported from shared) already covers all of those; the AttributeRunNode-ancestor arm is redundant, since a run's children are markers and attribute-tagged text. The one difference is a note's editable caller, which the shared helper excludes via $isElementOwnerRunAnchor and $isDocumentText counts as text.

Why it matters: mostly maintenance: each new kind of display text has to be added to every copy, the drift docs/standard-view-invariants.md section II warns about. The caller difference affects only a note whose caller is its only text. With the swap, all 111 tests in chapterLineEditing.test.tsx still pass.

Fix: In $isDocumentText (firstChapter.utils.ts:131), replace the $isMarkerNode, $isImmutableUnmatchedNode, $isAttributeDisplayRun and $findMatchingParent(node, $isAttributeRunNode) checks with !$isDisplayAnnotationCarrier(node) (imported from shared), keeping $isTextNode(node) and the zero-width-space-and-trim() test. Remove the imports that become unused ($findMatchingParent, $isAttributeRunNode, $isMarkerNode, $isImmutableUnmatchedNode, $isAttributeDisplayRun). This stops a note's editable caller from counting as chapter text, so update the PR's description of that edge case to match, and add a case to chapterLineEditing.test.tsx that pins the new behavior for a note whose only text is its caller.

How this was checked: $isDocumentText (firstChapter.utils.ts:131-140, added by this PR) does keep a hand-written copy of the exclusions that $isDisplayAnnotationCarrier (libs/shared/src/nodes/features/displayAnnotations.utils.ts:81-94, exported through shared) already holds. But the two listed gaps change no behavior. Verse glyphs: $holdsChapterContent (firstChapter.utils.ts:148) already returns true on $isSomeVerseNode before $isDocumentText is consulted, so a verse counted as text there is harmless. AttributeRunNode ancestor: its children are marker glyphs and the attribute-tagged value text (AttributeRunNode.ts:10-12), which the carrier already excludes through $isMarkerNode and $isAttributeDisplayRun, so that arm is redundant rather than missing. The one real difference is a note's editable caller, which the carrier excludes and $isDocumentText counts; that affects only a note whose caller is its only text. The swap was run: with the carrier in place of the four exclusions, chapterLineEditing.test.tsx passes (111/111) and eslint is clean on the file. The remaining value is maintenance only.

Other findings in this file: #1, #3, #5, #6, #7


packages/platform/src/editor/markerEdit/firstChapter.utils.ts line 138 at r1 (raw file):

    !$isAttributeDisplayRun(node) &&
    !$findMatchingParent(node, $isAttributeRunNode) &&
    node.getTextContent().replaceAll(ZWSP, "").trim() !== ""

#5 - low · checked and confirmed

A paragraph holding only no-break spaces gets verses inserted above it in Formatted and Paragraph-structure view but none in Standard view.

What happens: Standard view shows each no-break space as the text ~. At firstChapter.utils.ts:138, "~~".trim() is not empty, so $isDocumentText counts it and $insertFirstChapter adds no verses, saving [BOOK, c1, {para p: [NBSP NBSP]}]. In Formatted and Paragraph-structure view the text node holds real no-break spaces, which trim() removes, so the save is [BOOK, c1, v1, v2, {para p: [NBSP NBSP]}]. A paragraph of exactly one no-break space differs the same way, though in those two views that lone no-break space is already dropped on every save, by the exact-NBSP check at editor-usj.adaptor.ts:834, whether or not a chapter is inserted.

Why it matters: the result of inserting chapter 1 depends on which view is open; the input, a paragraph of nothing but no-break spaces, is rare.

Fix: Make $isDocumentText (firstChapter.utils.ts:131) and its caller $holdsChapterContent give the same answer in every view: where the markers show, remove ~ (Standard view's display of a no-break space) along with ZWSP before the trim() at :138, so a paragraph of only no-break spaces counts as empty in all three. Thread the viewOptions that $insertFirstChapter already receives down to $isDocumentText (it currently takes only the node) so the ~ strip applies only where ~ displays a no-break space. Add a test next to the existing $insertFirstChapter tests that runs a paragraph of two no-break spaces in Standard and Formatted view and asserts the same verses are inserted (use two: a lone one is dropped on save in Formatted view), and add an entry under Unreleased in packages/platform/CHANGELOG.md.

How this was checked: Read firstChapter.utils.ts:130-140: $isDocumentText ends with node.getTextContent().replaceAll(ZWSP, "").trim() !== "", and git blame shows line 138 was added by this PR (ceb1755). In Standard view a data no-break space is displayed as the text ~ (editor-usj.adaptor.ts:317 "An NBSP is data (~)", :832 "displayed as ~, never as a bare NBSP node"), and "~".trim() is non-empty, so $holdsChapterContent returns true and no verses are inserted. In Formatted view the text node holds U+00A0, which String.prototype.trim removes, so the paragraph is not counted and verses are inserted above it. The view-dependent result follows directly from the code; I did not run the editor.
Re-checked by running it: a paragraph of two no-break spaces saves with no verses in Standard view and with v1 and v2 above it in Formatted and Paragraph-structure view, and the two no-break spaces survive the save in all three; a lone no-break space is dropped on save in Formatted and Paragraph-structure view even with no chapter inserted (editor-usj.adaptor.ts:834).

Other findings in this file: #1, #3, #4, #6, #7


packages/platform/src/editor/markerEdit/firstChapter.utils.ts line 147 at r1 (raw file):

 * Any text counts, a section heading or a remark included.
 */
function $holdsChapterContent(start: LexicalNode): boolean {

#1 - medium · checked and confirmed

In every view, inserting chapter 1 with verses over content that is only a caption-less figure, a milestone or an empty footnote still puts the verses above it, leaving that content in the last verse.

What happens: $holdsChapterContent (firstChapter.utils.ts:147) returns true only for a verse or a node that passes $isDocumentText (:131), which requires a non-marker text node. A figure with no caption (\p \fig |src="a.jpg"\fig*) has no text node, and a \ts\* milestone and an empty \f + \f* footnote carry only marker glyphs. So versesToAdd (:184) stays at verseCount, and insertFirstChapter(2) saves [BOOK, c1, v1, v2, {para p: [item]}] for each. A captioned figure, or a footnote with text in it, is handled correctly.

Why it matters: this is the failure the change exists to prevent, left open for books whose only chapter content is such an item. The empty footnote fails in Standard view too, so it is not the caller-text edge case the description sets aside. The input is rare.

Fix: In $holdsChapterContent (firstChapter.utils.ts:147), also return true for a note node, a milestone node and a figure node, using the node guards exported from shared; keep returning false for a paragraph's own marker glyph ($isMarkerNode text), a caret's zero-width space and the attribute display text, so an empty \p still gets verses above it (the existing "adds verses above an empty paragraph" test). Add figure-without-caption, milestone and empty-footnote cases to the "over content already in the chapter" block in chapterLineEditing.test.tsx, each expecting [BOOK, CHAPTER_1, para], and add an entry under Unreleased in packages/platform/CHANGELOG.md if the published behavior changes.

How this was checked: Ran a probe that loads [id, {para p: [item]}] and calls insertFirstChapter(2) in Standard, Formatted and Paragraph-structure views. A figure without a caption, a \ts\* milestone and an empty \f + \f* footnote each save as [id, c1, v1, v2, {para p: [item]}] in all three views, so the item lands in the last verse (firstChapter.utils.ts:147-152 returns false because $isDocumentText at :131 needs a non-marker text node; :184-187 then keeps versesToAdd at verseCount). A figure with a caption, and a footnote with text inside, are handled correctly (no verses added). The empty-footnote case is not limited to the disclosed Standard-only caller-text edge: it fails in Standard view too, so it is a real gap rather than the disclosed one. The anchor lines 127-152 are new in this PR.

Other findings in this file: #3, #4, #5, #6, #7


#6 - low · checked and confirmed

$holdsChapterContent builds a full array of each block's subtree before checking it, even though it stops at the first match.

What happens: $holdsChapterContent (firstChapter.utils.ts:147) walks siblings with getNextSibling() and calls $dfs(block) on each; $dfs materializes the whole subtree as an array before the early return true can run. $dfsIterator walks lazily, and libs/shared-react/src/nodes/usj/note-index.utils.ts:19 uses it for that reason.

Why it matters: efficiency and readability only; it runs once per chapter insertion on a document with no chapters yet.

Fix: replace both loops in $holdsChapterContent with one for (const { node } of $dfsIterator(start, $getRoot().getLastDescendant() ?? start)).

How this was checked: $dfs in the installed Lexical utils package is Array.from($dfsIterator(startNode, endNode)) (LexicalUtils.dev.js:449-451), so $holdsChapterContent (firstChapter.utils.ts:147-152) materializes each block's whole subtree before its return true can run. The function does not exist at the merge base, so the code is new in this PR. $getNoteIndex already uses the lazy iterator for this reason (note-index.utils.ts:19-26). $findChapterContentStart returns a root child, so walking from it to the root's last descendant covers the same nodes in the same order as the two loops: its own subtree, then every later sibling's subtree. $dfsIterator includes the end node (LexicalUtils.dev.js:488-516). The cost is small and bounded because it runs once per chapter insertion into a document that has no chapters yet.

Other findings in this file: #1, #3, #4, #5, #7


packages/platform/src/editor/markerEdit/firstChapter.utils.ts line 184 at r1 (raw file):

  const chapterContentStart = $findChapterContentStart(styleInfo);
  const versesToAdd =

#7 - low · checked and confirmed

A book whose chapter content is only a section heading gets chapter 1 with no verses, even when the caller asks for verses.

What happens: for [BOOK, {para s1: ["The Creation"]}], $findChapterContentStart places \c 1 before the \s1. $holdsChapterContent counts the heading's text, so versesToAdd at firstChapter.utils.ts:184 is 0 and the save is [BOOK, c1, {para s1}].

Why it matters: this is a documented choice (the $holdsChapterContent TSDoc says "a section heading or a remark included", and EditorRef.insertFirstChapter in editor.model.ts says a \s1 already belongs to the chapter), but no test in the "over content already in the chapter" block pins it, so it can change unnoticed. Someone who typed a heading first has to add every verse by hand.

Fix: Keep the documented behavior and pin it: add a case to the "over content already in the chapter" block in chapterLineEditing.test.tsx that calls insertWithVerses([BOOK, { type: "para", marker: "s1", content: ["The Creation"] }]) and expects [BOOK, CHAPTER_1, heading] with no verses. If heading-only books should get verses instead, the change must not put verses above the heading, and it would also have to update the TSDoc in firstChapter.utils.ts and EditorRef.insertFirstChapter in editor.model.ts, regenerate the dist and API report with nx extract-api platform-editor, and add an Unreleased entry to packages/platform/CHANGELOG.md.

How this was checked: The behavior is real: $findChapterContentStart (firstChapter.utils.ts:111) returns the \s1 paragraph as chapter content start, $holdsChapterContent (:146) counts any document text including a heading, so versesToAdd is 0 at :182-185 and the heading-only book saves as [BOOK, c1, s1]. It is deliberate and documented, not an accident: the TSDoc at firstChapter.utils.ts:145 ("a section heading or a remark included") and EditorRef.insertFirstChapter at editor.model.ts:677 ("a section heading such as \s1 already belongs to the chapter") both say it. The remaining gap is that no test in chapterLineEditing.test.tsx (the "over content already in the chapter" block, :1243-1330) covers a heading-only book, so the documented choice is unpinned. The consequence is small: a user with only a heading must add the verses by hand.

Other findings in this file: #1, #3, #4, #5, #6


packages/platform/src/editor/markerEdit/chapterLineEditing.test.tsx line 1287 at r1 (raw file):

    });

    it("adds verses above a paragraph holding only whitespace and a caret's zero-width space", async () => {

#2 - low · checked and confirmed

The whitespace-and-zero-width-space test still passes if the paragraph below the inserted verses is dropped or moved.

What happens: the test at chapterLineEditing.test.tsx:1287 compares only .slice(0, 4) of the saved content against [BOOK, CHAPTER_1, V1, V2]. The saved content is [BOOK, c1, v1, v2, {para p: ["\u200B "]}], so nothing checks that the paragraph survives or stays after the verses. The name also says "a caret's zero-width space", but here the zero-width space comes from the loaded USJ, not from a caret.

Why it matters: test only, with no behavior effect; a regression that drops or reorders the paragraph would go unnoticed.

Fix: In chapterLineEditing.test.tsx (the test at :1287), replace the .slice(0, 4) comparison with a full toEqual of the saved content ending in the normalized paragraph: [BOOK, CHAPTER_1, V1, V2, { type: "para", marker: "p", content: [${ZWSP} ] }] (loading collapses the ${ZWSP} text to ${ZWSP} ). Delete the comment at :1290 and rename the test to describe a paragraph whose loaded text holds only whitespace and a zero-width space.

How this was checked: The test (chapterLineEditing.test.tsx:1287-1297, added by this PR) compares only slice(0, 4) of the saved content. I ran it in a scratch worktree and logged the full result: [book, c1, v1, v2, {type:"para", marker:"p", content:["\u200B "]}]. The normalized paragraph is deterministic, so the comment at :1290 does not justify skipping it; a regression that drops or reorders the paragraph would still pass. The anchor is on a line this PR added. Test-only impact.

katherinejensen00 and others added 2 commits October 27, 2026 18:42
Review of the first-chapter insert found content it missed: a figure
with no caption, a milestone or an empty footnote holds no text, so
verses still went above it. Those now count, along with any block the
editor keeps whole. A paragraph of no-break spaces counts as whitespace
in Standard view too, where each one shows as `~`, so every view gives
the same answer.

Also: use the shared `$isDisplayAnnotationCarrier` instead of a local
list of display-only text, walk the tree lazily with `$dfsIterator`,
pin the heading-only case, and compare the whole document in the
whitespace test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@katherinejensen00

Copy link
Copy Markdown
Contributor Author

Thanks, Ira. All 7 are fixed in c28e074, with the dist rebuilt in 27ea01a.

I checked that removing any one content check (verse, note, milestone, figure, display glyphs, ~) turns tests red. chapterLineEditing.test.tsx: 124 passing, plus lint and tsc.

(AI-assisted)

`MarkerObject` doesn't declare a figure's `file`, so the inline literal
failed the test typecheck in CI. Build the figure in a variable first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@irahopkinson irahopkinson left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks, all 7 check out. At 27ea01a, chapterLineEditing.test.tsx passes (124/124) and lint is clean on the changed files. Resolving the threads.

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

@irahopkinson irahopkinson left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

:lgtm: thanks so much for all your work

@irahopkinson made 1 comment.
Reviewable status: 0 of 7 files reviewed, all discussions resolved (waiting on irahopkinson+AI).

@katherinejensen00
katherinejensen00 merged commit ef60659 into main Oct 28, 2026
5 of 6 checks passed
@katherinejensen00
katherinejensen00 deleted the pt-4614-first-chapter-text branch October 28, 2026 01:59

const chapterContentStart = $findChapterContentStart(styleInfo);
for (const node of nodes) {
if (chapterContentStart) chapterContentStart.insertBefore(node);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Follow-up (this has been the behavior since #35): when chapter content starts with an empty paragraph, the verses go in before it, outside any paragraph, and the empty paragraph ends up after the last verse. "adds verses above an empty paragraph" and "adds verses below a titled front matter" both pin this (BOOK, title, CHAPTER_1, V1, V2, empty).

The easy way to get there is to type a title and press Enter, which leaves \id, \mt1 Genesis, \p (empty). "Add chapter number" then produces \c 1 \v 1 … \v 31 \p. In Simple mode the user then types into verses that belong to no paragraph, and their \p hangs after \v 31. Under the default personal lock they can't repair the structure. It's the same "existing content lands after the last verse" problem this PR fixes for text.

Suggestion: when the chapter content starts with an empty paragraph, put the verses inside that paragraph instead of before it, so the result is \c 1 \p \v 1 … \v 31.

});

// Only the chapter content counts: text in the front matter above it does not.
it("adds verses below a titled front matter", async () => {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Follow-up: moving this decision into the editor dropped the host test that pinned verses still being added below a full front matter with intro text (\h, \toc1, \mt1, \is1 Introduction, \ip <text> → verses). Here the only front matter is a lone \mt1. If chapter content were ever found to start at \is1 or \ip, say through a stylesheet change or a $findChapterContentStart regression, $holdsChapterContent would see the intro text, and every book with an introduction would silently get \c 1 with no verses. No test would fail. Could you add that case here?

katherinejensen00 added a commit that referenced this pull request Nov 13, 2026
A book Paratext creates holds `\h` and `\toc` lines under its `\id`
line. Adds `insertFirstChapter` cases for that shape, with an `\id` text
full of special characters, in Standard view and the paragraph-structure
view that Simple mode's "Add chapter number" button uses: chapter 1 and
its verses go below the header lines, and the `\id` line stays the
book's only one. Test-only; the behavior came with PT-4614 (#35, #37).

Co-authored-by: Claude Opus 5.5 <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.

3 participants