Context
Sub-issue of #120. Migrates packages/docx-core/src/primitives/document.ts paragraph-insertion paths to emit native OOXML revision markup at write time.
Per SUPPORT.md (#119), insert_paragraph is in Table A with element set w:ins, w:pPrChange, w:rPrChange. The current DocxDocument.insertParagraph() adds a paragraph via direct DOM mutation. After this PR it must produce a paragraph-level insertion that Word recognizes as a tracked change.
Depends on [120.0] for emitter helpers.
Proposal
Modify DocxDocument.insertParagraph(anchorParagraphId, position, content, ctx?, options?):
- Add an optional
ctx?: RevisionContext parameter.
- When
ctx is provided:
- Wrap the new paragraph's content runs in
<w:ins> (using wrapElementWithIns).
- Add a paragraph-level insertion marker by setting
<w:rPr><w:ins w:id="..." w:author="..." w:date="..."/></w:rPr> inside the new paragraph's <w:pPr>. (This is the OOXML idiom for "this paragraph itself was inserted as a tracked change" — distinct from the run-level <w:ins> wrapper.)
- When
style_source_id is provided and the inherited pPr/rPr differ from defaults, also emit <w:pPrChange> / <w:rPrChange> recording the previous (default) properties for inherited styling.
- When
ctx is omitted: preserve today's untracked behavior.
Also handle replaceParagraphText() if it lives in document.ts — same treatment.
Acceptance criteria
insertParagraph(anchor, 'AFTER', 'New para text', ctx) produces XML where the new paragraph contains:
<w:pPr><w:rPr><w:ins w:id="..." w:author="..." w:date="..."/></w:rPr></w:pPr> (the paragraph-level insertion marker)
<w:r> wrapped in <w:ins> carrying the run content
w:id values are unique across the document.
- When
style_source_id is used and changes paragraph styling, a <w:pPrChange> is emitted recording the prior property state.
- Calling without
ctx preserves today's behavior; golden tests stay green.
- New tests in the existing test infrastructure cover the four cases above.
npm run build && npm run test:run passes.
Files to edit
packages/docx-core/src/primitives/document.ts
- The corresponding test file (likely
document.test.ts or replace_text / insert_paragraph test files)
Files to read (do not edit)
packages/docx-core/src/primitives/track-changes-emitter.ts — use these helpers
packages/docx-core/SUPPORT.md
Out of scope
- MCP tool wiring (
insert_paragraph.ts, apply_plan.ts) — covered in [120.7].
- Paragraph deletion as a tracked change — that's a separate concern (rare in current MCP surface); add a follow-up issue if a primitive emerges.
Tracking
Context
Sub-issue of #120. Migrates
packages/docx-core/src/primitives/document.tsparagraph-insertion paths to emit native OOXML revision markup at write time.Per
SUPPORT.md(#119),insert_paragraphis in Table A with element setw:ins,w:pPrChange,w:rPrChange. The currentDocxDocument.insertParagraph()adds a paragraph via direct DOM mutation. After this PR it must produce a paragraph-level insertion that Word recognizes as a tracked change.Depends on [120.0] for emitter helpers.
Proposal
Modify
DocxDocument.insertParagraph(anchorParagraphId, position, content, ctx?, options?):ctx?: RevisionContextparameter.ctxis provided:<w:ins>(usingwrapElementWithIns).<w:rPr><w:ins w:id="..." w:author="..." w:date="..."/></w:rPr>inside the new paragraph's<w:pPr>. (This is the OOXML idiom for "this paragraph itself was inserted as a tracked change" — distinct from the run-level<w:ins>wrapper.)style_source_idis provided and the inheritedpPr/rPrdiffer from defaults, also emit<w:pPrChange>/<w:rPrChange>recording the previous (default) properties for inherited styling.ctxis omitted: preserve today's untracked behavior.Also handle
replaceParagraphText()if it lives indocument.ts— same treatment.Acceptance criteria
insertParagraph(anchor, 'AFTER', 'New para text', ctx)produces XML where the new paragraph contains:<w:pPr><w:rPr><w:ins w:id="..." w:author="..." w:date="..."/></w:rPr></w:pPr>(the paragraph-level insertion marker)<w:r>wrapped in<w:ins>carrying the run contentw:idvalues are unique across the document.style_source_idis used and changes paragraph styling, a<w:pPrChange>is emitted recording the prior property state.ctxpreserves today's behavior; golden tests stay green.npm run build && npm run test:runpasses.Files to edit
packages/docx-core/src/primitives/document.tsdocument.test.tsorreplace_text/insert_paragraphtest files)Files to read (do not edit)
packages/docx-core/src/primitives/track-changes-emitter.ts— use these helperspackages/docx-core/SUPPORT.mdOut of scope
insert_paragraph.ts,apply_plan.ts) — covered in [120.7].Tracking
SUPPORT.md