Skip to content

Treat implied paragraphs as transparent in USJ selection locations - #28

Closed
timothy-mccormack wants to merge 2 commits into
mainfrom
pt-4809-implied-para-json-paths
Closed

timothy-mccormack wants to merge 2 commits into
mainfrom
pt-4809-implied-para-json-paths

Conversation

@timothy-mccormack

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

Copy link
Copy Markdown
Contributor

Fixes the "Invalid selection" part of PT-4809. The Platform.Bible side is paranext/paranext-core#2900, which should merge after this PR and after platform-yalc moves.

Why

When a chapter has verses before its first paragraph marker (\c 1 followed directly by \v 1), Platform.Bible refuses every comment insertion in that chapter with "Invalid selection", even on a plain word in a proper paragraph further down.

The editor wraps content that sits outside any paragraph in an ImpliedParaNode when it loads (insertImpliedParasRecurse), and the editor→USJ conversion unwraps it again (removeImpliedParasRecurse). The logical-content helpers that turn a selection into a USJ jsonPath still counted the wrapper as a content item. So in such a chapter, every location getSelection() returned was one level too deep, or one index too low, compared with getUsj(). The host resolves the selection against getUsj(), so it couldn't find the selected text and refused it. Platform.Bible's character-marker bar uses the same lookup, so it silently showed nothing in those chapters.

What changed

  • $getLogicalContentItems and $getLogicalParent treat ImpliedParaNode as transparent, the same way annotation TypedMarkNodes already are. The new exported $isLogicallyTransparent is the single definition of which wrappers have no USJ location of their own.

  • One rule for every transparent wrapper, in both directions. It replaces the separate mark branch in $getLocationFromNode, including its "known approximation".

    • Element point → USJ ($getLogicalPointFromElementPoint): a point inside a wrapper is a point in its logical parent's content, at the next content node in document order. Presentation-only nodes are skipped and wrappers are entered.
    • USJ → element point ($getElementOffsetFromLogicalIndex becomes $getElementPointFromLogicalIndex, returning [node, offset]): every element point between the previous item and the next one is the same USJ boundary. Of those, it picks:
      • never a mark's edge, so typing there doesn't extend the annotation;
      • a point inside an implied paragraph rather than between blocks;
      • a point inside an implied paragraph with no content, when the boundary passes one (the empty line Enter leaves, or an empty document);
      • otherwise the earliest point.
    • Boundaries between a mark's children now map exactly, in regular paragraphs too.
  • Affinity at block breaks. Adjacent implied paragraphs export as one USJ text run, so the end of one and the start of the next are the same location. A caret and a range end resolve to the earlier line; a range start resolves to the later one (LogicalPointAffinity).

  • Nodes with no USJ location. These now report the content position beside them:

    • presentation-only text: the caret-guard hosts, NBSP spacers and attribute text;
    • a marker glyph whose anchor is an implied paragraph or an AttributeRunNode;
    • an element point before a visible glyph in an implied paragraph.

    Before, these reported $ or $.marker once the implied paragraph lost its index, and those never resolve.

  • A non-numeric offset resolves to boundary 0 instead of throwing.

Content that is already inside real paragraphs, with no marks, is unaffected.

Behavior changes worth a look

  • When an empty implied paragraph follows another implied paragraph, a caret at the end of the first one now resolves into the empty one. Both are the same USJ point, and without this the empty line can't be reached at all.
  • A caret in a \va/\vp/milestone attribute glyph inside a regular paragraph now reports the content position next to the glyph. Before, it reported the paragraph's marker location, which resolved to the \p glyph.

Not addressed here (already on main)

  • A note's caller is counted as a content item, so locations inside note content are off by one.
  • An ImpliedParaNode nested below the root (reachable through an HTML paste) has its content dropped by the exporter.

Testing

  • selection.utils.test.ts:

    • The implied-paragraph tests cover text and element points inside and after the paragraph, a mark inside it, and a round trip of every point in the chapter.
    • A new suite covers the transparent-wrapper boundaries: a caret host and marker glyphs in an implied paragraph, empty implied paragraphs, line breaks, adjacent implied paragraphs, a boundary inside a multi-child mark, and a non-numeric offset. All 10 tests fail against this PR's first commit.
  • logical-content-agreement.test.tsx now also pins the root's logical content against the exporter: implied paragraphs are transparent and text across them coalesces. This case fails on main.

  • nx run-many -t test lint typecheck passes for shared, shared-react, utilities and platform-editor (platform vitest: 2368 tests, including the corpus round-trip test).

  • dist/ was rebuilt with nx extract-api platform-editor, and the API report is unchanged. The index.js diff is large because the bundler renumbers identifiers.

  • In Platform.Bible, with the first commit's build staged (npm run build:editor) and the reporter's chapter loaded:

    • Comments can be inserted on plain words both before and after the unmarked verses.
    • A saved comment anchors on the selected text (GEN 1:5, "kidding").
    • A selection that crosses a character marker is still refused.

    The follow-up commit has not been re-checked in the app yet.

AI-assisted — Claude traced the cause, wrote the change and tests, and ran the in-app checks.

🤖 Generated with Claude Code


This change is Reviewable

Content that sits outside any paragraph (e.g. verses between \c and a
chapter's first paragraph marker) loads into an ImpliedParaNode, which
the editor->USJ conversion unwraps again. The logical-content helpers
that turn selections into USJ jsonPaths still counted the wrapper as a
content item, so every location after it pointed one level too deep and
one index too low. getSelection() therefore returned paths that do not
resolve against getUsj(), and in Platform.Bible every comment insertion
in such a chapter was refused as "Invalid selection" (PT-4809).

- $getLogicalContentItems / $getLogicalParent treat ImpliedParaNode as
  transparent, the same way annotation TypedMarkNodes already are.
- An element point inside an implied paragraph is expressed in its
  logical parent's coordinates.
- The reverse direction, $getElementPointFromLogicalIndex (was
  $getElementOffsetFromLogicalIndex), returns a point inside the implied
  paragraph when the boundary falls in it, so locations round-trip.
- A mark directly inside an implied paragraph anchors on the paragraph.

Verified in Platform.Bible with the reporter's chapter: comments can be
inserted on plain words before and after the unmarked verses and anchor
on the selected text; a selection that crosses a character marker is
still refused.

The dist/index.js diff is large because the bundler renumbers
identifiers; rebuilding unchanged main reproduces the committed bundle
byte for byte, so the output is reproducible.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Treating implied paragraphs as transparent left several locations wrong or
unresolvable: an empty implied paragraph mapped to the end of the document,
caret hosts and marker glyphs inside one reported `$`, boundaries inside a
mark in one snapped to the mark's front edge, and a caret at the end of one
implied paragraph resolved onto the next line.

- One rule for every logically transparent wrapper (annotation marks and
  implied paragraphs) in both directions, replacing the implied-paragraph
  special cases and the separate mark branch in `$getLocationFromNode`.
  Element points walk forward to the next content node; the inverse picks
  among the equivalent element points, staying outside mark edges, inside
  implied paragraphs, and in an empty implied paragraph when one is there.
- A boundary on a block break the USJ does not record resolves by
  affinity: a caret and a range end take the earlier line, a range start
  the later one.
- Presentation-only text and marker glyphs with no USJ location of their
  own report the content position beside them.
- A non-numeric offset no longer throws.
- Pin the root's logical content against the exporter, and add a
  regression test for each case above.

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

Copy link
Copy Markdown
Contributor Author

Closing as superseded by #11 (PT-4370), which merged first and fixes the same bug: it treats the root's implied paragraph as transparent in selection jsonPaths, as part of reworking the editor's position API. #11 is on platform-yalc.

Checked in Platform.Bible on paranext-core main (70c7ef79158) with the platform-yalc editor (1cb486ba), in a GEN 1 with no \p after \c 1. Comments save on plain words before the first paragraph marker (GEN 1:1) and after it (GEN 1:3), with no "Invalid selection".

The review of this PR also found edge cases that are still present on main and are not part of PT-4809. Each can still put the caret or a host selection in the wrong place:

  • a caret host after an empty last verse in an implied paragraph
  • a marker glyph inside an implied paragraph
  • an empty implied paragraph or an empty document
  • line breaks inside an implied paragraph

They would need a fresh change against #11's position model; this branch's code doesn't port.

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.

1 participant