User-defined segment boundaries

[alex-rawlings-yyc]

This change is 

Summary by CodeRabbit

• New Features
  • Added per-project user-defined segment boundaries with Alt-gated split controls and merge controls, including cross-segment linking across boundary edges.
  • Added inline verse superscripts and an optional left verse gutter (including verse-0 and merged ranges).
  • Added stronger phrase candidate preview styling.
• Bug Fixes
  • Improved focus/active-segment resolution, link enablement/tooltips, and scroll/re-centering behavior after merge/split boundary edits.
• Changes
  • Removed “chapter label in verse”; added “show verse gutter” toggle.
  • Added segmentation persistence on save, including boundary clearing via "null".
• Documentation
  • Added “User-defined segment boundaries” UX and save/restore documentation.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• ✅ Review completed - (🔄 Check again to review again)

📝 Walkthrough

Walkthrough

This PR adds user-defined segment boundaries stored as deltas from default verse segmentation. It introduces boundary controls, resegmentation, phrase-aware cross-segment linking, verse labels, draft autosave, project persistence, and updated view settings.

Changes

User-defined segment boundary editing

Layer / File(s)	Summary
Segmentation contracts and transforms src/types/*, src/utils/segmentation.ts, src/utils/verse-ref.ts, src/parsers/papi/resegmentBook.ts	Defines segmentation and verse metadata, validates deltas, applies normalized boundary edits, resolves verse containment, and rebuilds merged or split books.
Boundary editing UI and interaction state src/components/SegmentationStore.tsx, src/components/AltHeldContext.tsx, src/components/PhraseStripParts.tsx, src/components/SegmentView.tsx, src/components/SegmentListView.tsx, src/components/TokenLinkIcon.tsx	Adds merge/split controls, Alt-held gating, baseline split gestures, candidate styling, gutter labels, and adjacent-edge phrase linking.
Rendering, navigation, and reconciliation src/components/Interlinearizer.tsx, src/components/InterlinearizerLoader.tsx, src/components/ContinuousView.tsx, src/hooks/useSegmentWindow.ts, src/hooks/useBookIndexes.ts	Propagates segmentation context and versions, preserves focus across edits, resolves active segments by verse containment, and reconciles scrolling after boundary changes.
Draft and project persistence src/hooks/useDraftProject.ts, src/components/modals/ProjectModals.tsx, src/services/projectStorage.ts, src/main.ts	Autosaves segmentation deltas, tracks segmentation sync state, loads and validates stored boundaries, and persists updates with omit, clear, and replace semantics.
Verse metadata and display settings src/parsers/papi/usjBookExtractor.ts, src/parsers/papi/bookTokenizer.ts, src/utils/verse-superscripts.ts, src/utils/segment-labels.ts, contributions/*, src/types/view-options.ts	Carries rendered verse numbers through extraction and tokenization, renders inline superscripts and gutter labels, and replaces the chapter-label toggle with the verse-gutter setting.
Validation and regression coverage src/__tests__/*, __mocks__/lucide-react.tsx, src/hooks/useArcPaths.ts, src/components/AnalysisStore.tsx, src/components/PhraseBox.tsx, src/components/TokenChip.tsx	Adds coverage for segmentation, persistence, labels, navigation, controls, Alt-key behavior, phrase candidates, and settle-aware layout measurement.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related PRs

• sillsdev/interlinearizer-extension#91 — Relates to the TokenLinkIcon unlink behavior and lucide-react mock changes.
• sillsdev/interlinearizer-extension#98 — Relates to the removed chapter-label setting replaced by verse superscript and gutter rendering.

Suggested reviewers: imnasnainaec

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the main change: adding user-defined segment boundary editing and persistence.
Docstring Coverage	✅ Passed	Docstring coverage is 98.55% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch segment-boundaries

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[alex-rawlings-yyc]

@alex-rawlings-yyc resolved 1 discussion.
Reviewable status: 0 of 50 files reviewed, all discussions resolved (waiting on alex-rawlings-yyc).

[alex-rawlings-yyc]

@alex-rawlings-yyc resolved 2 discussions.
Reviewable status: 4 of 66 files reviewed, 1 unresolved discussion.

[imnasnainaec]

The segment join-split interaction when holding ALT is really slick!! Simple hover-text on the split and join buttons would help clarify what's about to happen when they're clicked.

A bigger concern is discoverability. We may want the segment join buttons always visible, with hover text that also mentions the ALT action for splitting segments.

[imnasnainaec]

⛏️ I think that (at least in continuous view, but perhaps also in the full-detail segment view) the verse superscript should only show where the verse actual starts, not at mid-verse segment starts (like the second 1 below).

[imnasnainaec]

We had also discussed an alternate (from the verse superscripts) for segment view, in which the verse(-range) shows up in an initial gutter/column instead.

[imnasnainaec]

Claude Sonnet analysis of two Devin flags:

1. SegmentListView.tsx:306 — scroll handler perf

The mounted window is hard-capped at HARD_WINDOW_CAP = 120 (useSegmentWindow.ts:31), and readTopChapter runs on every raw scroll event with no coalescing. Native scroll events fire more often than paints during inertial/trackpad fling, so this can mean multiple 120-element getBoundingClientRect() scans per animation frame.

Suggest a quick fix now, defer the bigger rewrite:

• Now: coalesce with requestAnimationFrame so readTopChapter runs at most once per frame:

  let scheduled = false;
  const onScroll = () => {
    if (scheduled) return;
    scheduled = true;
    requestAnimationFrame(() => {
      scheduled = false;
      readTopChapter();
    });
  };
  container.addEventListener('scroll', onScroll, { passive: true });

  Low risk, no architecture change, removes the per-event redundant reads.

• Possible follow-up: the suggested IntersectionObserver approach is the right long-term fix and would match the pattern already used for the extend-window sentinels (useSegmentWindow.ts:635-668) — observe only chapter-boundary segments with a scrollspy-style rootMargin instead of scanning every segment. Bigger change; fine as a follow-up rather than blocking this PR.

2. InterlinearizerLoader.tsx:329 — preceding-segment fallback misses cross-chapter segments in their end chapter

The fallback filters by startRef.chapter === scrRef.chapterNum (line 335), but Segment.verseStarts carries a chapter per entry (interlinearizer.d.ts:542). A cross-chapter segment (e.g. one starting at 4:20 and covering through 5:3) has startRef.chapter === 4, so it's excluded when resolving an over-shoot within chapter 5 — even if it's the only segment touching chapter 5's content. preceding then stays undefined and the invalid ref falls through unchanged, when a correct preceding segment actually exists.

Suggest iterating segment.verseStarts (filtered by vs.chapter === scrRef.chapterNum) instead of segment.startRef, and building the returned ref from the matching verseStarts entry's own chapter/verse rather than startRef. This can reuse the verse-number parsing currently private to verseLabelCovers in verse-ref.ts:28-34 — worth exporting a small firstVerseNumber(label) helper so both call sites share it instead of duplicating the regex. Recommend adding a regression test for this alongside the existing cross-chapter case in segment-labels.test.ts:88-98.

[alex-rawlings-yyc]

@imnasnainaec Clarify for me: You said:

We may want the segment join buttons always visible, with hover text that also mentions the ALT action for splitting segments.

Do we want join buttons always visible, with splitting buttons only visible with ALT? If that's the case, would the split tooltip be on the join buttons? And should the join buttons be enabled even when ALT isn't held?

[imnasnainaec]

@imnasnainaec Clarify for me: You said:

We may want the segment join buttons always visible, with hover text that also mentions the ALT action for splitting segments.

Do we want join buttons always visible, with splitting buttons only visible with ALT? If that's the case, would the split tooltip be on the join buttons? And should the join buttons be enabled even when ALT isn't held?

Join button always enabled; splitting only visible with ALT. Join and split buttons both with very simple hover text when ALT is held. Otherwise, join button with additional hover text about holding ALT to enable splitting segments.

[alex-rawlings-yyc]

@alex-rawlings-yyc resolved 5 discussions.
Reviewable status: 19 of 80 files reviewed, 1 unresolved discussion (waiting on alex-rawlings-yyc and imnasnainaec).

[imnasnainaec]

@imnasnainaec partially reviewed 18 files, made 1 comment, and resolved 1 discussion.
Reviewable status: 35 of 80 files reviewed, all discussions resolved (waiting on alex-rawlings-yyc).

---

src/__tests__/components/PhraseStripParts.test.tsx line 429 at r12 (raw file):

  }

  // -- Merge branch --------------------------------------------------------

⛏️ We can use nested describes instead of comment subsectioning.

[alex-rawlings-yyc]

src/__tests__/components/PhraseStripParts.test.tsx line 429 at r12 (raw file):

Previously, imnasnainaec (D. Ror.) wrote…

⛏️ We can use nested describes instead of comment subsectioning.

Done

[imnasnainaec]

@imnasnainaec made 1 comment.
Reviewable status: 35 of 80 files reviewed, 1 unresolved discussion (waiting on alex-rawlings-yyc).

---

a discussion (no related file):
🐛 I'm not seeing any hover text on the segment split/join buttons when I hold ALT.

[alex-rawlings-yyc]

@alex-rawlings-yyc made 1 comment.
Reviewable status: 35 of 80 files reviewed, 1 unresolved discussion (waiting on alex-rawlings-yyc and imnasnainaec).

---

a discussion (no related file):

Previously, imnasnainaec (D. Ror.) wrote…

🐛 I'm not seeing any hover text on the segment split/join buttons when I hold ALT.

Switched to Platform.Bible's dedicated Tooltip system; should be working now

[imnasnainaec]

@imnasnainaec reviewed 47 files and all commit messages, and resolved 1 discussion.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on alex-rawlings-yyc).