fix(docx-core): emit paragraph-level markers outside <w:r> on rebuild

[stevenobiajulu]

Summary

Fixes #106. Restores w:commentRangeStart / w:commentRangeEnd and w:bookmarkStart / w:bookmarkEnd on rebuild output by atomizing paragraph-internal markers and routing them outside the synthetic <w:r> wrapper that buildSingleRun emits for run-level leaves.

PR #101 traded these markers away to fix a "Word can't open" regression (issue #94), accepting that comment ranges (the highlighted span) and paragraph-internal bookmark spans were lost on rebuild output. This PR puts them back — at the schema-correct position (siblings of <w:r>, not children) — so Word still opens the file and the spans survive.

Mechanics

• New PARAGRAPH_LEVEL_TAGS set + isParagraphLevelLeaf() predicate in atomizer.ts.
• Ancestry-sensitive atomization: only emit a marker atom when the element sits inside a <w:p>. Body/table-sibling placements stay out of the atom stream and are still handled by the existing scaffold-strip block (avoids misattachment via assignParagraphIndices, which only assigns indices to atoms with a w:p ancestor).
• Rebuild-only gate: new atomizeParagraphLevelMarkers flag on AtomizeTreeOptions, set true only on the rebuild path. The inplace path's bookmark reconciliation breaks if bookmarkStart/End atoms enter the stream (orphaned-bookmark warnings, round-trip safety failures).
• buildRunContentWithParagraphMarkers(): walks a RunGroup left to right, buffers run-level atoms, flushes the buffer to <w:r> blocks via subGroupByRPr + buildSingleRun on each marker, and emits markers as bare elements. Always sub-groups by per-atom rPr — group.rPr is captured from the first atom and is intentionally suppressed for moved groups, so trusting it would bleed formatting across segments.
• Bookmark integrity: applies enforceConsumerCompatibility on the rebuilt body (mirrors inplace mode) to dedupe bookmark names/IDs and synthesize recovery starts/ends for orphans. Required because cross-context bookmark pairs (one half paragraph-internal, other body-level) appear unbalanced after rebuild.

Tests

• Strengthen "Comment added on revised side" in rebuild-auxiliary-merge.test.ts to verify markers are present and that their immediate parent is one of w:p / w:ins / w:del / w:moveFrom / w:moveTo (DOM-based, not regex). Original "must NOT appear inside <w:r>" regex regression stays as a floor.
• New "Cross-paragraph comment span" — markers preserved across paragraph boundary with matching w:id.
• New "Sibling-style scaffold markers" — body-level bookmarks don't leak into reconstructed paragraphs.
• New "Inplace regression — comment span" — verifies inplace mode still succeeds without falling back to rebuild when revised has a spanning comment.
• Extend synthetic-docx-fixture.ts with commentSpanParagraphs, bookmarkOnParagraph, siblingBookmarkBefore.

Counts: docx-core 1094 pass (was 1091, +3 new), docx-mcp 638 pass, full lint clean.

Out of scope (follow-ups will be filed)

• moveFromRange* / moveToRange* — collides with synthetic emission in wrapWithMoveFrom/To; needs scaffold-cleanup + dedup work.
• permStart / permEnd — same placement rule per ECMA-376; mechanical extension once helper exists, but lacks fixture coverage.
• buildDocumentPreservingStructure cross-paragraph comment-range stripping in inplace mode — separate code path; explicitly deferred by issue Reconstruct paragraph-level markers (commentRange, bookmark) outside <w:r> in rebuild mode #106 itself.

Peer review

Reviewed by Codex CLI (with repo access) and Gemini CLI in parallel before implementation; both reviews informed the final design — particularly Codex's catches on:

• ancestry-sensitive atomization (vs naive tag-only)
• gating to rebuild-only via options flag (shouldStartNewParagraph keeps paragraphIndex === undefined atoms in the current paragraph, so body-level markers would otherwise misattach)
• always sub-grouping by rPr in the marker-aware helper (overriding group.rPr because moved groups suppress rPr-splitting)
• DOM-based test assertions (the existing "comment added" scenario produces an Inserted range, so the marker's parent is <w:ins> — not raw <w:p>)

Test plan

• npm run build
• npm run lint:workspaces
• npm run test:run (1094/1095 across docx-core, +638 docx-mcp, +113 third workspace)
• npm run check:spec-coverage
• Reviewer: confirm acceptance criteria from issue Reconstruct paragraph-level markers (commentRange, bookmark) outside <w:r> in rebuild mode #106 are met
• Reviewer: verify no regressions in inplace-mode bookmark/comment tests

Fixes: #106
Ref: #101

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
site	Ready	Preview, Comment	Apr 27, 2026 11:23pm

[codecov]

Codecov Report

❌ Patch coverage is 86.95652% with 15 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ocx-core/src/integration/synthetic-docx-fixture.ts	65.78%	12 Missing and 1 partial ⚠️
packages/docx-core/src/atomizer.ts	95.65%	1 Missing ⚠️
...re/src/baselines/atomizer/documentReconstructor.ts	97.82%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!