Evaluate from-scratch DOCX generation as a safe-docx capability

[stevenobiajulu]

Summary

Today safe-docx is positioned around surgical manipulation of existing OOXML documents — revisions, tracked changes, comments, side-part edits, MCP-mediated edits. The complementary capability — constructing a new DOCX from scratch out of structured inputs (sections, headings, tables, headers/footers with page numbers, signature blocks, etc.) — is currently out of scope.

This issue captures the strategic option of bringing that capability in-house under @usejunior/docx-core. Not on the near-term roadmap; filing so the option doesn't get lost.

Why it could matter

• Reduces total surface area of third-party OOXML emitters we depend on in downstream products.
• Gives consumers one library that owns both write and rewrite paths against the same canonical model — fewer impedance mismatches.
• Lets us guarantee end-to-end OOXML quality (the same conformance work we do for manipulation paths applies to generation).
• Opens up MCP tool surfaces like "generate a new document from a recipe" that today require pairing safe-docx with an external generator.

What "feature complete" would minimally cover

Drawn from the document shapes that appear in real-world legal/contract workflows. Not exhaustive — flag additions in comments.

• Sections with distinct headers/footers (cover page → body)
• PAGE / NUMPAGES fields in footers, structurally correct (cached result text present so reading apps don't trip recovery dialogs)
• Named paragraph styles + style table emission
• Tables with cell borders, column widths, fixed layout
• Tabular cover-terms blocks
• Signature blocks (signature line + name + date + title rows)
• Numbered lists / multi-level numbering
• Run-level formatting (bold, color, font, size) with proper rPr discipline
• Page numbering, page-margin, section breaks
• Drafting notes / annotations as separable layers
• Field code emission that opens cleanly in Microsoft Word for Mac (not just LibreOffice)

Anti-goals

• Not a clone of any specific third-party generation library's API; the safe-docx model can be opinionated.
• Not a Word-for-Mac compatibility layer alone — must hold up against Pages, Google Docs import, LibreOffice, and headless renderers as well.

Status

Priority: backlog. Filing now so the option is captured. Re-evaluate when downstream consumers express demand or when a substantive piece can be carved off opportunistically.

Acceptance criteria for THIS issue (not for the work itself)

• Document that the capability is recognized as strategic.
• Re-prioritize when (a) a downstream consumer requests generation, OR (b) someone identifies a 1–2 PR-sized starter slice that exercises the architecture.

Related capabilities already in safe-docx

(none of the above replace these; they extend safe-docx's footprint)

• Document comparison / redline (comparison label)
• Tracked changes, comments, revision markers (tracked-changes label)
• MCP server surface for surgical edits