@md2nativedocx/cli 0.0.0-stage → 0.2.1

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@md2nativedocx/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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": {
+    "type": "git",
+    "url": "https://github.com/nicolasbridelance/md2nativedocx",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/nicolasbridelance/md2nativedocx#readme",
+  "bugs": {
+    "url": "https://github.com/nicolasbridelance/md2nativedocx/issues"
+  },
+  "keywords": [
+    "mermaid",
+    "mermaid-to-docx",
+    "markdown-to-docx",
+    "markdown-to-word",
+    "docx",
+    "pptx",
+    "word",
+    "powerpoint",
+    "diagram",
+    "editable",
+    "pandoc",
+    "ooxml",
+    "drawingml",
+    "markdown"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/convert.d.mts",
+      "default": "./src/convert.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./src/convert.d.mts",
+  "bin": {
+    "md2nativedocx": "bin/md2nativedocx.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "assets",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "build": "echo \"cli: no build step (plain JS)\"",
+    "typecheck": "echo \"cli: no typecheck step\"",
+    "test": "node --test test/*.test.mjs",
+    "pretest:ci": "mkdir -p reports",
+    "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.2.0",
+    "@md2nativedocx/pptx": "0.1.1",
+    "adm-zip": "^0.6.1"
+  }
+}

package/src/chartParts.mjs

@@ -0,0 +1,177 @@
+/**
+ * Native-chart hand-off (ADR 0011): completes the `c:chart` wiring for every diagram the core bridge
+ * dispatched to a native Word chart, and builds the embedded `.xlsx` workbook behind it.
+ *
+ * Same discipline as `postprocess.mjs`'s `injectSmartArtParts`, and within AGENTS.md rule 7's
+ * allowlist (new parts under `word/charts/` and `word/embeddings/`): it only **adds** parts, relationships and content types, never rewrites a part
+ * Pandoc wrote beyond swapping its own placeholder, and is a no-op when the document has no native
+ * chart. Every relationship it adds is internal (no `TargetMode`, rule 3). The workbook is a small zip
+ * written with `adm-zip`, already a dependency of this package, so no new dependency (rule 6).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { AdmZip, readZipEntry, setZipEntry } from './zipUtils.mjs';
+
+const PLACEHOLDER_RE = /CHART_PLACEHOLDER:([A-Za-z0-9-]+)/g;
+const REL_BASE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+const CHART_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.drawingml.chart+xml';
+const XLSX_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+const XML_DECL = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+
+/** Strict XML escaping of user-controlled text (AGENTS.md rule #2). */
+function esc(text) {
+  return String(text)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/** Column letters for a 0-based index: A..Z, AA..AZ, … */
+function col(index) {
+  let n = index;
+  let out = '';
+  do {
+    out = String.fromCharCode(65 + (n % 26)) + out;
+    n = Math.floor(n / 26) - 1;
+  } while (n >= 0);
+  return out;
+}
+
+function textCell(ref, text) {
+  return `<c r="${ref}" t="inlineStr"><is><t xml:space="preserve">${esc(text)}</t></is></c>`;
+}
+
+/**
+ * Build the embedded workbook: one sheet, a header row, then one row per category (label, then one
+ * value per series; an `undefined`/`null` value is an empty cell).
+ *
+ * @param {{ sheetName: string, header: string[], rows: Array<[string, ...Array<number|null|undefined>]> }} data
+ * @returns {Buffer} the `.xlsx` file
+ */
+export function buildWorkbookXlsx(data) {
+  const headerRow = `<row r="1">${data.header.map((h, c) => textCell(`${col(c)}1`, h)).join('')}</row>`;
+  const dataRows = data.rows.map((row, i) => {
+    const r = i + 2;
+    const [label, ...values] = row;
+    const cells = values
+      .map((value, c) => {
+        if (value === undefined || value === null) return '';
+        const n = Number(value);
+        if (!Number.isFinite(n)) throw new Error('md2nativedocx: chart value is not a finite number');
+        return `<c r="${col(c + 1)}${r}"><v>${n}</v></c>`;
+      })
+      .join('');
+    return `<row r="${r}">${textCell(`A${r}`, label)}${cells}</row>`;
+  });
+  const rows = [headerRow, ...dataRows].join('');
+  const main = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main';
+  const zip = new AdmZip();
+  const add = (name, xml) => zip.addFile(name, Buffer.from(XML_DECL + xml, 'utf8'));
+  add(
+    '[Content_Types].xml',
+    '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">' +
+      '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>' +
+      '<Default Extension="xml" ContentType="application/xml"/>' +
+      '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>' +
+      '<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>' +
+      '<Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>' +
+      '</Types>',
+  );
+  add(
+    '_rels/.rels',
+    `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="${REL_BASE}/officeDocument" Target="xl/workbook.xml"/></Relationships>`,
+  );
+  add(
+    'xl/workbook.xml',
+    `<workbook xmlns="${main}" xmlns:r="${REL_BASE}"><sheets><sheet name="${esc(data.sheetName)}" sheetId="1" r:id="rId1"/></sheets></workbook>`,
+  );
+  add(
+    'xl/_rels/workbook.xml.rels',
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+      `<Relationship Id="rId1" Type="${REL_BASE}/worksheet" Target="worksheets/sheet1.xml"/>` +
+      `<Relationship Id="rId2" Type="${REL_BASE}/styles" Target="styles.xml"/>` +
+      '</Relationships>',
+  );
+  add('xl/worksheets/sheet1.xml', `<worksheet xmlns="${main}"><sheetData>${rows}</sheetData></worksheet>`);
+  add(
+    'xl/styles.xml',
+    `<styleSheet xmlns="${main}"><fonts count="1"><font><sz val="11"/><name val="Calibri"/></font></fonts>` +
+      '<fills count="2"><fill><patternFill patternType="none"/></fill><fill><patternFill patternType="gray125"/></fill></fills>' +
+      '<borders count="1"><border><left/><right/><top/><bottom/><diagonal/></border></borders>' +
+      '<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>' +
+      '<cellXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/></cellXfs></styleSheet>',
+  );
+  return zip.toBuffer();
+}
+
+function nextChartNumber(zip) {
+  let max = 0;
+  for (const entry of zip.getEntries()) {
+    const m = /^word\/charts\/chart(\d+)\.xml$/.exec(entry.entryName);
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return max + 1;
+}
+
+/**
+ * Complete the native-chart wiring for every placeholder in `docxPath`'s `word/document.xml`.
+ * Must run after `postProcessDocx` (it reads the namespace-fixed, id-renumbered document).
+ *
+ * @param {string} docxPath
+ * @param {string} chartDir directory the core bridge wrote `<id>/chart.xml`, `data.json`, `meta.json` into
+ */
+export function injectChartParts(docxPath, chartDir) {
+  const archive = resolve(docxPath);
+  const zip = new AdmZip(archive);
+  let documentXml = readZipEntry(zip, 'word/document.xml');
+  const ids = [...new Set([...documentXml.matchAll(PLACEHOLDER_RE)].map((m) => m[1]))];
+  if (ids.length === 0) return;
+  if (!chartDir) throw new Error('md2nativedocx: document.xml references native charts but no chartDir was given');
+
+  let contentTypes = readZipEntry(zip, '[Content_Types].xml');
+  let relsXml = readZipEntry(zip, 'word/_rels/document.xml.rels');
+  let n = nextChartNumber(zip);
+  const newParts = [];
+
+  for (const id of ids) {
+    const dir = join(chartDir, id);
+    if (!existsSync(dir)) throw new Error(`md2nativedocx: no chart parts found for "${id}" in ${chartDir}`);
+    const chartXml = readFileSync(join(dir, 'chart.xml'), 'utf8');
+    const meta = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf8'));
+    const chartPath = `word/charts/chart${n}.xml`;
+    const relId = `rIdChart${n}`;
+    relsXml = relsXml.replace(
+      '</Relationships>',
+      `<Relationship Id="${relId}" Type="${REL_BASE}/chart" Target="charts/chart${n}.xml"/></Relationships>`,
+    );
+    contentTypes = contentTypes.replace('</Types>', `<Override PartName="/${chartPath}" ContentType="${CHART_CONTENT_TYPE}"/></Types>`);
+    newParts.push([chartPath, chartXml]);
+
+    if (meta.hasWorkbook) {
+      const data = JSON.parse(readFileSync(join(dir, 'data.json'), 'utf8'));
+      const workbookPath = `word/embeddings/Microsoft_Excel_Sheet${n}.xlsx`;
+      newParts.push([workbookPath, buildWorkbookXlsx(data)]);
+      newParts.push([
+        `word/charts/_rels/chart${n}.xml.rels`,
+        XML_DECL +
+          '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+          `<Relationship Id="rId1" Type="${REL_BASE}/package" Target="../embeddings/Microsoft_Excel_Sheet${n}.xlsx"/>` +
+          '</Relationships>',
+      ]);
+      if (!/Extension="xlsx"/i.test(contentTypes)) {
+        contentTypes = contentTypes.replace('</Types>', `<Default Extension="xlsx" ContentType="${XLSX_CONTENT_TYPE}"/></Types>`);
+      }
+    }
+    documentXml = documentXml.split(`CHART_PLACEHOLDER:${id}`).join(relId);
+    n += 1;
+  }
+
+  setZipEntry(zip, 'word/document.xml', documentXml);
+  setZipEntry(zip, '[Content_Types].xml', contentTypes);
+  setZipEntry(zip, 'word/_rels/document.xml.rels', relsXml);
+  for (const [path, content] of newParts) setZipEntry(zip, path, content);
+  zip.writeZip(archive);
+}

package/src/cliSupport.mjs

@@ -0,0 +1,30 @@
+/**
+ * Small helpers shared by every CLI entry path (the Pandoc/.docx path in `bin/md2nativedocx.mjs` and
+ * the .pptx path in `pptxExport.mjs`).
+ */
+
+import { resolve, isAbsolute, relative, sep } from 'node:path';
+
+/** Typed error for CLI-level failures. */
+export class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = 'CliError';
+    this.exitCode = exitCode;
+  }
+}
+
+/** 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 `..`. 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 rel = relative(resolve(cwd), abs);
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+      throw new CliError(`Path escapes the working directory: ${rawPath}`, 2);
+    }
+  }
+  return abs;
+}

package/src/convert.d.mts

@@ -0,0 +1,97 @@
+/**
+ * Types of `@md2nativedocx/cli`'s library entry point (`convert.mjs`). Hand-written: the package is plain
+ * JavaScript with no build step. Keep in step with `convert.mjs` and `envOptions.mjs`.
+ */
+
+/** Page and typography of the bundled reference document. Ignored under {@link ConvertOptions.referenceDoc}. */
+export interface LayoutOptions {
+  /** `A3`, `A4` (default), `Letter`, `Legal`… An unknown value falls back to A4. */
+  pageSize?: string;
+  /** `portrait` (default) or `landscape`. */
+  orientation?: string;
+  /** Word's presets: `normal` (default), `narrow`, `moderate`, `wide`. */
+  margins?: string;
+  /** Custom margins in centimetres; each side overrides the preset. */
+  marginsCustomCm?: { top?: number; right?: number; bottom?: number; left?: number };
+  headingFont?: string;
+  bodyFont?: string;
+  /** Body text size in points. */
+  fontSizePt?: number;
+  /** `single`, `1.15`, `1.5`, `double`; anything else keeps the template's spacing. */
+  lineSpacing?: string;
+  /** `both`, `right` or `center`; anything else leaves body text left-aligned. */
+  justify?: string;
+  /** Theme accent colour, `RRGGBB`. */
+  accentColor?: string;
+  /** Table header fill, `RRGGBB`. */
+  tableHeaderColor?: string;
+  /** A centred page number in the footer. */
+  footerPageNumber?: boolean;
+  /** Put each heading immediately followed by a table in its own landscape section. */
+  landscapeTables?: boolean;
+}
+
+/** 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. */
+  referenceDoc?: string;
+  layout?: LayoutOptions;
+  /** A table of contents after the title, refreshed when Word opens the file. Default `false`. */
+  toc?: boolean;
+  /** Heading levels in the table of contents, 2 to 4. Default 3. */
+  tocDepth?: number;
+  /** Force a colour emoji font on emoji runs. Default `true`. */
+  emojiFont?: boolean;
+  /** SmartArt for the diagrams that can be one. Default `true`. */
+  smartArt?: boolean;
+  /** SmartArt look; unknown values fall back to `colorful`. */
+  smartArtStyle?: string;
+  /** Ship the pre-rendered SmartArt drawing, so Word and LibreOffice show the same geometry. Default `true`. */
+  smartArtDrawing?: boolean;
+  /** Native Word charts for `pie` / `xychart` / `radar`: `true` (default), `false`, or the types to chart. */
+  nativeCharts?: boolean | readonly string[];
+  /** Largest diagram width in EMU. Default: the page's usable width. */
+  maxDrawingCx?: number;
+  /** Largest diagram height in EMU. Default: the page's usable height. */
+  maxDrawingCy?: number;
+  /** Pandoc executable. Default `pandoc`, looked up on `PATH`. */
+  pandocBin?: string;
+  /** Node executable the Lua filter runs the diagram bridge with. Default: `process.execPath`. */
+  nodeBin?: string;
+}
+
+/** A finished document. */
+export interface ConvertResult {
+  /** 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[];
+  /** Everything Pandoc and the filter wrote to stderr, for a log. */
+  pandocStderr: string;
+}
+
+/** A conversion that produced no document. */
+export declare class ConversionError extends Error {
+  /** `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;
+}
+
+/**
+ * Convert a Markdown document to `.docx`: Pandoc with the md2nativedocx filter, every ```mermaid block as
+ * editable Word shapes, SmartArt or a native chart. Needs Pandoc installed. Never reads `MD2NATIVEDOCX_*`
+ * environment variables: behavior comes from `options` only.
+ *
+ * @param source Markdown text, or `{ path }` of a file for Pandoc to read (`.qmd` is read as Markdown).
+ * @throws {ConversionError} when no document could be produced.
+ */
+export declare function convert(source: string | { path: string }, options?: ConvertOptions): Promise<ConvertResult>;

package/src/convert.mjs

@@ -0,0 +1,274 @@
+/**
+ * `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
+ * ```mermaid block through `renderDiagram()`), post-processing, SmartArt and chart part injection. It
+ * lives here and not in `core` because it runs Pandoc (AGENTS.md: core knows nothing about Pandoc).
+ *
+ * Behavior comes from {@link ConvertOptions} only. Every inherited `MD2NATIVEDOCX_*` variable is removed
+ * from the environment Pandoc and the filter see, then the ones the filter and the bridge read are set from
+ * 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.
+ */
+
+import { execFile } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+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';
+
+/** A conversion that produced no document. `stage` says where it stopped. */
+export class ConversionError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ stage: 'setup' | 'pandoc' | 'postprocess' | 'write', pandocStderr?: string, cause?: unknown }} details
+   */
+  constructor(message, { stage, pandocStderr = '', cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'ConversionError';
+    this.stage = stage;
+    this.pandocStderr = pandocStderr;
+  }
+}
+
+// Custom reference.docx (Word's current default look: Aptos font scheme, modern "Office" theme colors,
+// non-bold flat heading hierarchy) instead of Pandoc's own bundled default, which is still the original
+// 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
+ * flat install, the VS Code extension's vendored copy). import.meta.resolve() is Node's own resolution
+ * algorithm, so it finds it in every case without guessing directory depths.
+ */
+function resolveFilterPath() {
+  try {
+    return fileURLToPath(import.meta.resolve('@md2nativedocx/pandoc-filter/md2nativedocx.lua'));
+  } catch (err) {
+    throw new ConversionError(`could not locate @md2nativedocx/pandoc-filter: ${errorMessage(err)}`, { stage: 'setup', cause: err });
+  }
+}
+
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** `MD2NATIVEDOCX_NATIVE_CHARTS` as the bridge reads it, or `null` for charts off. */
+function nativeChartsEnv(setting) {
+  if (setting === undefined || setting === true) return '1';
+  if (setting === false || (Array.isArray(setting) && setting.length === 0)) return null;
+  return setting.join(',');
+}
+
+/** The environment Pandoc runs with: the caller's, minus `MD2NATIVEDOCX_*`, plus what `options` says. */
+function pandocEnvironment(options, { smartArtDir, chartDir, maxDrawingExtentEmu, landscapeGeometry }) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith('MD2NATIVEDOCX_')));
+  if (smartArtDir) env.MD2NATIVEDOCX_SMARTART_DIR = smartArtDir;
+  if (options.smartArtStyle !== undefined) env.MD2NATIVEDOCX_SMARTART_STYLE = options.smartArtStyle;
+  if (options.smartArtDrawing === false) env.MD2NATIVEDOCX_SMARTART_DRAWING = '0';
+  if (chartDir) {
+    env.MD2NATIVEDOCX_CHART_DIR = chartDir;
+    env.MD2NATIVEDOCX_NATIVE_CHARTS = nativeChartsEnv(options.nativeCharts);
+  }
+  // md2nativedocx.lua needs it on Windows (no shebang handling there, so it cannot run a bare .mjs). Our
+  // own interpreter is always Node: a system Node, or the VS Code extension's Electron run as Node.
+  env.MD2NATIVEDOCX_NODE_BIN = options.nodeBin ?? process.execPath;
+  // An explicit drawing cap wins over the page-derived one (e.g. a diagram meant for a half-width cell).
+  const cx = options.maxDrawingCx ?? (maxDrawingExtentEmu ? Math.round(maxDrawingExtentEmu.cx) : undefined);
+  const cy = options.maxDrawingCy ?? (maxDrawingExtentEmu ? Math.round(maxDrawingExtentEmu.cy) : undefined);
+  if (cx !== undefined) env.MD2NATIVEDOCX_MAX_DRAWING_CX = String(cx);
+  if (cy !== undefined) env.MD2NATIVEDOCX_MAX_DRAWING_CY = String(cy);
+  if (landscapeGeometry) {
+    env.MD2NATIVEDOCX_LANDSCAPE_TABLES = '1';
+    env.MD2NATIVEDOCX_PAGE_W_TWIPS = String(landscapeGeometry.pgSize.w);
+    env.MD2NATIVEDOCX_PAGE_H_TWIPS = String(landscapeGeometry.pgSize.h);
+    env.MD2NATIVEDOCX_MARGIN_TOP_TWIPS = String(landscapeGeometry.margins.top);
+    env.MD2NATIVEDOCX_MARGIN_RIGHT_TWIPS = String(landscapeGeometry.margins.right);
+    env.MD2NATIVEDOCX_MARGIN_BOTTOM_TWIPS = String(landscapeGeometry.margins.bottom);
+    env.MD2NATIVEDOCX_MARGIN_LEFT_TWIPS = String(landscapeGeometry.margins.left);
+  }
+  return env;
+}
+
+function runPandoc(bin, args, { cwd, env }) {
+  return new Promise((resolvePromise, reject) => {
+    execFile(bin, args, { cwd, env, maxBuffer: 64 * 1024 * 1024 }, (err, _stdout, stderr) => {
+      if (err) {
+        reject(new ConversionError(`Pandoc failed (exit ${err.code ?? '?'})`, { stage: 'pandoc', pandocStderr: stderr ?? '', cause: err }));
+      } else {
+        resolvePromise(stderr ?? '');
+      }
+    });
+  });
+}
+
+/**
+ * Lines this project wrote to stderr (`md2nativedocx: ...`: parser warnings, SmartArt or chart fallbacks,
+ * from each bridge run the Lua filter spawned), without that prefix. Pandoc's own diagnostics share the
+ * stream but are not ours to count.
+ */
+function extractWarnings(stderrText) {
+  return stderrText
+    .split('\n')
+    .filter((line) => line.startsWith('md2nativedocx: ') && line.trim().length > 0)
+    .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`, 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).
+ * @param {import('./convert.d.mts').ConvertOptions} [options]
+ * @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;
+  if (customReferenceDoc !== undefined && !existsSync(customReferenceDoc)) {
+    throw new ConversionError(`reference document not found: ${customReferenceDoc}`, { stage: 'setup' });
+  }
+  // A custom reference document wins outright: its page setup is unknown, so page/typography options are
+  // not patched into it (spec §2.1, option (a)).
+  const layout = customReferenceDoc ? {} : (options.layout ?? {});
+
+  const work = mkdtempSync(join(tmpdir(), 'md2nativedocx-convert-'));
+  let generatedReferenceDoc = null;
+  try {
+    try {
+      generatedReferenceDoc = customReferenceDoc ? null : buildReferenceDoc(DEFAULT_REFERENCE_DOC, layout);
+    } catch (err) {
+      throw new ConversionError(`reference document setup failed: ${errorMessage(err)}`, { stage: 'setup', cause: err });
+    }
+    const referenceDoc = customReferenceDoc ?? generatedReferenceDoc?.path ?? DEFAULT_REFERENCE_DOC;
+
+    const inputPath = inputFile(source, work);
+    const outputPath = join(work, 'output.docx');
+
+    const pandocArgs = [inputPath, '-o', outputPath, '--lua-filter', filterPath];
+    if (existsSync(referenceDoc)) pandocArgs.push('--reference-doc', referenceDoc);
+    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.
+    const smartArtDir = options.smartArt !== false ? mkdtempSync(join(work, 'smartart-')) : null;
+    const chartDir = nativeChartsEnv(options.nativeCharts) !== null ? mkdtempSync(join(work, 'chart-')) : null;
+    const env = pandocEnvironment(options, {
+      smartArtDir,
+      chartDir,
+      // Usable page area for the translator, whether or not the reference document needed a patch.
+      maxDrawingExtentEmu: customReferenceDoc ? null : resolveMaxDrawingExtentEmu(layout),
+      // The filter's "back to portrait" section needs the document's actual page geometry.
+      landscapeGeometry: layout.landscapeTables
+        ? { pgSize: resolvePageSize(layout.pageSize, layout.orientation), margins: resolveMargins(layout.margins, layout.marginsCustomCm) }
+        : null,
+    });
+
+    const pandocStderr = await runPandoc(options.pandocBin ?? 'pandoc', pandocArgs, { cwd, env });
+
+    try {
+      // Namespaces and drawing ids first: the SmartArt and chart injection read the fixed document.xml.
+      postProcessDocx(outputPath, { toc: Boolean(options.toc), emojiFont: options.emojiFont !== false });
+      if (smartArtDir) injectSmartArtParts(outputPath, smartArtDir);
+      if (chartDir) injectChartParts(outputPath, chartDir);
+    } catch (err) {
+      throw new ConversionError(`post-processing failed: ${errorMessage(err)}`, { stage: 'postprocess', pandocStderr, cause: err });
+    }
+
+    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 });
+  }
+}