@md2nativedocx/cli 0.1.0 → 0.2.1

package/README.md

@@ -27,10 +27,11 @@ md2nativedocx report.md -o report.docx
 ```
 
 ```
-Usage: md2nativedocx <input.md> -o <output.docx> [options]
+Usage: md2nativedocx <input.md> -o <output.docx|output.odt|output.pptx> [options]
 
 Options:
-  -o, --output <file>   Output .docx path (required)
+  -o, --output <file>   Output .docx, .odt or .pptx path (required)
+  --show-source         .pptx only: show each diagram's Mermaid source beside it
   -h, --help            Show this help
 ```
 
@@ -47,6 +48,22 @@ Pandoc as usual. Per-type detail:
 | `MD2NATIVEDOCX_NATIVE_CHARTS=0` (or `pie,xychart`) | No Word charts (or only those types) |
 | `MD2NATIVEDOCX_SMARTART_STYLE` | SmartArt look: `simple`, `subtle`, `moderate`, `intense-accent`, `colorful` (default), `colorful-moderate`, `intense` |
 
+### LibreOffice (`.odt`)
+
+```sh
+md2nativedocx report.md -o report.odt
+```
+
+Writes an OpenDocument text for LibreOffice: the document as Pandoc converts it, and each flowchart as one
+group of native LibreOffice shapes (boxes, diamonds, cylinders…) with connectors attached to them, which
+follow a box you move (*F3* enters the group), subgraphs as containers, `classDef`/`style`/`linkStyle`
+colours kept. Other diagram types become a note in their place for now. The page is A4 with 2.54 cm
+margins; the page and typography variables below, SmartArt and charts apply to `.docx` only. Pandoc
+writes the whole file, with a reference document and template shipped in `assets/` (see
+`THIRD_PARTY_NOTICES.md` for the template's BSD-3 notice).
+
+From code: `convert(markdown, { format: 'odt' })`.
+
 ## Configuration
 
 Page layout, typography, table of contents, and other export options are set via environment
@@ -62,6 +79,13 @@ in the main repository for the full list.
 | `1` | No document: input file not found, Pandoc missing or failed, post-processing failed. |
 | `2` | Bad command line: unknown option, missing input or `-o`, a path outside the working directory. |
 
+## Very large diagrams
+
+A diagram with more than 500 nodes (subgraph boxes included) or 800 edges is not laid out: the document
+still converts, the diagram is replaced by a grey note saying why, and a warning goes to stderr and the
+`.log`. This keeps one pathological block from running for minutes. In `@md2nativedocx/core`, `renderDiagram()`
+throws a `DiagramTooLargeError` instead, and takes `maxNodes`, `maxEdges` and `maxSourceLength` to change the limits.
+
 ## From Node: `convert()`
 
 The same conversion as a function, for a Node application, a build script or a server, without spawning

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,38 @@
+# Third-party notices
+
+Everything in this package is CC0-1.0 except the file below.
+
+## `assets/md2nativedocx.opendocument`
+
+Derived from Pandoc's `opendocument` template (Pandoc 3.1.3, `data/templates/default.opendocument`).
+Pandoc's templates are dual-licensed under the GNU GPL (version 2 or later) and the BSD 3-Clause
+license; this derived file is distributed under the BSD 3-Clause license. The only change is a loop
+added inside `office:automatic-styles`, filled by this project's Lua filter with the styles of the
+diagrams it draws. That change is distributed under the same license.
+
+```
+Copyright (c) 2014-2023, John MacFarlane <jgm@berkeley.edu>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted
+provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice, this list of conditions
+    and the following disclaimer.
+  * Redistributions in binary form must reproduce the above copyright notice, this list of
+    conditions and the following disclaimer in the documentation and/or other materials provided
+    with the distribution.
+  * Neither the name of John MacFarlane nor the names of other contributors may be used to endorse
+    or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
+THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+
+Pandoc itself is not part of this package: it is run as a separate program (GPL-2.0-or-later).

package/assets/README.md

@@ -1,27 +1,65 @@
 # `reference.docx`
 
 Passed to Pandoc via `--reference-doc` so generated documents use Word's current default look
