Skip to content

[120.2] Emit paragraph-level w:ins from document.ts:insertParagraph #137

@stevenobiajulu

Description

@stevenobiajulu

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?):

  1. Add an optional ctx?: RevisionContext parameter.
  2. 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.
  3. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requesttracked-changesTracked changes, comments, revision markers

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions