@md2nativedocx/cli 0.0.0-stage → 0.2.1

package/src/pptxExport.mjs

@@ -0,0 +1,102 @@
+/**
+ * `.pptx` branch of the CLI (`md2nativedocx deck.md -o deck.pptx`): one slide per ```mermaid block.
+ *
+ * Pandoc is not involved: `@md2nativedocx/pptx` rewrites the diagram shapes core already produces
+ * (see docs/adr/0010-pptx-production-translator-plan.md). Non-diagram Markdown is ignored.
+ */
+
+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]
+
+  --show-source   Put each diagram's Mermaid source in a panel beside it
+`;
+
+function parsePptxArgs(argv) {
+  const args = { input: null, output: null, showSource: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-o' || a === '--output') {
+      args.output = argv[++i];
+      if (!args.output) throw new CliError('Missing value for --output', 2);
+    } else if (a === '--show-source') {
+      args.showSource = true;
+    } else if (a === '-h' || a === '--help') {
+      args.help = true;
+    } else if (a.startsWith('-')) {
+      throw new CliError(`Unknown option: ${a}`, 2);
+    } else if (args.input === null) {
+      args.input = a;
+    } else {
+      throw new CliError(`Unexpected argument: ${a}`, 2);
+    }
+  }
+  return args;
+}
+
+/** Run the deck export; resolves to the process exit code. */
+export async function runPptxCli(argv, cwd) {
+  try {
+    const args = parsePptxArgs(argv);
+    if (args.help) {
+      process.stdout.write(USAGE);
+      return 0;
+    }
+    if (!args.input) throw new CliError('Missing input file.', 2);
+    const input = resolveSafePath(args.input, cwd);
+    const output = resolveSafePath(args.output, cwd);
+    if (!existsSync(input)) throw new CliError(`Input file not found: ${args.input}`, 1);
+
+    const { exportPptx, PptxConversionError } = await import('@md2nativedocx/pptx');
+    let result;
+    try {
+      result = await exportPptx(readFileSync(input, 'utf8'), { title: basename(input), showSource: args.showSource });
+    } catch (err) {
+      if (err instanceof PptxConversionError) throw new CliError(`md2nativedocx: ${err.message}`, 1);
+      throw err;
+    }
+    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`);
+      for (const w of result.warnings) process.stderr.write(`md2nativedocx: ${w}\n`);
+    }
+    process.stdout.write(`Wrote ${basename(output)} (${result.slideCount} slide${result.slideCount === 1 ? '' : 's'})\n`);
+    return 0;
+  } catch (err) {
+    if (err instanceof CliError) {
+      process.stderr.write(`${err.message}\n`);
+      return err.exitCode;
+    }
+    process.stderr.write(`md2nativedocx: pptx export failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  }
+}
+
+/** Plain-text log next to the deck (`deck.pptx` -> `deck.log`), same header as the .docx export log so
+ * the VS Code extension reads the warning count and opens it the same way. */
+function writePptxLog(input, output, warnings, slideCount) {
+  const logPath = output.slice(0, -extname(output).length) + '.log';
+  const lines = [
+    'md2nativedocx export log',
+    `Date: ${new Date().toISOString()}`,
+    `Input: ${input}`,
+    `Output: ${output}`,
+    `Warnings: ${warnings.length}`,
+    '',
+    ...(warnings.length > 0 ? warnings.map((w) => `- ${w.replace(/^md2nativedocx:\s*(warning:\s*)?/, '')}`) : ['No warnings.']),
+    '',
+    `Slides: ${slideCount}`,
+    '',
+  ];
+  writeOutputSafely(logPath, lines.join('\n'));
+}

package/src/referenceDocBuilder.mjs

@@ -0,0 +1,521 @@
+/**
+ * Build a `reference.docx` patched for the page/typography settings a user
+ * picked (`docs/specs/export_customization_SPEC.md` §1.1-1.8/1.14, §2.1 —
+ * "Lot 1"), starting from the bundled static template
+ * (`packages/cli/assets/reference.docx`) or a custom one the caller already
+ * resolved.
+ *
+ * Same `unzip`/`zip` shell-out pattern `postprocess.mjs` already uses for
+ * the final `.docx` (rule `AGENTS.md` "nouvelle dépendance → escalade" —
+ * this needs none): extract only the entries a given option set actually
+ * touches, patch them with scoped string/regex edits (not a full XML
+ * parser — same rationale as `postprocess.mjs`: the input is a known,
+ * machine-authored template, not arbitrary XML), rezip in place.
+ *
+ * Confirmed empirically (not assumed) that this is worth doing at all:
+ * Pandoc's `--reference-doc` carries the reference document's own
+ * `<w:sectPr>` (page size/margins) into the generated `.docx` verbatim —
+ * tested with a distinctive custom `w:pgSz`/`w:pgMar` round-tripped through
+ * a real `pandoc` invocation. `styles.xml`'s `w:docDefaults` is likewise
+ * confirmed to reach ordinary body paragraphs: Pandoc emits `BodyText`/
+ * `FirstParagraph` for regular paragraphs, and neither style (nor `Normal`
+ * itself, its ultimate base) overrides `w:line`/`w:jc`, so both cascade
+ * down from `w:docDefaults` unless a run/paragraph in the Markdown source
+ * overrides them explicitly.
+ *
+ * Two of the 10 Lot 1 catalog entries are *not* a simple patch here and are
+ * deliberately out of scope for this module (tracked separately in
+ * TODO.md): 1.10 (TOC — a Pandoc flag + `settings.xml` patch) and 1.11
+ * (table style presets — underspecified in the spec, no concrete preset
+ * names to switch between yet). 1.9 (dedicated landscape section for
+ * tables, "Lot 5") is mostly a new Lua filter concern (spec §2.3,
+ * `md2nativedocx.lua`) but this module still has one narrow stake in it:
+ * {@link buildReferenceDoc}'s `landscapeTables` option forces an explicit
+ * `sectPr` even with no other page option set, so the Lua filter's "return
+ * to portrait" paragraphs have a concrete page size/margins to agree with
+ * (see its own doc comment for why). 1.13 (footer page numbers) needed a
+ * brand-new `word/footer*.xml` part + relationship + content-type override,
+ * closer in shape to `postprocess.mjs`'s `injectSmartArtParts` — implemented
+ * here anyway (`patchRelsForFooter`/`patchContentTypesForFooter` below)
+ * since {@link buildReferenceDoc} was already the right place to assemble it.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { AdmZip, readZipEntry, setZipEntry } from './zipUtils.mjs';
+
+/** Page dimensions in twips (1/20 pt), portrait orientation (w < h). Standard
+ * OOXML values used verbatim by Word/LibreOffice — not an assumption, unlike
+ * the margin presets below. */
+export const PAGE_SIZES_TWIPS = {
+  A3: { w: 16838, h: 23811 },
+  A4: { w: 11906, h: 16838 },
+  Letter: { w: 12240, h: 15840 },
+  Legal: { w: 12240, h: 20160 },
+};
+
+/**
+ * Word margin presets in twips — Word's own actual built-in values (1 inch
+ * = 1440 twips exactly), **not** the 2.5cm/1417-twip approximation the spec's
+ * catalog (§1.3) originally stated for a metric locale. That approximation
+ * was flagged from the start as an unverified assumption; **disconfirmed by
+ * a real Word test (2026-09-06)**: with the old 1417/1077 values, Word's own
+ * Page Setup dialog showed the margins as "Personnalisées" (Custom), not
+ * "Modérées" (Moderate) — proof the values didn't match any of Word's named
+ * presets. Twips are locale-independent (Word always stores/recognizes the
+ * same internal values regardless of whether its UI displays cm or inches),
+ * so the fix is the same set of numbers everywhere, not a locale-specific
+ * one: Normal/Wide use whole inches (1"=1440), Moderate's left/right use
+ * 0.75in=1080, matching Word's real built-in "Normal"/"Moderate"/"Wide"
+ * margin presets (verified against Word's own Page Setup dialog). `narrow`
+ * (0.5in=720) already matched and needed no change.
+ */
+export const MARGIN_PRESETS_TWIPS = {
+  normal: { top: 1440, right: 1440, bottom: 1440, left: 1440 },
+  narrow: { top: 720, right: 720, bottom: 720, left: 720 },
+  moderate: { top: 1440, right: 1080, bottom: 1440, left: 1080 },
+  wide: { top: 1440, right: 2880, bottom: 1440, left: 2880 },
+};
+
+/** `w:spacing/@w:line` (in 240ths of a line) for each named preset. `'default'`
+ * (or an absent/unrecognized token) means "leave the template's own 1.08 —
+ * Word's actual current default, not one of these four presets — alone",
+ * handled by {@link resolveLineSpacing} returning `null` rather than an
+ * entry here. */
+export const LINE_SPACING_TOKENS = {
+  single: { line: 240, rule: 'auto' },
+  '1.15': { line: 276, rule: 'auto' },
+  '1.5': { line: 360, rule: 'auto' },
+  double: { line: 480, rule: 'auto' },
+};
+
+const XML_ATTR_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' };
+
+/** Escape a string for use inside an XML attribute value (rule #2,
+ * AGENTS.md) — `headingFont`/`bodyFont` are free-text VS Code settings, not
+ * validated against a fixed list, so they reach `a:latin/@typeface`
+ * user-controlled. */
+function escapeXmlAttr(value) {
+  return String(value).replace(/[&<>"']/g, (ch) => XML_ATTR_ESCAPES[ch]);
+}
+
+/** Validate a color as 6 hex digits, uppercased; `null` if invalid. Mirrors
+ * `ooxml-translator.ts`'s `hexColor` — same reasoning: escaping alone would
+ * still let a non-hex value through into `a:srgbClr/@val`. */
+function validHexColor(value) {
+  return /^[0-9A-Fa-f]{6}$/.test(value) ? value.toUpperCase() : null;
+}
+
+/** Resolve a page size + orientation into portrait/landscape twip
+ * dimensions. Unrecognized `pageSize` falls back to A4 (spec §1.1 default). */
+export function resolvePageSize(pageSize, orientation) {
+  const base = PAGE_SIZES_TWIPS[pageSize] ?? PAGE_SIZES_TWIPS.A4;
+  return orientation === 'landscape'
+    ? { w: base.h, h: base.w, orientation: 'landscape' }
+    : { w: base.w, h: base.h, orientation: 'portrait' };
+}
+
+const DEFAULT_PAGE_SIZE = resolvePageSize('A4', 'portrait');
+
+/** Resolve a margin preset name, or `custom` + `customCm` ({top,right,bottom,left}
+ * in centimeters). An invalid/incomplete custom value falls back to the
+ * `normal` preset rather than writing a malformed or absurd page margin. */
+export function resolveMargins(margins, customCm) {
+  if (margins === 'custom' && customCm) {
+    const toTwip = (cm) => Math.round((Number(cm) * 1440) / 2.54);
+    const resolved = {
+      top: toTwip(customCm.top),
+      right: toTwip(customCm.right),
+      bottom: toTwip(customCm.bottom),
+      left: toTwip(customCm.left),
+    };
+    const sane = Object.values(resolved).every((v) => Number.isFinite(v) && v > 0 && v < 50000);
+    if (sane) return resolved;
+  }
+  return MARGIN_PRESETS_TWIPS[margins] ?? MARGIN_PRESETS_TWIPS.normal;
+}
+
+/** Resolve a line-spacing token to `{line, rule}`, or `null` for `'default'`
+ * (leave the template's current value untouched) or an unrecognized token. */
+export function resolveLineSpacing(token) {
+  if (!token || token === 'default') return null;
+  return LINE_SPACING_TOKENS[token] ?? null;
+}
+
+/** Font size in points -> `w:sz`/`w:szCs` half-points, clamped to a sane
+ * 6-72pt range (spec §1.6 only exposes 9-14, but this is a defensive floor/
+ * ceiling, not the UI-facing limit). `undefined` for a non-finite/non-positive
+ * input. */
+function resolveFontSizeHalfPt(pt) {
+  const n = Number(pt);
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  return Math.min(Math.max(Math.round(n * 2), 12), 144);
+}
+
+/**
+ * Patch `word/theme/theme1.xml`: heading/body font typefaces and the accent1
+ * color. Each field is independently optional — an absent one leaves that
+ * part of the theme untouched.
+ */
+export function patchTheme(themeXml, { headingFont, bodyFont, accentColor } = {}) {
+  let out = themeXml;
+  if (headingFont) {
+    out = out.replace(
+      /(<a:majorFont><a:latin typeface=")[^"]*("\s*\/>)/,
+      `$1${escapeXmlAttr(headingFont)}$2`,
+    );
+  }
+  if (bodyFont) {
+    out = out.replace(
+      /(<a:minorFont><a:latin typeface=")[^"]*("\s*\/>)/,
+      `$1${escapeXmlAttr(bodyFont)}$2`,
+    );
+  }
+  if (accentColor) {
+    const safe = validHexColor(accentColor);
+    if (safe) {
+      out = out.replace(
+        /(<a:accent1><a:srgbClr val=")[0-9A-Fa-f]{6}("\s*\/><\/a:accent1>)/,
+        `$1${safe}$2`,
+      );
+    }
+  }
+  return out;
+}
+
+/** `w:jc`'s (`ST_Jc`) own valid values that this project's `justify` setting
+ * maps onto 1:1 — `'left'` (the setting's default) intentionally has no
+ * entry here since it means "don't write a `w:jc` at all, Word's own
+ * default is already left-aligned", same as before `right`/`center` existed. */
+const JUSTIFY_VALUES = new Set(['both', 'right', 'center']);
+
+/**
+ * Patch `word/styles.xml`'s `<w:docDefaults>` block (base font size, line
+ * spacing, default justification) and, independently, the literal `w:val`
+ * color fallback on every style that references the theme's `accent1`
+ * (`w:themeColor="accent1"`) plus the `Table` style's header-row shading.
+ *
+ * The `docDefaults` part is scoped to that one block (extracted, transformed,
+ * spliced back) so a `w:sz`/`w:spacing` elsewhere in the stylesheet (e.g. a
+ * heading style's own override) is never touched. The accent/table-header
+ * parts operate on the whole document since the styles they touch
+ * (`Heading1`-`Heading9`, `Hyperlink`, `Table`) live outside `docDefaults`.
+ */
+export function patchStyles(stylesXml, { fontSizeHalfPt, lineSpacing, justify, accentColor, tableHeaderColor } = {}) {
+  let out = stylesXml;
+
+  const match = out.match(/<w:docDefaults>[\s\S]*?<\/w:docDefaults>/);
+  if (match) {
+    let block = match[0];
+
+    if (fontSizeHalfPt !== undefined) {
+      block = block
+        .replace(/<w:sz w:val="\d+"\s*\/>/, `<w:sz w:val="${fontSizeHalfPt}" />`)
+        .replace(/<w:szCs w:val="\d+"\s*\/>/, `<w:szCs w:val="${fontSizeHalfPt}" />`);
+    }
+
+    if (lineSpacing) {
+      block = block.replace(
+        /<w:spacing w:after="(\d+)" w:line="\d+" w:lineRule="auto"\s*\/>/,
+        `<w:spacing w:after="$1" w:line="${lineSpacing.line}" w:lineRule="${lineSpacing.rule}" />`,
+      );
+    }
+
+    if (JUSTIFY_VALUES.has(justify)) {
+      block = block.replace(/(<w:pPrDefault>\s*<w:pPr>)/, `$1<w:jc w:val="${justify}" />`);
+    }
+
+    out = out.replace(match[0], block);
+  }
+
+  if (accentColor) {
+    out = patchAccentColorFallbacks(out, accentColor);
+  }
+  if (tableHeaderColor) {
+    out = patchTableHeaderColor(out, tableHeaderColor);
+  }
+
+  return out;
+}
+
+/**
+ * `Heading1`-`Heading9`/`Hyperlink`/`Title`/`TOCHeading` each carry a
+ * `<w:color w:themeColor="accent1" w:val="4472C4" .../>` — `w:val` is a
+ * cached literal fallback for a renderer that doesn't resolve theme colors
+ * live. Real Word resolves `w:themeColor` dynamically (so patching just
+ * `theme1.xml`'s `a:accent1`, which {@link patchTheme} already does, is in
+ * principle enough there), but **LibreOffice does not**: rendering a
+ * document with a patched theme but an unpatched literal fallback, the
+ * heading/hyperlink color visibly stayed the old default blue — confirmed by
+ * sampling actual rendered pixel colors, not just reading the XML. Patching
+ * every such literal `w:val` here (regardless of renderer) makes the
+ * accent color correct everywhere, not just in implementations that bother
+ * with live theme resolution.
+ *
+ * `Title`/`TOCHeading` use a *shaded* variant (`w:themeShade`, a darker tint
+ * of accent1) — recomputing Word's exact shade algorithm isn't attempted
+ * here; those two also just get the flat custom color instead of a computed
+ * darker tint, a deliberate, documented simplification (consistent color,
+ * slightly less tonal variety, rather than risking a wrong-guessed formula).
+ */
+function patchAccentColorFallbacks(stylesXml, accentColor) {
+  const safe = validHexColor(accentColor);
+  if (!safe) return stylesXml;
+  return stylesXml.replace(
+    /<w:color\s+[^>]*\bw:themeColor="accent1"[^>]*\/>/g,
+    (tag) => tag.replace(/w:val="[0-9A-Fa-f]{6}"/, `w:val="${safe}"`),
+  );
+}
+
+/**
+ * Shades the header row of every table (the `Table` style's
+ * `<w:tblStylePr w:type="firstRow">` conditional formatting — the same block
+ * Pandoc's default template already ships with just a bottom border, no
+ * fill) with a user-chosen background color. Adds a `<w:shd>` if none is
+ * present yet, or replaces an existing one — idempotent either way.
+ */
+function patchTableHeaderColor(stylesXml, tableHeaderColor) {
+  const safe = validHexColor(tableHeaderColor);
+  if (!safe) return stylesXml;
+  return stylesXml.replace(
+    /(<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}"/>`;
+      // 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}`;
+    },
+  );
+}
+
+/**
+ * Patch `word/document.xml`'s final (only) `<w:sectPr />` into a full
+ * section with explicit page size/orientation/margins, and optionally a
+ * `<w:footerReference>` (spec §1.13, "Lot 1" fast-follow — `footerRId` is the
+ * relationship id {@link patchRelsForFooter} minted for `word/footer1.xml`).
+ * `pgSize`/`margins` are each `null` when not requested — falls back to A4
+ * portrait / the `normal` preset respectively for whichever one the caller
+ * didn't ask to change, since a `<w:sectPr>` needs both to be well-formed
+ * regardless of which specific option triggered building one at all.
+ * `footerReference` must be the first child when present — confirmed
+ * against a real Pandoc-processed `sectPr` (`TODO.md`), not assumed.
+ */
+export function patchSectPr(documentXml, { pgSize, margins, footerRId } = {}) {
+  if (!pgSize && !margins && !footerRId) return documentXml;
+  const size = pgSize ?? DEFAULT_PAGE_SIZE;
+  const mar = margins ?? MARGIN_PRESETS_TWIPS.normal;
+  const orientAttr = size.orientation === 'landscape' ? ' w:orient="landscape"' : '';
+  const footerRef = footerRId ? `<w:footerReference w:type="default" r:id="${footerRId}"/>` : '';
+  const sectPr =
+    `<w:sectPr>${footerRef}<w:pgSz w:w="${size.w}" w:h="${size.h}"${orientAttr}/>` +
+    `<w:pgMar w:top="${mar.top}" w:right="${mar.right}" w:bottom="${mar.bottom}" w:left="${mar.left}" w:header="708" w:footer="708" w:gutter="0"/></w:sectPr>`;
+  return documentXml.replace(/<w:sectPr\s*\/>/, sectPr);
+}
+
+/**
+ * Minimal footer part (spec §1.13): a single centered `PAGE` field. Written
+ * as a brand-new `word/footer1.xml` package part — confirmed empirically
+ * that, unlike `settings.xml` (see `patchSettings`'s doc comment), Pandoc
+ * *does* carry over a reference document's footer part/relationship/
+ * `footerReference` verbatim: a canary footer with a `PAGE` field, added to
+ * a copy of `reference.docx` and round-tripped through a real `pandoc`
+ * invocation, survived into the generated `.docx` and rendered a page
+ * number when opened in LibreOffice.
+ */
+export const FOOTER_PAGE_NUMBER_XML =
+  '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+  '<w:ftr xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">' +
+  '<w:p><w:pPr><w:jc w:val="center"/></w:pPr>' +
+  '<w:r><w:fldChar w:fldCharType="begin"/></w:r>' +
+  '<w:r><w:instrText xml:space="preserve"> PAGE </w:instrText></w:r>' +
+  '<w:r><w:fldChar w:fldCharType="separate"/></w:r>' +
+  '<w:r><w:t>1</w:t></w:r>' +
+  '<w:r><w:fldChar w:fldCharType="end"/></w:r>' +
+  '</w:p></w:ftr>';
+
+/** Smallest unused `rId` in a `.rels` file's `Id="rIdN"` attributes (`rId1`
+ * if there are none) — `reference.docx`'s own relationships already go up
+ * to `rId8` plus a decorative `rId30` (an external hyperlink in its
+ * placeholder body content, never reaching real output), so a fixed id
+ * would risk colliding. */
+function nextRelationshipId(relsXml) {
+  const ids = [...relsXml.matchAll(/Id="rId(\d+)"/g)].map((m) => Number(m[1]));
+  const max = ids.length ? Math.max(...ids) : 0;
+  return `rId${max + 1}`;
+}
+
+/** Add the footer relationship to `word/_rels/document.xml.rels`. Returns
+ * `{ xml, rId }` — `rId` is what {@link patchSectPr}'s `footerRId` and
+ * `patchContentTypesForFooter` need to stay consistent. */
+export function patchRelsForFooter(relsXml) {
+  const rId = nextRelationshipId(relsXml);
+  const rel =
+    '<Relationship Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer" ' +
+    `Id="${rId}" Target="footer1.xml" />`;
+  return { xml: relsXml.replace('</Relationships>', `${rel}</Relationships>`), rId };
+}
+
+/** Declare `word/footer1.xml`'s content type in `[Content_Types].xml`.
+ * Idempotent (checked by path, not just presence of the word "footer") in
+ * case a future base template already ships a footer of its own. */
+export function patchContentTypesForFooter(contentTypesXml) {
+  if (contentTypesXml.includes('/word/footer1.xml')) return contentTypesXml;
+  const override =
+    '<Override PartName="/word/footer1.xml" ' +
+    'ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml" />';
+  return contentTypesXml.replace('</Types>', `${override}</Types>`);
+}
+
+/**
+ * Patch `word/settings.xml` to add `<w:updateFields w:val="true" />` when a
+ * TOC is requested (spec §1.10/§2.2) — without it, a Pandoc-generated TOC
+ * field shows stale/empty content until the user manually refreshes it
+ * (F9); with it, Word itself offers to update fields on open. No-op (and
+ * idempotent) when `toc` is falsy or the flag is already present.
+ *
+ * Applied by `postprocess.mjs` to the **final generated `.docx`**'s own
+ * `settings.xml`, not to the reference doc here — confirmed empirically
+ * that Pandoc synthesizes its own `word/settings.xml` from scratch and does
+ * NOT carry over the reference document's (unlike `theme1.xml`/
+ * `styles.xml`/`document.xml`'s `sectPr`, all confirmed carried over).
+ * Exported from this module anyway since it's the same kind of pure,
+ * independently-testable XML patch as the others here — just consumed by a
+ * different caller.
+ */
+export function patchSettings(settingsXml, { toc } = {}) {
+  if (!toc || /<w:updateFields\b/.test(settingsXml)) return settingsXml;
+  return settingsXml.replace(/(<w:settings\b[^>]*>)/, `$1\n  <w:updateFields w:val="true" />`);
+}
+
+/**
+ * Build a patched `reference.docx` from `basePath` for the given raw option
+ * values (as they arrive from CLI env vars / VS Code settings — every field
+ * optional, `undefined` meaning "user didn't touch this one").
+ *
+ * Returns `null` when every option is unset (the common case — no export
+ * customization active): callers should keep using `basePath` unchanged,
+ * unzip/zip is skipped entirely. Otherwise returns `{ path, dir }`: `path` is
+ * the patched `.docx` (pass it to Pandoc's `--reference-doc`), `dir` is the
+ * scratch directory the caller must `rmSync(dir, { recursive: true, force:
+ * true })` once Pandoc has run (mirrors how `md2nativedocx.mjs` already
+ * cleans up its `smartArtDir` scratch directory).
+ */
+export function buildReferenceDoc(basePath, rawOptions = {}) {
+  const {
+    pageSize, orientation, margins, marginsCustomCm,
+    headingFont, bodyFont, fontSizePt, lineSpacing, justify, accentColor, tableHeaderColor,
+    footerPageNumber, landscapeTables,
+  } = rawOptions;
+
+  const needsFooter = footerPageNumber === true;
+  // Lot 5 (spec §1.9/§2.3) also forces an explicit sectPr, even with no
+  // pageSize/orientation/margins of its own: the Lua filter's "return to
+  // portrait" paragraphs need a concrete, known page size/margins to write
+  // — Pandoc's own unpatched default (an empty `<w:sectPr/>`, which resolves
+  // to whatever Letter/A4 default the local Pandoc/LibreOffice install
+  // falls back to) is not something this process can introspect, and a
+  // mismatch between that and this module's own A4/normal fallback would
+  // make the non-table sections of the document silently switch page size
+  // the moment landscape tables are turned on (found manually testing this
+  // lot end to end). So enabling landscapeTables alone pins the whole
+  // document to the same A4/normal-margins default `resolvePageSize`/
+  // `resolveMargins` already use elsewhere — a real, deliberate behavior
+  // change flagged in TODO.md, not a silent one: a user who wants a
+  // different page size must combine this toggle with the Lot 1 page size
+  // setting, same as any other Lot 1 option already requires today.
+  const needsSectPr =
+    pageSize !== undefined || orientation !== undefined || margins !== undefined || needsFooter || landscapeTables === true;
+  const needsTheme = headingFont !== undefined || bodyFont !== undefined || accentColor !== undefined;
+  const resolvedLineSpacing = resolveLineSpacing(lineSpacing);
+  const needsStyles =
+    fontSizePt !== undefined ||
+    resolvedLineSpacing !== null ||
+    JUSTIFY_VALUES.has(justify) ||
+    accentColor !== undefined ||
+    tableHeaderColor !== undefined;
+
+  if (!needsSectPr && !needsTheme && !needsStyles) return null;
+
+  const dir = mkdtempSync(join(tmpdir(), 'md2nativedocx-refdoc-'));
+  const workDocx = join(dir, 'reference.docx');
+
+  try {
+    const zip = new AdmZip(basePath);
+
+    if (needsTheme) {
+      const theme = readZipEntry(zip, 'word/theme/theme1.xml');
+      setZipEntry(zip, 'word/theme/theme1.xml', patchTheme(theme, { headingFont, bodyFont, accentColor }));
+    }
+    if (needsStyles) {
+      const styles = readZipEntry(zip, 'word/styles.xml');
+      const fontSizeHalfPt = fontSizePt !== undefined ? resolveFontSizeHalfPt(fontSizePt) : undefined;
+      setZipEntry(
+        zip,
+        'word/styles.xml',
+        patchStyles(styles, {
+          fontSizeHalfPt,
+          lineSpacing: resolvedLineSpacing,
+          justify,
+          accentColor,
+          tableHeaderColor,
+        }),
+      );
+    }
+
+    let footerRId;
+    if (needsFooter) {
+      const rels = readZipEntry(zip, 'word/_rels/document.xml.rels');
+      const patched = patchRelsForFooter(rels);
+      footerRId = patched.rId;
+      setZipEntry(zip, 'word/_rels/document.xml.rels', patched.xml);
+
+      const contentTypes = readZipEntry(zip, '[Content_Types].xml');
+      setZipEntry(zip, '[Content_Types].xml', patchContentTypesForFooter(contentTypes));
+
+      setZipEntry(zip, 'word/footer1.xml', FOOTER_PAGE_NUMBER_XML);
+    }
+
+    if (needsSectPr) {
+      const documentXml = readZipEntry(zip, 'word/document.xml');
+      const pgSize =
+        pageSize !== undefined || orientation !== undefined || landscapeTables === true
+          ? resolvePageSize(pageSize, orientation)
+          : null;
+      const mar = margins !== undefined || landscapeTables === true ? resolveMargins(margins, marginsCustomCm) : null;
+      setZipEntry(zip, 'word/document.xml', patchSectPr(documentXml, { pgSize, margins: mar, footerRId }));
+    }
+
+    zip.writeZip(workDocx);
+    return { path: workDocx, dir };
+  } catch (err) {
+    rmSync(dir, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+/**
+ * Usable page area in EMU for `TranslateOptions.maxDrawingCx`/`maxDrawingCy`
+ * (`export_customization_SPEC.md` §2.4) — the same page size/orientation/
+ * margins resolution as {@link buildReferenceDoc}, but expressed as the
+ * drawable area a diagram must fit, in EMU (1 twip = 635 EMU) rather than as
+ * XML to patch. Independent of whether a reference doc was actually built:
+ * even a `md2nativedocx.referenceDocument` custom-template user still gets a
+ * diagram sized for *some* explicit page area rather than silently keeping
+ * the Letter-portrait default when they never touched Lot 1's settings at
+ * all — so this only returns `null` (meaning "keep the translator's own
+ * built-in default") when literally none of pageSize/orientation/margins
+ * were set, same condition as `needsSectPr` above.
+ */
+export function resolveMaxDrawingExtentEmu({ pageSize, orientation, margins, marginsCustomCm } = {}) {
+  if (pageSize === undefined && orientation === undefined && margins === undefined) return null;
+  const size = resolvePageSize(pageSize, orientation);
+  const mar = margins !== undefined ? resolveMargins(margins, marginsCustomCm) : MARGIN_PRESETS_TWIPS.normal;
+  const TWIP_TO_EMU = 635;
+  const cx = (size.w - mar.left - mar.right) * TWIP_TO_EMU;
+  const cy = (size.h - mar.top - mar.bottom) * TWIP_TO_EMU;
+  return { cx: Math.max(1, cx), cy: Math.max(1, cy) };
+}

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.`,
+  );
+}