Live OOXML contract

DOCX fidelity and security

The Next.js export endpoint generates a native WordprocessingML package locally. This matrix is tied to the repository’s live package-level fidelity test; it is not a claim that arbitrary browser CSS has a one-to-one Word equivalent.

Tested mappings

Area	Native DOCX output
Document structure	Headings, paragraphs, block quotes, nested bullets and decimal lists, fixed-layout tables
Inline formatting	Bold, italic, underline, strike, code, font family and size, text/background color, subscript and superscript
Paragraph layout	Alignment, margins, line height, first-line indent, page-break-before and explicit page breaks
Page layout	Letter or A4, portrait or landscape, bounded margins, default headers and footers, current/total page fields
Tables	Exact DXA grid, repeating header rows, column span, row span, cell shading and vertical alignment
Review semantics	Native DOCX insertions, deletions, comments, footnotes and endnotes
Links and media	HTTP/HTTPS/mailto links; PNG, JPEG, GIF and BMP data URIs; trusted server-resolved image map

Request contract

POST /api/export/docx
{
  "html": "<h1>Report</h1><p>Body</p>",
  "title": "Report",
  "fileName": "report.docx",
  "headerHtml": "<p>Private report</p>",
  "footerHtml": "<p>Page <span data-page-number="current"></span></p>",
  "page": { "size": "a4", "orientation": "landscape",
            "margin": { "top": 1080, "right": 900, "bottom": 1080, "left": 900 } },
  "imageMap": { "https://trusted.example/chart.png": "data:image/png;base64,..." }
}

Margins use twentieths of a point (twips) and are bounded from 360 to 2880. The request is capped at 1 MiB. An image map accepts at most eight HTTP(S) keys, data-image values only, and 768 KiB decoded in total.

Semantic HTML conventions

<ins data-author="Ada" data-date="2026-07-16T12:00:00Z">added</ins>
<del data-author="Ada">removed</del>
<span data-comment="Check the source" data-comment-author="Reviewer">claim</span>
<sup data-footnote="Source citation"></sup>
<span data-endnote="Appendix detail"></span>
<hr class="page-break">

Security boundary

The converter never performs network fetches. A URL in an img element is ignored unless the calling server supplies an exact URL-to-data-URI entry in imageMap. This keeps DNS, redirects, private addresses, credentials and tenant authorization outside the converter’s trust boundary.

Intentional limits

Word is paginated and browser HTML is flow layout. Floats, CSS grid, filters, scripts, forms, animation and arbitrary styles are not translated.
Only default section headers and footers are exposed; first-page/even-page variants and multiple HTML-defined sections require an application-specific template.
The automated suite inspects the generated OOXML parts and relationships. Visual sign-off in Microsoft Word or LibreOffice remains a release step for branded templates.