Evals & Deep Dives

Known limitations

If you have been burned by a DOCX library before, you want the boundary stated plainly, not discovered in production. Here is where safe-docx's edges currently are.

It is not a from-scratch document generator

safe-docx is built for brownfield editing — operating on existing .docx files while preserving their formatting, tracked changes, and comments. It is not a templating or programmatic-layout toolkit for producing new documents from nothing. If generating new .docx files is your primary need, reach for a generation-first library such as docx instead.

It rejects Word template files (.dotx) for now

The local runtime intentionally refuses .dotx template files. Convert the template to a normal .docx document before opening it. This is a deliberate guard, not a silent failure — it will tell you.

The runtime surface is JavaScript/TypeScript only

Supported runtime usage is JavaScript/TypeScript with jszip + @xmldom/xmldom. There is no .NET, Python, or LibreOffice dependency in normal use. That keeps deployment simple, but it also means safe-docx does not shell out to those engines for the cases where only they can render or convert a file.

Automated fixture coverage targets specific document families

The behaviors below are exercised against real legal and business documents, but the in-repo automated fixtures concentrate on a defined set: Common Paper–style and Bonterms mutual NDAs, a Letter of Intent, and ILPA limited-partnership-agreement redline fixtures. The engine is designed for broader complex classes (NVCA financing forms, YC SAFEs, offering memoranda, order forms, services agreements), but "designed for" is not the same as "has a committed fixture for." Where your document class is not yet in the fixture set, treat round-trip fidelity as something to verify, not assume.

The scenario pages are curated exemplars

The pages under safe-docx evals are hand-picked to illustrate how individual primitives behave; they are not the full test suite. The complete, machine-generated run of 990+ tests lives in the public Allure report. If a behavior you care about is not yet written up as a page, the test for it may still exist there.

Where to dig deeper

For the precise contract surface of AI-attributable edits, the assumption matrix, and the traceability matrix, read them at the source:

• UseJunior/safe-docx — source, issues, and release history (MIT).
• SUPPORT.md — the contract surface of AI-attributable edits.
• assumptions.md — the assumption matrix the engine relies on.
• safe-docx vs python-docx — where each tool sits in the stack.