-(Aptos font scheme, modern "Office" theme colors, flat non-bold heading hierarchy) instead of
-Pandoc's own bundled default, which is the original 2007-2010 Office theme verbatim (Calibri
-headings / Cambria body, bold colored H1-H3, accent1 `#4F81BD`) — confirmed by inspecting
-Pandoc 3.1.3's `--print-default-data-file reference.docx` directly, not assumed.
-
-No real Word install was available to generate this by hand (the usual method: open Pandoc's
-default reference.docx in Word, tweak styles via the UI, save). Built instead by editing the
-OOXML directly:
-
-- `word/theme/theme1.xml`: `majorFont`/`minorFont` latin typeface set to `Aptos Display`/`Aptos`;
-  color scheme swapped from the 2007 palette to the modern one (`accent1` `#4472C4`, etc.).
-- `word/styles.xml`: `docDefaults` body text 12pt → 11pt, paragraph spacing single/10pt-after →
-  1.08 line spacing/8pt-after (Word's actual `Normal.dotm` defaults since the 2013 theme, not
-  changed by the later Aptos font rollout); `Heading1`-`Heading3` no longer bold, `Heading4`-
-  `Heading5` no longer italic (the 2007 theme's bold/italic emphasis ladder isn't how the current
-  built-in Word style gallery renders headings); heading/hyperlink accent colors updated to match.
-
-**Assumptions to verify in a real Word** (no Word install in this environment — verified so far
-only structurally, via `xmllint`, and visually via LibreOffice, which substitutes a fallback font
-since Aptos isn't installed here either): the exact non-bold/non-italic heading styling, and
-whether Word's *current* built-in template still matches this reconstruction if Microsoft has
-changed it again since. Regenerate by editing `word/theme/theme1.xml` and `word/styles.xml` the
-same way if it needs correcting — no other part of this file matters (do not hand-edit
-`document.xml`, numbering, or anything else in the package).
+(Aptos font scheme, the modern "Office" colour scheme, accent1 `#4472C4`, flat non-bold heading
+hierarchy, 11 pt body text with 1.08 line spacing and 8 pt after) instead of Pandoc's own bundled
+default, which is the 2007-2010 Office look (Calibri/Cambria, bold coloured headings).
+
+**Written by this project, from scratch (2026-10-08).** Every part comes from
+`packages/cli/reference-docx-src/` and is assembled by:
+
+```bash
+node scripts/build-reference-docx.mjs
+```
+
+Edit a part there, rebuild, and commit both. The build is reproducible (fixed timestamps).
+
+Why: the previous file was derived from Pandoc's default `reference.docx`, which Pandoc distributes
+under GPL-2+ only (its templates are dual GPL-2+/BSD-3, its other data files are not), while this
+project is CC0. The maintainer chose to rebuild it (ADR 0013, `docs/adr/0013-odf-output-phase-0.md`).
+The new parts keep the same visual values: a LibreOffice render of a document using every Pandoc
+style (title block, abstract, headings, lists, footnote, code, table with caption, definition list,
+diagram) is pixel-identical to the previous one. They contain no sample text and no relationship to
+anything outside the package (the old file carried an unused `http://example.com` link from
+Pandoc's sample document).
+
+What the rest of the code relies on (`src/referenceDocBuilder.mjs`, tested in
+`test/reference-doc-builder.test.mjs`):
+
+- `word/theme/theme1.xml`: `<a:majorFont><a:latin typeface="…" />`, the same for `minorFont`, and
+  `<a:accent1><a:srgbClr val="RRGGBB"/></a:accent1>`;
+- `word/styles.xml`: `w:docDefaults` with `w:sz`/`w:szCs` and a `w:pPrDefault`; accent colours as
+  `w:themeColor="accent1"` with a literal `w:val` fallback (LibreOffice does not resolve theme
+  colours); a `Table` style with a `firstRow` conditional `w:tcPr`;
+- `word/document.xml`: an empty `<w:sectPr />`, which `patchSectPr` fills.
+
+Styles Pandoc adds at conversion time (syntax highlighting `SourceCode`, `*Tok`) are not in this
+file: Pandoc writes them itself.
+
+**To verify in a real Word** (no Word in this environment; checked with LibreOffice and the Open XML
+validator): heading styling and whether Word's current built-in template still matches.
+
+# `reference.odt` and `md2nativedocx.opendocument`
+
+The two files handed to Pandoc for a `.odt` (ADR 0013; `AGENTS.md` rule 7: nothing touches the
+`.odt` Pandoc writes). Both are built by:
+
+```bash
+node scripts/build-odt-assets.mjs
+```
+
+- **`reference.odt`**, written by this project (CC0) from `packages/cli/reference-odt-src/`, never
+  Pandoc's own (GPL-2+). Pandoc keeps its `styles.xml` and writes the rest. It defines the styles
+  Pandoc's ODT writer refers to (headings, title block, code, quotations, tables, captions,
+  definition lists, footnotes, links), an A4 page with 2.54 cm margins, and the arrow markers and
+  dash pattern the diagrams use (`ODF_GRAPHIC_DEFINITIONS` in `@md2nativedocx/core`, kept equal by
+  `test/odt.test.mjs`). LibreOffice does **not** supply its built-in look for a style a document
+  references without defining (headings came out as plain text with a minimal `styles.xml`,
+  2026-10-08), so each one is written here.
+- **`md2nativedocx.opendocument`**, Pandoc 3.1.3's `opendocument` template plus one loop inside
+  `office:automatic-styles` for the diagram styles. BSD-3-Clause, see `../THIRD_PARTY_NOTICES.md`.
+  The build refuses any other Pandoc version, and `test/odt.test.mjs` checks the file still differs
+  from `pandoc -D opendocument` by that loop only.
+
+Known Pandoc 3.1.3 limitation, not ours: a front-matter `abstract` is written as bare text outside
+any paragraph, which the ODF validator rejects (same with Pandoc's own reference document).

package/assets/md2nativedocx.opendocument

@@ -0,0 +1,171 @@
+$-- md2nativedocx: Pandoc's opendocument template (Pandoc 3.1.3), with one addition: the
+$-- md2n-automatic-styles loop in office:automatic-styles, filled by the md2nativedocx Lua filter.
+$-- Copyright (c) 2014-2023, John MacFarlane. BSD-3-Clause, see THIRD_PARTY_NOTICES.md.
+<?xml version="1.0" encoding="utf-8" ?>
+<office:document-content xmlns:office="urn:oasis:names:tc:opendocument:xmlns:office:1.0" xmlns:style="urn:oasis:names:tc:opendocument:xmlns:style:1.0" xmlns:text="urn:oasis:names:tc:opendocument:xmlns:text:1.0" xmlns:table="urn:oasis:names:tc:opendocument:xmlns:table:1.0" xmlns:draw="urn:oasis:names:tc:opendocument:xmlns:drawing:1.0" xmlns:fo="urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:meta="urn:oasis:names:tc:opendocument:xmlns:meta:1.0" xmlns:number="urn:oasis:names:tc:opendocument:xmlns:datastyle:1.0" xmlns:svg="urn:oasis:names:tc:opendocument:xmlns:svg-compatible:1.0" xmlns:chart="urn:oasis:names:tc:opendocument:xmlns:chart:1.0" xmlns:dr3d="urn:oasis:names:tc:opendocument:xmlns:dr3d:1.0" xmlns:math="http://www.w3.org/1998/Math/MathML" xmlns:form="urn:oasis:names:tc:opendocument:xmlns:form:1.0" xmlns:script="urn:oasis:names:tc:opendocument:xmlns:script:1.0" xmlns:ooo="http://openoffice.org/2004/office" xmlns:ooow="http://openoffice.org/2004/writer" xmlns:oooc="http://openoffice.org/2004/calc" xmlns:dom="http://www.w3.org/2001/xml-events" xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" office:version="1.3">
+  <office:font-face-decls>
+    <style:font-face style:name="Courier New" style:font-family-generic="modern" style:font-pitch="fixed" svg:font-family="'Courier New'" />
+  </office:font-face-decls>
+  <office:automatic-styles>
+    $automatic-styles$
+$for(md2n-automatic-styles)$
+    $md2n-automatic-styles$
+$endfor$
+  </office:automatic-styles>
+$for(header-includes)$
+  $header-includes$
+$endfor$
+<office:body>
+<office:text>
+$if(title)$
+<text:p text:style-name="Title">$title$</text:p>
+$endif$
+$if(subtitle)$
+<text:p text:style-name="Subtitle">$subtitle$</text:p>
+$endif$
+$for(author)$
+<text:p text:style-name="Author">$author$</text:p>
+$endfor$
+$if(date)$
+<text:p text:style-name="Date">$date$</text:p>
+$endif$
+$if(abstract)$
+$abstract$
+$endif$
+$for(include-before)$
+$include-before$
+$endfor$
+$if(toc)$
+<text:table-of-content>
+  <text:table-of-content-source text:outline-level="$toc-depth$">
+    <text:index-title-template text:style-name="Contents_20_Heading">$toc-title$</text:index-title-template>
+    <text:table-of-content-entry-template text:outline-level="1"
+    text:style-name="Contents_20_1">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="2"
+    text:style-name="Contents_20_2">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="3"
+    text:style-name="Contents_20_3">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="4"
+    text:style-name="Contents_20_4">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="5"
+    text:style-name="Contents_20_5">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="6"
+    text:style-name="Contents_20_6">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="7"
+    text:style-name="Contents_20_7">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="8"
+    text:style-name="Contents_20_8">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="9"
+    text:style-name="Contents_20_9">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+    <text:table-of-content-entry-template text:outline-level="10"
+    text:style-name="Contents_20_10">
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-chapter />
+      <text:index-entry-text />
+      <text:index-entry-link-end />
+      <text:index-entry-tab-stop style:type="right"
+      style:leader-char="." />
+      <text:index-entry-link-start text:style-name="Internet_20_link" />
+      <text:index-entry-page-number />
+      <text:index-entry-link-end />
+    </text:table-of-content-entry-template>
+  </text:table-of-content-source>
+</text:table-of-content>
+$endif$
+$body$
+$for(include-after)$
+$include-after$
+$endfor$
+</office:text>
+</office:body>
+</office:document-content>

package/bin/md2nativedocx.mjs

@@ -22,11 +22,12 @@
  *   * Errors are typed (ParseError/TranslationError) and mapped to exit codes.
  */
 
-import { execFileSync } from 'node:child_process';
 import { basename, extname } from 'node:path';
-import { existsSync, writeFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { CliError, resolveSafePath } from '../src/cliSupport.mjs';
 import { ConversionError, convert } from '../src/convert.mjs';
+import { writeOutputSafely } from '../src/writeOutputSafely.mjs';
+import { formatWordCompatibility, runWordCompatibilityCheck } from '../src/wordCheck.mjs';
 import { hasLayoutOptions, readConvertOptionsFromEnv } from '../src/envOptions.mjs';
 
 // `-o something.pptx` takes the Pandoc-free deck path (packages/pptx), dispatched before anything a
@@ -40,13 +41,16 @@ import { hasLayoutOptions, readConvertOptionsFromEnv } from '../src/envOptions.m
   }
 }
 
-const USAGE = `Usage: md2nativedocx <input.md> -o <output.docx|output.pptx> [options]
+const USAGE = `Usage: md2nativedocx <input.md> -o <output.docx|output.odt|output.pptx> [options]
+
+A .odt output is for LibreOffice: flowcharts become native, editable shapes and connectors;
+other diagram types become a note for now.
 
 A .pptx output is a slide deck: one slide per \`\`\`mermaid block, titled with the nearest
 preceding heading (text outside diagrams is not exported).
 
 Options:
-  -o, --output <file>   Output .docx or .pptx path (required)
+  -o, --output <file>   Output .docx, .odt or .pptx path (required)
   --show-source         .pptx only: show each diagram's Mermaid source beside it
   -h, --help            Show this help
 `;
@@ -126,9 +130,18 @@ async function main() {
     process.exit(1);
   }
 
+  const format = extname(output).toLowerCase() === '.odt' ? 'odt' : 'docx';
+  if (format === 'odt' && hasLayoutOptions(options.layout)) {
+    process.stderr.write('md2nativedocx (info): page/typography options apply to .docx only; the .odt uses A4 with 2.54 cm margins.\n');
+  }
+  // MD2NATIVEDOCX_REFERENCE_DOC names a Word template; a .odt keeps the bundled reference.odt.
+  const formatOptions = format === 'odt' && options.referenceDoc && extname(options.referenceDoc).toLowerCase() !== '.odt'
+    ? { ...options, referenceDoc: undefined }
+    : options;
+
   let result;
   try {
-    result = await convert({ path: input }, { ...options, cwd });
+    result = await convert({ path: input }, { ...formatOptions, cwd, format });
   } catch (err) {
     if (err instanceof ConversionError) {
       process.stderr.write(`md2nativedocx: ${err.message}\n`);
@@ -138,12 +151,20 @@ async function main() {
     }
     throw err;
   }
-  writeFileSync(output, result.document);
+  try {
+    writeOutputSafely(output, result.document);
+  } catch (err) {
+    if (err instanceof ConversionError) {
+      process.stderr.write(`md2nativedocx: ${err.message}\n`);
+      process.exit(2);
+    }
+    throw err;
+  }
 
   // Surface the diagrams' non-fatal notices: never let a successful export silently hide something the
   // author should know about.
   const warnings = result.warnings.map((w) => `md2nativedocx: ${w}`);
-  const wordCompatibility = runWordCompatibilityCheck(output);
+  const wordCompatibility = format === 'docx' ? runWordCompatibilityCheck(output) : null;
   const logPath = writeExportLog({ input, output, warnings, rawStderr: result.pandocStderr, wordCompatibility });
   if (warnings.length > 0) {
     process.stdout.write(`Warnings: ${warnings.length} (see ${basename(logPath)})\n`);
@@ -152,74 +173,13 @@ async function main() {
   process.stdout.write(`Wrote ${basename(output)}\n`);
 }
 
-/**
- * Word compatibility check (ADR 0007 part D) — validates the generated
- * `.docx` against the exact schema real Word enforces strictly, via
- * `scripts/oxml-validator/`'s DLL (Microsoft's own Open XML SDK). See
- * `AGENTS.md` → "Diagnosing 'Word won't open the file'" and ADR 0006 for
- * why this exists: neither well-formed-XML checks nor LibreOffice (which
- * this project already uses for `test:visual`) can catch a schema
- * violation Word rejects outright — that gap cost 7 rounds of
- * manually-compared, individually-disproven hypotheses in the SmartArt
- * "cycle" corruption incident before this validator found the real cause
- * in a single pass.
- *
- * Opt-in via `MD2NATIVEDOCX_OXML_VALIDATOR_DLL` (the vendored DLL path,
- * set by the VS Code extension's `dotnetProvisioner.ts` when
- * `md2nativedocx.wordCompatibilityCheck.enabled` is on) — unset for a
- * standalone `npx md2nativedocx` install, which doesn't ship the DLL, so
- * this is a no-op there unless a user sets both env vars by hand.
- * `MD2NATIVEDOCX_DOTNET_BIN` mirrors `MD2NATIVEDOCX_PANDOC_BIN`'s own
- * "defaults to the bare command name, letting a provisioner override it"
- * convention.
- *
- * Never throws: an export that already succeeded must never be reported as
- * failed because this optional, best-effort check couldn't run (`dotnet`
- * missing, DLL missing, unexpected crash) — same rule already applied to
- * `extractWarnings`/`readWarningCount` elsewhere in this pipeline. Returns
- * `null` when not run at all (env var unset), or
- * `{ ran: true, diagramErrors, otherErrors }` /
- * `{ ran: false, reason }` otherwise.
- */
-function runWordCompatibilityCheck(docxPath) {
-  const dllPath = process.env.MD2NATIVEDOCX_OXML_VALIDATOR_DLL;
-  if (!dllPath) return null;
-
-  const dotnetBin = process.env.MD2NATIVEDOCX_DOTNET_BIN || 'dotnet';
-  try {
-    const stdout = execFileSync(dotnetBin, [dllPath, docxPath, '--json'], { encoding: 'utf8' });
-    const report = JSON.parse(stdout.trim().split('\n').pop());
-    const diagramErrors = report.errors.filter((e) => e.Part?.startsWith('/word/diagrams/'));
-    const otherErrors = report.errors.filter((e) => !e.Part?.startsWith('/word/diagrams/'));
-    return { ran: true, diagramErrors, otherErrors };
-  } catch (err) {
-    // execFileSync throws on a non-zero exit (errorCount > 0 also exits 1,
-    // per scripts/oxml-validator/OpenXmlValidator.cs) -- but it still wrote
-    // the JSON report to stdout first, captured on the error object.
-    const stdout = err.stdout?.toString();
-    if (stdout) {
-      try {
-        const report = JSON.parse(stdout.trim().split('\n').pop());
-        if (Array.isArray(report.errors)) {
-          const diagramErrors = report.errors.filter((e) => e.Part?.startsWith('/word/diagrams/'));
-          const otherErrors = report.errors.filter((e) => !e.Part?.startsWith('/word/diagrams/'));
-          return { ran: true, diagramErrors, otherErrors };
-        }
-      } catch {
-        // Fall through to the generic "could not run" case below.
-      }
-    }
-    return { ran: false, reason: err instanceof Error ? err.message : String(err) };
-  }
-}
-
 /** Write a plain-text log next to the output .docx (same basename, `.log`
  * extension) so a click-right export (no VS Code Problems panel in view) has
  * somewhere durable to point to — spec §10, "surface warnings". Written on
  * every successful export, not just when there are warnings, for a
  * consistent, discoverable location. */
 function writeExportLog({ input, output, warnings, rawStderr, wordCompatibility }) {
-  const logPath = extname(output).toLowerCase() === '.docx'
+  const logPath = ['.docx', '.odt'].includes(extname(output).toLowerCase())
     ? output.slice(0, -extname(output).length) + '.log'
     : `${output}.log`;
   const lines = [
@@ -239,35 +199,10 @@ function writeExportLog({ input, output, warnings, rawStderr, wordCompatibility
   if (rawStderr && rawStderr.trim().length > 0) {
     lines.push('--- Raw Pandoc/tool output ---', rawStderr.trimEnd(), '');
   }
-  writeFileSync(logPath, lines.join('\n'), 'utf8');
+  writeOutputSafely(logPath, lines.join('\n'));
   return logPath;
 }
 
-/** Renders {@link runWordCompatibilityCheck}'s result as `.log` lines. Kept
- * separate from that function so the "not run at all" (feature off) case
- * reads as a plain, unalarming note rather than something that looks like a
- * missing/failed check — most exports won't have this env var set at all
- * (standalone CLI usage, or the VS Code setting turned off). */
-function formatWordCompatibility(result) {
-  if (result === null) {
-    return ['Not checked (md2nativedocx.wordCompatibilityCheck is off, or this is a standalone CLI export).'];
-  }
-  if (!result.ran) {
-    return [`Not checked (could not run: ${result.reason}).`];
-  }
-  if (result.diagramErrors.length === 0) {
-    const note = result.otherErrors.length > 0
-      ? ` (${result.otherErrors.length} pre-existing schema note(s) elsewhere, unrelated to this export's diagram content — see TODO.md)`
-      : '';
-    return [`0 error(s) — validated against the same schema Word itself enforces.${note}`];
-  }
-  const lines = [`${result.diagramErrors.length} error(s) found in the generated diagram content:`];
-  for (const e of result.diagramErrors) {
-    lines.push(`  - ${e.Path}: ${e.Description}`);
-  }
-  return lines;
-}
-
 main().catch((err) => {
   process.stderr.write(`md2nativedocx: ${err instanceof Error ? err.message : String(err)}\n`);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@md2nativedocx/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Complete Markdown to Word (.docx) converter, or PowerPoint (.pptx), with editable diagrams — all 29 Mermaid types become real shapes, SmartArt and charts that readers can change in Word, not flattened PNGs.",
   "license": "CC0-1.0",
   "repository": {
@@ -46,7 +46,8 @@
   "files": [
     "bin",
     "src",
-    "assets"
+    "assets",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "scripts": {
     "build": "echo \"cli: no build step (plain JS)\"",
@@ -56,8 +57,8 @@
     "test:ci": "node --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=reports/junit.xml test/*.test.mjs"
   },
   "dependencies": {
-    "@md2nativedocx/pandoc-filter": "0.1.0",
-    "@md2nativedocx/pptx": "0.1.0",
+    "@md2nativedocx/pandoc-filter": "0.2.0",
+    "@md2nativedocx/pptx": "0.1.1",
     "adm-zip": "^0.6.1"
   }
 }

package/src/cliSupport.mjs

@@ -3,7 +3,7 @@
  * the .pptx path in `pptxExport.mjs`).
  */
 
-import { resolve, isAbsolute } from 'node:path';
+import { resolve, isAbsolute, relative, sep } from 'node:path';
 
 /** Typed error for CLI-level failures. */
 export class CliError extends Error {
@@ -17,10 +17,12 @@ export class CliError extends Error {
 /** Resolve and validate a path (anti path traversal via `..`). */
 export function resolveSafePath(rawPath, cwd) {
   const abs = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
-  // Reject relative paths that escape the working directory via `..`.
+  // Reject relative paths that escape the working directory via `..`. Compared through
+  // path.relative, not a `root + '/'` prefix: that never matched a Windows path (`\`), so every
+  // relative path was refused there (found 2026-10-08 by the .odt CLI tests on the Windows runner).
   if (!isAbsolute(rawPath)) {
-    const root = resolve(cwd);
-    if (!abs.startsWith(root + '/') && abs !== root) {
+    const rel = relative(resolve(cwd), abs);
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
       throw new CliError(`Path escapes the working directory: ${rawPath}`, 2);
     }
   }

package/src/convert.d.mts

@@ -33,6 +33,12 @@ export interface LayoutOptions {
 
 /** How {@link convert} builds the document. Every field is optional; the defaults match the CLI's. */
 export interface ConvertOptions {
+  /**
+   * `docx` (default) or `odt`. A `.odt` draws flowcharts as native LibreOffice shapes (other diagram types
+   * become a note for now); `layout`, `emojiFont`, SmartArt and native charts apply to `.docx` only, and
+   * `referenceDoc`, when given, must then be a `.odt`.
+   */
+  format?: 'docx' | 'odt';
   /** Pandoc's working directory, against which relative image paths resolve. Default: `process.cwd()`. */
   cwd?: string;
   /** A `.docx` template to use instead of the bundled one (Pandoc's `--reference-doc`). Must exist. */
@@ -64,7 +70,7 @@ export interface ConvertOptions {
 
 /** A finished document. */
 export interface ConvertResult {
-  /** The `.docx` file's bytes. */
+  /** The `.docx` (or `.odt`) file's bytes. */
   document: Buffer;
   /** Non-fatal problems in the diagrams (syntax ignored, a SmartArt or chart drawn as shapes instead). */
   warnings: string[];
@@ -74,8 +80,8 @@ export interface ConvertResult {
 
 /** A conversion that produced no document. */
 export declare class ConversionError extends Error {
-  /** `setup`: filter or reference document · `pandoc`: Pandoc failed or is missing · `postprocess`. */
-  readonly stage: 'setup' | 'pandoc' | 'postprocess';
+  /** `setup`: filter or reference document · `pandoc`: Pandoc failed or is missing · `postprocess` · `write`: the output file could not be written (open in Word, locked). */
+  readonly stage: 'setup' | 'pandoc' | 'postprocess' | 'write';
   /** Pandoc's stderr, when it ran. */
   readonly pandocStderr: string;
 }

package/src/convert.mjs

@@ -1,5 +1,6 @@
 /**
- * `convert()`: Markdown in, finished `.docx` bytes out (docs/specs/01-v2-engine-spec.md §6, ADR 0012).
+ * `convert()`: Markdown in, finished `.docx` (or `.odt`) bytes out (docs/specs/01-v2-engine-spec.md §6,
+ * ADR 0012; `.odt`: ADR 0013).
  *
  * The library entry point of `@md2nativedocx/cli`, and what `bin/md2nativedocx.mjs` itself calls. It owns
  * the whole document path: reference document build, Pandoc with the Lua filter (which renders each
@@ -11,6 +12,11 @@
  * the options, so a host process's environment cannot change a conversion behind its caller's back. The
  * variables remain the CLI's interface (`envOptions.mjs` reads them).
  *
+ * `format: 'odt'` hands Pandoc the derived `opendocument` template and the project's `reference.odt`
+ * (`assets/`, built by `scripts/build-odt-assets.mjs`), and the filter draws each flowchart as native
+ * ODF shapes. Nothing touches the `.odt` Pandoc writes (AGENTS.md rule 7). Page and typography options,
+ * SmartArt, charts and the emoji font are `.docx` features and do not apply.
+ *
  * Security (AGENTS.md): Pandoc runs through `execFile` with an argument array (rule 4); every file is written
  * in a fresh temporary directory removed afterwards; the post-processing is the rule 7 allowlist.
  */
@@ -21,6 +27,7 @@ import { tmpdir } from 'node:os';
 import { extname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { postProcessDocx, injectSmartArtParts } from './postprocess.mjs';
+import { unclosedFenceWarnings } from './unclosedFences.mjs';
 import { injectChartParts } from './chartParts.mjs';
 import { buildReferenceDoc, resolveMaxDrawingExtentEmu, resolvePageSize, resolveMargins } from './referenceDocBuilder.mjs';
 
@@ -28,7 +35,7 @@ import { buildReferenceDoc, resolveMaxDrawingExtentEmu, resolvePageSize, resolve
 export class ConversionError extends Error {
   /**
    * @param {string} message
-   * @param {{ stage: 'setup' | 'pandoc' | 'postprocess', pandocStderr?: string, cause?: unknown }} details
+   * @param {{ stage: 'setup' | 'pandoc' | 'postprocess' | 'write', pandocStderr?: string, cause?: unknown }} details
    */
   constructor(message, { stage, pandocStderr = '', cause } = {}) {
     super(message, cause === undefined ? undefined : { cause });
@@ -43,6 +50,12 @@ export class ConversionError extends Error {
 // 2007-2010 Office theme. See packages/cli/assets/README.md for how it was built and what it changes.
 // `src/` and `bin/` are at the same depth, so this also holds in the VS Code extension's vendored bundle.
 const DEFAULT_REFERENCE_DOC = fileURLToPath(new URL('../assets/reference.docx', import.meta.url));
+// The `.odt` pair (ADR 0013): the project's own reference.odt (A4, 2.54 cm margins, diagram markers) and
+// Pandoc's opendocument template plus the diagram-styles loop. See packages/cli/assets/README.md.
+const DEFAULT_REFERENCE_ODT = fileURLToPath(new URL('../assets/reference.odt', import.meta.url));
+const ODT_TEMPLATE = fileURLToPath(new URL('../assets/md2nativedocx.opendocument', import.meta.url));
+/** 9 in in EMU: the `.docx` output's default drawing height (core's `MAX_DRAWING_CY`). */
+const ODT_MAX_DRAWING_CY = 8229600;
 
 /**
  * Where @md2nativedocx/pandoc-filter lands varies with how the CLI was deployed (npm workspace, nested or
@@ -122,8 +135,72 @@ function extractWarnings(stderrText) {
     .map((line) => line.slice('md2nativedocx: '.length));
 }
 
+/** Warnings about the source text itself, found before Pandoc runs (an unclosed ```mermaid fence). */
+function sourceWarnings(source) {
+  let text;
+  try {
+    text = typeof source === 'string' ? source : readFileSync(source.path, 'utf8');
+  } catch {
+    // An unreadable input is Pandoc's error to report with its own message; this check is only advisory.
+    return [];
+  }
+  return unclosedFenceWarnings(text);
+}
+
+/** Where Pandoc reads from: the given file, or the text written to `work/input.md`. */
+function inputFile(source, work) {
+  if (typeof source !== 'string') return source.path;
+  const inputPath = join(work, 'input.md');
+  writeFileSync(inputPath, source, 'utf8');
+  return inputPath;
+}
+
+/** Pandoc's reader and table-of-contents arguments, shared by both formats. */
+function commonPandocArgs(inputPath, options) {
+  const args = [];
+  // Pandoc picks its reader from the extension and does not know `.qmd`; Quarto Markdown is Pandoc
+  // Markdown plus front matter and code chunks, so naming the reader is correct and drops its warning.
+  if (extname(inputPath).toLowerCase() === '.qmd') args.push('--from', 'markdown');
+  const tocDepth = Math.min(4, Math.max(2, Math.round(options.tocDepth ?? 3)));
+  if (options.toc) args.push('--toc', `--toc-depth=${tocDepth}`);
+  return args;
+}
+
+/** The `.odt` path: Pandoc writes the whole package, nothing is done to it afterwards (rule 7). */
+async function convertOdt(source, options) {
+  const filterPath = resolveFilterPath();
+  const cwd = options.cwd ?? process.cwd();
+  const referenceDoc = options.referenceDoc ?? DEFAULT_REFERENCE_ODT;
+  if (!existsSync(referenceDoc)) {
+    throw new ConversionError(`reference document not found: ${referenceDoc}`, { stage: 'setup' });
+  }
+  if (extname(referenceDoc).toLowerCase() !== '.odt') {
+    throw new ConversionError(`a .odt output needs a .odt reference document, got ${referenceDoc}`, { stage: 'setup' });
+  }
+  const work = mkdtempSync(join(tmpdir(), 'md2nativedocx-convert-'));
+  try {
+    const inputPath = inputFile(source, work);
+    const outputPath = join(work, 'output.odt');
+    const pandocArgs = [inputPath, '-o', outputPath, '--lua-filter', filterPath, '--template', ODT_TEMPLATE, '--reference-doc', referenceDoc];
+    pandocArgs.push(...commonPandocArgs(inputPath, options));
+    // Diagrams are scaled to fit the bundled reference.odt's text width (A4, 2.54 cm margins) and at most
+    // 9 in high, the `.docx` default, which leaves room for a heading above a page-tall diagram instead of
+    // pushing it alone onto the next page.
+    const page = resolveMaxDrawingExtentEmu({ pageSize: 'A4' });
+    const env = pandocEnvironment(
+      { ...options, smartArtStyle: undefined, smartArtDrawing: undefined },
+      { smartArtDir: null, chartDir: null, maxDrawingExtentEmu: { cx: page.cx, cy: Math.min(page.cy, ODT_MAX_DRAWING_CY) }, landscapeGeometry: null },
+    );
+    const pandocStderr = await runPandoc(options.pandocBin ?? 'pandoc', pandocArgs, { cwd, env });
+    return { document: readFileSync(outputPath), warnings: [...sourceWarnings(source), ...extractWarnings(pandocStderr)], pandocStderr };
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
 /**
- * Convert a Markdown document to `.docx`. See `convert.d.mts` for the option and result types.
+ * Convert a Markdown document to `.docx`, or `.odt` with `format: 'odt'`. See `convert.d.mts` for the
+ * option and result types.
  *
  * @param {string | { path: string }} source Markdown text, or a file for Pandoc to read (its extension picks
  *   the reader; `.qmd` is read as Markdown).
@@ -131,6 +208,11 @@ function extractWarnings(stderrText) {
  * @returns {Promise<import('./convert.d.mts').ConvertResult>}
  */
 export async function convert(source, options = {}) {
+  const format = options.format ?? 'docx';
+  if (format !== 'docx' && format !== 'odt') {
+    throw new ConversionError(`unknown format ${JSON.stringify(format)}; expected "docx" or "odt"`, { stage: 'setup' });
+  }
+  if (format === 'odt') return convertOdt(source, options);
   const filterPath = resolveFilterPath();
   const cwd = options.cwd ?? process.cwd();
   const customReferenceDoc = options.referenceDoc;
@@ -151,22 +233,12 @@ export async function convert(source, options = {}) {
     }
     const referenceDoc = customReferenceDoc ?? generatedReferenceDoc?.path ?? DEFAULT_REFERENCE_DOC;
 
-    let inputPath;
-    if (typeof source === 'string') {
-      inputPath = join(work, 'input.md');
-      writeFileSync(inputPath, source, 'utf8');
-    } else {
-      inputPath = source.path;
-    }
+    const inputPath = inputFile(source, work);
     const outputPath = join(work, 'output.docx');
 
     const pandocArgs = [inputPath, '-o', outputPath, '--lua-filter', filterPath];
-    // Pandoc picks its reader from the extension and does not know `.qmd`; Quarto Markdown is Pandoc
-    // Markdown plus front matter and code chunks, so naming the reader is correct and drops its warning.
-    if (extname(inputPath).toLowerCase() === '.qmd') pandocArgs.push('--from', 'markdown');
     if (existsSync(referenceDoc)) pandocArgs.push('--reference-doc', referenceDoc);
-    const tocDepth = Math.min(4, Math.max(2, Math.round(options.tocDepth ?? 3)));
-    if (options.toc) pandocArgs.push('--toc', `--toc-depth=${tocDepth}`);
+    pandocArgs.push(...commonPandocArgs(inputPath, options));
 
     // The bridge (one run per ```mermaid block, spawned by the Lua filter) hands SmartArt and chart parts
     // back through these directories: a Lua filter cannot add package parts itself.
@@ -194,7 +266,7 @@ export async function convert(source, options = {}) {
       throw new ConversionError(`post-processing failed: ${errorMessage(err)}`, { stage: 'postprocess', pandocStderr, cause: err });
     }
 
-    return { document: readFileSync(outputPath), warnings: extractWarnings(pandocStderr), pandocStderr };
+    return { document: readFileSync(outputPath), warnings: [...sourceWarnings(source), ...extractWarnings(pandocStderr)], pandocStderr };
   } finally {
     rmSync(work, { recursive: true, force: true });
     if (generatedReferenceDoc) rmSync(generatedReferenceDoc.dir, { recursive: true, force: true });

package/src/pptxExport.mjs

@@ -5,9 +5,11 @@
  * (see docs/adr/0010-pptx-production-translator-plan.md). Non-diagram Markdown is ignored.
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { basename, extname } from 'node:path';
 import { CliError, resolveSafePath } from './cliSupport.mjs';
+import { ConversionError } from './convert.mjs';
+import { writeOutputSafely } from './writeOutputSafely.mjs';
 
 const USAGE = `Usage: md2nativedocx <input.md> -o <output.pptx> [--show-source]
 
@@ -57,7 +59,12 @@ export async function runPptxCli(argv, cwd) {
       if (err instanceof PptxConversionError) throw new CliError(`md2nativedocx: ${err.message}`, 1);
       throw err;
     }
-    writeFileSync(output, result.buffer);
+    try {
+      writeOutputSafely(output, result.buffer);
+    } catch (err) {
+      if (err instanceof ConversionError) throw new CliError(`md2nativedocx: ${err.message}`, 2);
+      throw err;
+    }
     writePptxLog(input, output, result.warnings, result.slideCount);
     if (result.warnings.length > 0) {
       process.stdout.write(`Warnings: ${result.warnings.length}\n`);
@@ -91,5 +98,5 @@ function writePptxLog(input, output, warnings, slideCount) {
     `Slides: ${slideCount}`,
     '',
   ];
-  writeFileSync(logPath, lines.join('\n'), 'utf8');
+  writeOutputSafely(logPath, lines.join('\n'));
 }

package/src/referenceDocBuilder.mjs

@@ -282,7 +282,11 @@ function patchTableHeaderColor(stylesXml, tableHeaderColor) {
     /(<w:style[^>]*\bw:styleId="Table"[^>]*>[\s\S]*?<w:tblStylePr w:type="firstRow">[\s\S]*?<w:tcPr>)([\s\S]*?)(<\/w:tcPr>)/,
     (whole, open, inner, close) => {
       const shd = `<w:shd w:val="clear" w:color="auto" w:fill="${safe}"/>`;
-      const nextInner = /<w:shd\b[^>]*\/>/.test(inner) ? inner.replace(/<w:shd\b[^>]*\/>/, shd) : `${inner}${shd}`;
+      // Schema order inside w:tcPr puts w:shd after w:tcBorders and before w:vAlign.
+      let nextInner;
+      if (/<w:shd\b[^>]*\/>/.test(inner)) nextInner = inner.replace(/<w:shd\b[^>]*\/>/, shd);
+      else if (/<w:vAlign\b/.test(inner)) nextInner = inner.replace(/<w:vAlign\b/, `${shd}<w:vAlign`);
+      else nextInner = `${inner}${shd}`;
       return `${open}${nextInner}${close}`;
     },
   );

package/src/unclosedFences.mjs

@@ -0,0 +1,48 @@
+// Unclosed ```mermaid fence detection (TODO §R1.5). Pandoc turns an unterminated fence into a code block
+// running to the end of the file, without any warning: the diagram and everything after it silently stop
+// being converted. This is a pre-Pandoc check so the export log can say so.
+//
+// Mirrors `packages/vscode-extension/src/mermaidBlocks.ts` (`findUnclosedMermaidFences`): the extension
+// is TypeScript and bundles this package as a vendored copy, so the few lines are kept in both places.
+
+const ANY_FENCE = /^(`{3,}|~{3,})/;
+const OPEN_MERMAID = /^(`{3,})\s*mermaid\s*$/i;
+
+/**
+ * Lines (1-based) of every ```mermaid fence that is never closed.
+ * Other fenced blocks are skipped wholesale, as Pandoc does, so a mermaid fence shown inside a longer
+ * ````-fenced example is not reported.
+ * @param {string} text
+ * @returns {number[]}
+ */
+export function findUnclosedMermaidFenceLines(text) {
+  const lines = text.split(/\r\n|\r|\n/);
+  const unclosed = [];
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = (lines[i] ?? '').trim();
+    const mermaid = OPEN_MERMAID.exec(trimmed);
+    const marker = mermaid?.[1] ?? ANY_FENCE.exec(trimmed)?.[1];
+    if (!marker) continue;
+    const close = new RegExp(`^${marker}\\s*$`);
+    let j = i + 1;
+    while (j < lines.length && !close.test((lines[j] ?? '').trim())) j++;
+    if (j >= lines.length) {
+      // An unterminated fence runs to the end of the file: nothing after it is parsed either.
+      if (mermaid) unclosed.push(i + 1);
+      break;
+    }
+    i = j;
+  }
+  return unclosed;
+}
+
+/**
+ * Export-log warnings for every unclosed ```mermaid fence in `text`.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function unclosedFenceWarnings(text) {
+  return findUnclosedMermaidFenceLines(text).map(
+    (line) => `warning: line ${line}: the \`\`\`mermaid block is never closed, so Pandoc treats everything from there to the end of the file as plain code and no diagram is converted. Add a closing \`\`\` line.`,
+  );
+}

package/src/wordCheck.mjs

@@ -0,0 +1,125 @@
+// Word compatibility check (ADR 0007 part D, TODO §R1.4). Validates the generated `.docx` against the
+// schema real Word enforces (Open XML SDK) and says, part by part, what was actually checked. It never
+// claims an effect on how Word opens the file: the validator cannot know that.
+import { execFileSync } from 'node:child_process';
+
+/** Pandoc release the "known Pandoc" signatures below were recorded against (2026-11-13). */
+export const PANDOC_SIGNATURES_VERSION = '3.1.3';
+
+// Parts only this project writes (diagrams, charts and their embedded workbooks).
+const OWN_PARTS = ['/word/diagrams/', '/word/charts/', '/word/embeddings/'];
+// Elements inside `word/document.xml` that only this project writes: the inline drawing canvas, its
+// shapes, the SmartArt/chart frames and the alternate-content wrappers around them.
+const OWN_PATH = /\/(wpc|wps|wp|a|pic|dgm|c|mc|w14|wp14):|\/w:drawing\b/;
+
+/**
+ * Known noise from Pandoc's own `.docx` writer: a closed list of signatures, each pinned to a part and to
+ * the shape of the validator message. Anything not matching is reported as an error.
+ * @type {ReadonlyArray<{ name: string, part: string, path: RegExp, description?: RegExp }>}
+ */
+const PANDOC_SIGNATURES = [
+  { name: 'syntax-highlighting styles', part: '/word/styles.xml', path: /\/w:style\[\d+\]\/w:rPr\[1\]$/, description: /unexpected child element/ },
+  { name: 'list numbering ids (w:nsid)', part: '/word/numbering.xml', path: /\/w:nsid\[1\]$/ },
+  { name: 'settings (w:doNotTrackMoves)', part: '/word/settings.xml', path: /^\/w:settings\[1\]$/, description: /doNotTrackMoves/ },
+  { name: 'table properties', part: '/word/document.xml', path: /\/w:tbl\[\d+\]\/(w:tblPr\[1\](\/w:jc\[1\])?|w:tr\[\d+\]\/w:trPr\[1\]\/w:tblHeader\[1\])$/ },
+  { name: 'list paragraph properties', part: '/word/document.xml', path: /^\/w:document\[1\]\/w:body\[1\]\/w:p\[\d+\]\/w:pPr\[1\]$/, description: /unexpected child element .*pStyle/ },
+];
+
+/**
+ * Sort validator errors into what this project writes, Pandoc's known noise, and everything else.
+ * Own output wins over a known signature, so a diagram error can never be hidden as Pandoc noise.
+ *
+ * @param {ReadonlyArray<{ Part?: string, Path?: string, Description?: string }>} errors
+ * @returns {{ own: object[], pandoc: object[], other: object[] }}
+ */
+export function classifyValidatorErrors(errors) {
+  const own = [];
+  const pandoc = [];
+  const other = [];
+  for (const e of errors) {
+    const part = e.Part ?? '';
+    const path = e.Path ?? '';
+    if (OWN_PARTS.some((p) => part.startsWith(p)) || (part === '/word/document.xml' && OWN_PATH.test(path))) {
+      own.push(e);
+    } else if (PANDOC_SIGNATURES.some((sig) => sig.part === part && sig.path.test(path) && (!sig.description || sig.description.test(e.Description ?? '')))) {
+      pandoc.push(e);
+    } else {
+      other.push(e);
+    }
+  }
+  return { own, pandoc, other };
+}
+
+/** @param {string} stdout */
+function parseReport(stdout) {
+  const report = JSON.parse(stdout.trim().split('\n').pop());
+  if (!Array.isArray(report.errors)) throw new TypeError('validator report has no errors list');
+  return { ran: true, ...classifyValidatorErrors(report.errors) };
+}
+
+/**
+ * Run the validator on `docxPath` when `MD2NATIVEDOCX_OXML_VALIDATOR_DLL` is set.
+ *
+ * Never throws: an export that already succeeded must never be reported as failed because this
+ * optional check could not run. Returns `null` when off, `{ ran: true, own, pandoc, other }`, or
+ * `{ ran: false, reason }`.
+ * @param {string} docxPath
+ */
+export function runWordCompatibilityCheck(docxPath) {
+  const dllPath = process.env.MD2NATIVEDOCX_OXML_VALIDATOR_DLL;
+  if (!dllPath) return null;
+  const dotnetBin = process.env.MD2NATIVEDOCX_DOTNET_BIN || 'dotnet';
+  try {
+    return parseReport(execFileSync(dotnetBin, [dllPath, docxPath, '--json'], { encoding: 'utf8' }));
+  } catch (err) {
+    // A non-zero exit (errorCount > 0) still wrote the JSON report to stdout first.
+    const stdout = err?.stdout?.toString();
+    if (stdout) {
+      try {
+        return parseReport(stdout);
+      } catch {
+        // Not a usable report: fall through to the "could not run" case.
+      }
+    }
+    return { ran: false, reason: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/** @param {{ Path?: string, Description?: string }} e */
+const errorLine = (e) => `  - ${e.Path}: ${e.Description}`;
+
+/**
+ * Render a check result as `.log` lines: one statement per part of the document, saying what was
+ * validated and what was found, never what Word will do.
+ * @param {ReturnType<typeof runWordCompatibilityCheck>} result
+ * @returns {string[]}
+ */
+export function formatWordCompatibility(result) {
+  if (result === null) {
+    return ['Not checked (md2nativedocx.wordCompatibilityCheck is off, or this is a standalone CLI export).'];
+  }
+  if (!result.ran) return [`Not checked (could not run: ${result.reason}).`];
+
+  const lines = [];
+  lines.push(
+    result.own.length === 0
+      ? 'Diagrams and charts (written by md2nativedocx): no schema error found.'
+      : `Diagrams and charts (written by md2nativedocx): ${result.own.length} schema error(s):`,
+    ...result.own.map(errorLine),
+  );
+  const rest = [];
+  if (result.pandoc.length > 0) {
+    const names = [...new Set(PANDOC_SIGNATURES.filter((sig) => result.pandoc.some((e) => e.Part === sig.part && sig.path.test(e.Path ?? ''))).map((sig) => sig.name))];
+    rest.push(`${result.pandoc.length} known schema deviation(s) written by Pandoc itself (${names.join('; ')}; signatures recorded with Pandoc ${PANDOC_SIGNATURES_VERSION}).`);
+  }
+  if (result.other.length > 0) {
+    rest.push(`${result.other.length} other schema error(s):`);
+  }
+  lines.push(
+    rest.length === 0 ? 'Rest of the document (written by Pandoc): no schema error found.' : `Rest of the document (written by Pandoc): ${rest.shift()}`,
+    ...rest,
+    ...result.other.map(errorLine),
+  );
+  lines.push('This is a validation against the Open XML schema; it does not predict how Word will behave.');
+  return lines;
+}

package/src/writeOutputSafely.mjs

@@ -0,0 +1,69 @@
+// Safe output writing (TODO §R1.1). Word keeps an exclusive handle on an open document and drops a
+// `~$` lock file beside it; overwriting under it (notably on OneDrive) corrupts or loses the file.
+// This module refuses in those cases, and otherwise swaps the new file in atomically so the previous
+// target is never truncated.
+import { closeSync, existsSync, fsyncSync, openSync, renameSync, rmSync, writeSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { ConversionError } from './convert.mjs';
+
+/**
+ * Names of the lock files Word creates for `fileName`: `~$` + the full name, and, for long names,
+ * `~$` + the name without its first 2 characters.
+ * @param {string} fileName
+ * @returns {string[]}
+ */
+export function wordLockFileNames(fileName) {
+  return [...new Set([`~$${fileName}`, `~$${fileName.slice(2)}`])];
+}
+
+/** @param {string} message @param {unknown} [cause] */
+function writeError(message, cause) {
+  return new ConversionError(message, { stage: 'write', cause });
+}
+
+/**
+ * Write `data` to `target` without ever truncating an existing file.
+ *
+ * Refuses (throws a {@link ConversionError} with `stage: 'write'`) when a Word lock file sits beside the
+ * target, or when the existing target cannot be opened for writing. Otherwise writes
+ * `<target>.<pid>.tmp` in the same folder, fsyncs it, and renames it over the target; the temporary is
+ * removed on failure.
+ *
+ * @param {string} target absolute output path
+ * @param {Buffer | string} data
+ */
+export function writeOutputSafely(target, data) {
+  const dir = dirname(target);
+  const name = basename(target);
+
+  for (const lock of wordLockFileNames(name)) {
+    if (existsSync(join(dir, lock))) {
+      throw writeError(`${name} is open in Word: close it or export under another name.`);
+    }
+  }
+
+  if (existsSync(target)) {
+    try {
+      closeSync(openSync(target, 'r+'));
+    } catch (err) {
+      throw writeError(`${name} cannot be overwritten (it is probably open in Word or another program): close it or export under another name.`, err);
+    }
+  }
+
+  const tmp = `${target}.${process.pid}.tmp`;
+  let fd;
+  try {
+    fd = openSync(tmp, 'w');
+    writeSync(fd, data);
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    renameSync(tmp, target);
+  } catch (err) {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* already failing; the original error is the one to report */ }
+    }
+    rmSync(tmp, { force: true });
+    throw writeError(`could not write ${name}: ${err instanceof Error ? err.message : String(err)}`, err);
+  }
+}