@md2nativedocx/cli 0.0.0-stage → 0.1.0

package/src/postprocess.mjs

@@ -0,0 +1,628 @@
+/**
+ * Post-process the .docx produced by Pandoc so Word accepts our drawings.
+ *
+ * Two corrections are applied to `word/document.xml`:
+ *
+ *  1. **Extended namespace declarations on the root.** Pandoc does not declare
+ *     `wpc`/`wpg`/`wps` on `w:document`. Our translator declares them inline on
+ *     the elements that use them, which is valid XML but is not what Word
+ *     emits, and Word resolves the markup-compatibility (`mc`) processing model
+ *     against the *root* declarations. Word itself always declares them on the
+ *     root, so we match that.
+ *
+ *  2. **Document-wide unique drawing ids.** Word treats `wp:docPr/@id` and every
+ *     `cNvPr/@id` as one id space per document and reports the file as corrupt
+ *     when two collide. The translator is a pure function that numbers each
+ *     fragment from 1 independently, so a document with two diagrams (or one
+ *     diagram plus a Pandoc-inserted image) always collides until they are
+ *     renumbered here — the one place that sees the whole document.
+ *
+ * Security (AGENTS.md):
+ *   * Rule #7 (Pandoc authors the package; post-processing limited to an
+ *     allowlist): this replaces exactly one entry (`word/document.xml`) in the
+ *     archive Pandoc produced — it is not a reimplementation of ZIP/docx
+ *     packaging. It is required for the output to be Word-conformant.
+ *   * No external relationship is added (rule #3) and no user-controlled text is
+ *     interpolated: the edits are namespace declarations on the root tag and
+ *     rewrites of numeric `id` attributes.
+ *   * The rewrites are regex-scoped to `id="<digits>"` on a fixed list of
+ *     element names. A full XML parser would be sturdier but would mean a new
+ *     dependency (rule #6); the input here is machine-generated by Pandoc and by
+ *     our own translator, not arbitrary XML.
+ *
+ * A third function, {@link injectSmartArtParts}, goes further than the two
+ * corrections above — it adds brand-new ZIP entries (`word/diagrams/*.xml`),
+ * not just same-path replacements. Signed off separately
+ * (`docs/specs/FUTURE_mmd2smartart_SPEC.md` §8, confirmed with the maintainer
+ * 2026-09-03), and listed in rule #7's allowlist since its 2026-10-07
+ * rewording. See its own doc comment for why it exists and what
+ * it does; it is a no-op whenever a document has no SmartArt diagram in it.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { patchSettings } from './referenceDocBuilder.mjs';
+import { AdmZip, readZipEntry, setZipEntry } from './zipUtils.mjs';
+
+/** Extended namespaces Word declares on the document root, prefix -> URI. */
+const EXTENDED_NS = {
+  'xmlns:wpc': 'http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas',
+  'xmlns:mc': 'http://schemas.openxmlformats.org/markup-compatibility/2006',
+  'xmlns:wp14': 'http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing',
+  'xmlns:wpg': 'http://schemas.microsoft.com/office/word/2010/wordprocessingGroup',
+  'xmlns:wps': 'http://schemas.microsoft.com/office/word/2010/wordprocessingShape',
+};
+
+/**
+ * Prefixes listed in `mc:Ignorable` — the extensions Word may safely skip.
+ * `wpc`/`wpg`/`wps` are deliberately absent: they carry the diagram itself, so
+ * declaring them ignorable would licence Word to drop it.
+ *
+ * Every prefix listed here MUST also be declared via `xmlns:` on the root
+ * (`EXTENDED_NS` above, or Pandoc's own declarations) — the markup-compatibility
+ * spec (ECMA-376 Part 3) requires an `mc:Ignorable` prefix to resolve to an
+ * in-scope namespace. This used to list the full boilerplate a real Word
+ * document advertises (`w14 w15 w16se w16cid w16 w16cex w16sdtdh w16sdtfl
+ * w16du wp14`), copied from a real Word document's root without also copying
+ * the xmlns declarations those extra prefixes need — nine undeclared
+ * prefixes, invalid per spec. Word's parser enforces this strictly and
+ * reports the file as needing repair; LibreOffice does not, which is why this
+ * went unnoticed through every LibreOffice-headless and structural-XML check
+ * (found 2026-09-02, opening a generated .docx in real Word for the first
+ * time). `wp14` is the only one of that list we actually declare.
+ */
+const IGNORABLE = 'wp14';
+
+/** Elements whose `id` attribute *defines* a drawing object id. */
+const ID_DEFINING_ELEMENTS = ['wp:docPr', 'wpg:cNvPr', 'wps:cNvPr', 'pic:cNvPr'];
+
+/** Elements whose `id` attribute *references* a drawing object id. */
+const ID_REFERENCING_ELEMENTS = ['a:stCxn', 'a:endCxn'];
+
+/**
+ * Inject the extended namespace declarations onto the root `w:document`
+ * element. Returns the modified XML.
+ *
+ * The check is scoped to the root's opening tag: the document body legitimately
+ * contains inline `xmlns:wpg=` declarations on the drawing elements, so a
+ * whole-document search would conclude the namespaces are already present and
+ * silently leave the root untouched.
+ */
+export function injectNamespaces(documentXml) {
+  const rootStart = documentXml.indexOf('<w:document');
+  if (rootStart < 0) {
+    throw new Error('md2nativedocx: could not find <w:document> root element');
+  }
+  const tagEnd = documentXml.indexOf('>', rootStart);
+  if (tagEnd < 0) {
+    throw new Error('md2nativedocx: malformed <w:document> root element');
+  }
+  const openTag = documentXml.slice(rootStart, tagEnd + 1);
+
+  const additions = Object.entries(EXTENDED_NS)
+    .filter(([attr]) => !openTag.includes(`${attr}=`))
+    .map(([attr, uri]) => ` ${attr}="${uri}"`)
+    .join('');
+  const ignorable = openTag.includes('mc:Ignorable=') ? '' : ` mc:Ignorable="${IGNORABLE}"`;
+  if (!additions && !ignorable) return documentXml;
+
+  const newOpenTag = `${openTag.slice(0, -1)}${additions}${ignorable}>`;
+  return documentXml.slice(0, rootStart) + newOpenTag + documentXml.slice(tagEnd + 1);
+}
+
+/**
+ * Renumber every drawing object id in the document so no two collide.
+ *
+ * Ids are remapped per `w:drawing` block, because `a:stCxn`/`a:endCxn` reference
+ * shapes within their own drawing: a block-local old -> new map keeps each
+ * connector attached to the same pair of shapes while a counter shared across
+ * blocks guarantees document-wide uniqueness.
+ */
+export function renumberDrawingIds(documentXml) {
+  let nextId = 1;
+  const defPattern = new RegExp(`<(${ID_DEFINING_ELEMENTS.join('|')})\\s+id="(\\d+)"`, 'g');
+  const refPattern = new RegExp(`<(${ID_REFERENCING_ELEMENTS.join('|')})\\s+id="(\\d+)"`, 'g');
+
+  return documentXml.replace(/<w:drawing>[\s\S]*?<\/w:drawing>/g, (block) => {
+    // Pass 1: assign a fresh id to each definition in this drawing.
+    const remap = new Map();
+    for (const match of block.matchAll(defPattern)) {
+      const oldId = match[2];
+      if (!remap.has(oldId)) remap.set(oldId, String(nextId++));
+    }
+    if (remap.size === 0) return block;
+
+    // Pass 2: rewrite definitions and the connector references that point at
+    // them. An unmapped reference is left alone rather than guessed at.
+    return block
+      .replace(defPattern, (whole, tag, oldId) => `<${tag} id="${remap.get(oldId)}"`)
+      .replace(refPattern, (whole, tag, oldId) =>
+        remap.has(oldId) ? `<${tag} id="${remap.get(oldId)}"` : whole,
+      );
+  });
+}
+
+/**
+ * Emoji/badge color rendering (spec §1.15/§2.5, "Lot 2") — Word substitutes a
+ * fallback font for ✅/⚠️/❌ and friends unless a run is explicitly set to an
+ * emoji-capable font ("Segoe UI Emoji"), otherwise flattening them to
+ * indistinguishable grey glyphs.
+ *
+ * Splits at grapheme-cluster boundaries (`Intl.Segmenter`, not naive
+ * per-character scanning) rather than forcing the whole run's font: Pandoc
+ * puts an entire mixed sentence in one `<w:r>` (confirmed empirically — see
+ * `TODO.md`), so forcing "Segoe UI Emoji" on the whole run would also
+ * change the font of the surrounding prose, not just the emoji. Grapheme
+ * clusters matter because an emoji is frequently more than one Unicode code
+ * point (a base character plus a variation selector, skin-tone modifier, or
+ * ZWJ sequence, e.g. "⚠️" = U+26A0 + U+FE0F) — splitting on raw code points
+ * would separate a modifier from its base and could detach it visually.
+ *
+ * `\p{Extended_Pictographic}` (a standard Unicode property, ES2018+, no new
+ * dependency) is the classification the spec itself left as "a precise list
+ * to establish" — this covers essentially every emoji in one regex; the one
+ * confirmed gap is keycap sequences (`1️⃣`, `#️⃣`), whose base characters
+ * (digits, `#`, `*`) aren't pictographic themselves. Regional-indicator
+ * flag pairs (e.g. "🇫🇷") need a second explicit check: `Intl.Segmenter`
+ * correctly groups the pair into one grapheme cluster, but neither half
+ * matches `Extended_Pictographic` on its own.
+ *
+ * Only transforms a run shaped exactly `<w:r>(<w:rPr>...</w:rPr>)?<w:t ...>
+ * text</w:t></w:r>` — the shape Pandoc actually emits for plain and
+ * bold/italic text alike (confirmed empirically, both with and without
+ * emoji). Anything else (a run wrapping a `<w:drawing>`, multiple `<w:t>`
+ * elements, a `<w:br/>`, ...) is left untouched rather than guessed at,
+ * same conservative-regex-scope reasoning as `renumberDrawingIds` above.
+ */
+const EXTENDED_PICTOGRAPHIC_RE = /\p{Extended_Pictographic}/u;
+// A single grapheme cluster made entirely of regional-indicator symbols (a
+// flag, e.g. "🇫🇷") — used to classify one already-segmented cluster.
+const REGIONAL_INDICATOR_CLUSTER_RE = /^[\u{1F1E6}-\u{1F1FF}]+$/u;
+// Existence check (not anchored) — used only to decide whether a whole run's
+// text is worth segmenting at all.
+const REGIONAL_INDICATOR_ANYWHERE_RE = /[\u{1F1E6}-\u{1F1FF}]/u;
+const EMOJI_FONT = 'Segoe UI Emoji';
+const GRAPHEME_SEGMENTER = new Intl.Segmenter('en', { granularity: 'grapheme' });
+
+function isEmojiGrapheme(cluster) {
+  if (REGIONAL_INDICATOR_CLUSTER_RE.test(cluster)) return true;
+  for (const ch of cluster) {
+    if (EXTENDED_PICTOGRAPHIC_RE.test(ch)) return true;
+  }
+  return false;
+}
+
+/**
+ * Force *emoji* presentation (not text/monochrome presentation) on a single
+ * bare pictographic code point by appending VARIATION SELECTOR-16 (U+FE0F).
+ *
+ * **Origin story, corrected 2026-09-06 — read this before trusting the name
+ * of this function.** First real-Word test (✅/⚠️/❌/🚀, one document): ⚠️/🚀
+ * rendered in color, ✅/❌ stayed monochrome despite identical `w:rFonts`
+ * forcing. Hypothesis at the time: ⚠️ already had U+FE0F in its own text and
+ * 🚀 has no monochrome glyph to begin with, so *adding* U+FE0F to bare ✅/❌
+ * should fix them. **A broader 31-symbol real-Word review disproved this**:
+ * ✔️/✖️ (U+2714/U+2716) already carried an explicit U+FE0F in the *original*
+ * source and still rendered monochrome — proof the selector alone does not
+ * reliably force color in this Word/Segoe UI Emoji combination, contrary to
+ * Unicode's own `Default_Emoji_Presentation` model. The actual empirical
+ * split (same review) doesn't line up with Unicode block or any property
+ * this code can query: monochrome = {U+2705 ✅, U+274C ❌, U+2714 ✔,
+ * U+2716 ✖, U+2B50 ⭐, U+2611 ☑} (plus keycap sequences, a separate,
+ * already-known gap below); every other tested symbol — including several
+ * in the *same* Miscellaneous Symbols block as ☑ (U+2600 ☀, U+2601 ☁,
+ * U+26A0 ⚠, U+2699 ⚙, U+2708 ✈, U+260E ☎, U+26A1 ⚡) — rendered in color.
+ * This looks like a fixed, Microsoft-curated list of legacy Wingdings-
+ * heritage "checklist" symbols Word/Segoe UI Emoji keeps monochrome by
+ * design (plausibly for compatibility with documents that use them as
+ * plain checkbox/bullet glyphs, not as colorful emoji) — not a font-
+ * resolution bug this project's OOXML output can fix by itself. **This
+ * function is kept anyway** (harmless, more explicit/correct Unicode text
+ * regardless of whether Word's glyph selection responds to it), but do NOT
+ * assume it "fixes" ✅/❌/✔/✖/⭐/☑ — it doesn't, as far as real-Word testing
+ * has shown. See TODO.md for the full, up-to-date empirical table and
+ * whether anyone has since found an actual workaround.
+ *
+ * Scoped deliberately narrow — only a grapheme cluster that is *exactly one*
+ * Unicode code point and doesn't already end in a variation selector: a
+ * multi-code-point cluster is either already disambiguated (⚠️'s existing
+ * U+FE0F) or a composed sequence (ZWJ combos, regional-indicator flag
+ * pairs) where inserting U+FE0F elsewhere isn't a documented, tested fix
+ * and risks breaking cluster recognition instead.
+ */
+const VARIATION_SELECTOR_16 = '\uFE0F';
+function ensureEmojiPresentation(cluster) {
+  const codePoints = [...cluster];
+  if (codePoints.length !== 1 || !EXTENDED_PICTOGRAPHIC_RE.test(cluster)) return cluster;
+  return cluster + VARIATION_SELECTOR_16;
+}
+
+/** Split `text` into consecutive `{ text, emoji }` segments, merging adjacent
+ * grapheme clusters of the same classification. */
+function segmentEmoji(text) {
+  const segments = [];
+  for (const { segment } of GRAPHEME_SEGMENTER.segment(text)) {
+    const emoji = isEmojiGrapheme(segment);
+    const normalized = emoji ? ensureEmojiPresentation(segment) : segment;
+    const last = segments[segments.length - 1];
+    if (last && last.emoji === emoji) {
+      last.text += normalized;
+    } else {
+      segments.push({ text: normalized, emoji });
+    }
+  }
+  return segments;
+}
+
+/** Force the emoji font into `rPrInner` (a run's `<w:rPr>` inner XML, or `''`
+ * if it had none) — replaces an existing `<w:rFonts/>` in place, or prepends
+ * a new one (CT_RPr's schema requires `rFonts` to be its first child, when
+ * present, so a naive append could produce an invalid element order). */
+function withEmojiFont(rPrInner) {
+  const rFonts = `<w:rFonts w:ascii="${EMOJI_FONT}" w:hAnsi="${EMOJI_FONT}" w:eastAsia="${EMOJI_FONT}" w:cs="${EMOJI_FONT}"/>`;
+  return /<w:rFonts\b[^>]*\/>/.test(rPrInner) ? rPrInner.replace(/<w:rFonts\b[^>]*\/>/, rFonts) : rFonts + rPrInner;
+}
+
+const EMOJI_RUN_RE = /<w:r>(?:<w:rPr>([\s\S]*?)<\/w:rPr>)?<w:t(?:\s[^>]*)?>([\s\S]*?)<\/w:t><\/w:r>/g;
+
+export function forceEmojiColorFont(documentXml) {
+  return documentXml.replace(EMOJI_RUN_RE, (whole, rPrInner, text) => {
+    if (!EXTENDED_PICTOGRAPHIC_RE.test(text) && !REGIONAL_INDICATOR_ANYWHERE_RE.test(text)) return whole;
+    const segments = segmentEmoji(text);
+    if (!segments.some((s) => s.emoji)) return whole;
+    return segments
+      .map(({ text: segText, emoji }) => {
+        const rPr = emoji
+          ? `<w:rPr>${withEmojiFont(rPrInner ?? '')}</w:rPr>`
+          : rPrInner !== undefined
+            ? `<w:rPr>${rPrInner}</w:rPr>`
+            : '';
+        return `<w:r>${rPr}<w:t xml:space="preserve">${segText}</w:t></w:r>`;
+      })
+      .join('');
+  });
+}
+
+/**
+ * Move a Pandoc-generated TOC field (spec §1.10/§2.2, "Lot 3", `--toc`) from
+ * where Pandoc always puts it — the very top of the body, before any
+ * heading — to right after the document's first Heading1 paragraph, per the
+ * spec's own wording ("sommaire automatique sous le H1"). Confirmed
+ * empirically that Pandoc's placement needed this fix at all: a real
+ * `pandoc --toc` run puts the `<w:sdt>` TOC field before the title, not
+ * under it, and Pandoc has no flag to change that.
+ *
+ * A no-op (returns `documentXml` unchanged) when there is no TOC field
+ * (`--toc` wasn't used) or no Heading1 paragraph to anchor after — in the
+ * latter case the TOC is left at Pandoc's own default position rather than
+ * silently dropped. Safe to always run, TOC or not: this is why
+ * `postProcessDocx` composes it unconditionally instead of taking a flag.
+ */
+export function repositionTocAfterTitle(documentXml) {
+  const tocMatch = documentXml.match(/<w:sdt>[\s\S]*?<w:docPartGallery w:val="Table of Contents"[\s\S]*?<\/w:sdt>/);
+  if (!tocMatch) return documentXml;
+  const tocBlock = tocMatch[0];
+  const withoutToc = documentXml.replace(tocBlock, '');
+  const headingMatch = withoutToc.match(/<w:p>[\s\S]*?<w:pStyle w:val="Heading1"[\s\S]*?<\/w:p>/);
+  if (!headingMatch) return documentXml;
+  const insertAt = withoutToc.indexOf(headingMatch[0]) + headingMatch[0].length;
+  return withoutToc.slice(0, insertAt) + tocBlock + withoutToc.slice(insertAt);
+}
+
+/**
+ * Landscape table sections (spec §1.9/§2.3, "Lot 5") — cleanup for a trap
+ * found empirically (ADR 0005), not documented by the spec itself: the Lua
+ * filter (`md2nativedocx.lua`) emits one `<w:sectPr>`-only paragraph before
+ * every matched `Header` and one after its `Table`, independently for each
+ * match. Two situations leave one of those paragraphs closing a section with
+ * literally no other content in it, which Word/LibreOffice both render as an
+ * extra blank page:
+ *
+ *  1. Two matches directly adjacent in the source (no content between one
+ *     Table and the next Header) — the "close" paragraph after the first
+ *     Table ends up immediately next to the "open" paragraph before the
+ *     second Header, with nothing real between them.
+ *  2. A matched Table is the very last content in the document — its
+ *     "close" (landscape) paragraph ends up immediately before the body's
+ *     own final `<w:sectPr>`, with nothing between them either.
+ *
+ * Both are fixed by a single shared building block: a `<w:sectPr>`-only
+ * paragraph (`<w:p><w:pPr><w:sectPr>...</w:sectPr></w:pPr></w:p>`) is a
+ * shape Pandoc itself never emits (confirmed empirically — its own section
+ * marker is always a bare `<w:sectPr>` directly under `<w:body>`, never
+ * wrapped in a paragraph), so matching it structurally is unambiguous: it
+ * can only be one of ours. Both functions tolerate `<w:bookmarkStart/End>`
+ * tags in the gap (Pandoc auto-brackets headers with these; confirmed by the
+ * spike that they can land between two of our synthetic paragraphs) without
+ * treating that gap as real content.
+ */
+
+// The captured group must only ever match `<w:pgSz/>`/`<w:pgMar/>`-shaped
+// self-closing children (what `md2nativedocx.lua` actually emits) — NOT
+// `[\s\S]*?`. A lazy dot-all group has no way to know it should stop at the
+// paragraph's own `</w:sectPr></w:pPr></w:p>` rather than a later one
+// further down the document; found the hard way (a real corrupted .docx)
+// when it silently swallowed an entire Header+Table in between two of our
+// paragraphs, matching this pattern's *later* occurrence instead of the
+// intended one. A self-closing-only child element can never contain a
+// nested `<w:p>`/`<w:tbl>`, which is what keeps the match from crossing into
+// real content.
+const SECTPR_INNER = '(?:<w:[A-Za-z]+(?:\\s[^>]*)?\\/>)*';
+const SECTPR_ONLY_PARA = `<w:p><w:pPr><w:sectPr>(${SECTPR_INNER})<\\/w:sectPr><\\/w:pPr><\\/w:p>`;
+const BOOKMARK_GAP = '((?:\\s*<w:bookmark(?:Start|End)\\b[^>]*\\/>)*\\s*)';
+
+/**
+ * Case 1 above: collapse two `<w:sectPr>`-only paragraphs that end up
+ * directly adjacent (only bookmark tags/whitespace between them) into
+ * nothing, keeping the gap. Deleting both removes the empty section they
+ * would otherwise bracket, merging the sections on either side of the pair
+ * into one continuous section — closed by whatever real `<w:sectPr>`
+ * eventually follows (another one of ours, or the document's own final
+ * one). Looped (not a single global replace) so a run of 3+ adjacent
+ * matches (e.g. three consecutive landscape tables) collapses completely,
+ * not just pairwise.
+ */
+export function collapseAdjacentSectionBreaks(documentXml) {
+  const re = new RegExp(SECTPR_ONLY_PARA + BOOKMARK_GAP + SECTPR_ONLY_PARA, 'g');
+  let out = documentXml;
+  let prev;
+  do {
+    prev = out;
+    out = out.replace(re, '$2');
+  } while (out !== prev);
+  return out;
+}
+
+/**
+ * Case 2 above: when a `<w:sectPr>`-only paragraph is the last thing before
+ * the body's own final `<w:sectPr>` (self-closed or not — a custom
+ * `reference.docx`/Lot 1 page settings can leave it populated), merge that
+ * paragraph's settings into the body-final `<w:sectPr>` and drop the
+ * paragraph. The section it described (a matched Table with nothing after
+ * it in the document) becomes the document's actual last section instead of
+ * a separate, contentless one. Must run after {@link collapseAdjacentSectionBreaks}
+ * so a run of adjacent matches at the very end of the document is already
+ * reduced to one paragraph by the time this looks for it.
+ */
+export function collapseTrailingLandscapeSection(documentXml) {
+  const re = new RegExp(
+    SECTPR_ONLY_PARA + BOOKMARK_GAP + '<w:sectPr(?:\\s*\\/>|>[\\s\\S]*?<\\/w:sectPr>)\\s*<\\/w:body>',
+  );
+  const match = documentXml.match(re);
+  if (!match) return documentXml;
+  return documentXml.replace(re, `$2<w:sectPr>$1</w:sectPr></w:body>`);
+}
+
+/**
+ * Post-process a .docx file in place: read `word/document.xml`, apply the
+ * corrections above, and write the entry back into the archive. When `toc`
+ * is true (spec §1.10/§2.2, "Lot 3"), also patches `word/settings.xml` to
+ * add `<w:updateFields w:val="true" />` — confirmed empirically that this
+ * has to happen here, on the *final* generated `.docx`, rather than on the
+ * reference doc (`referenceDocBuilder.mjs`'s `buildReferenceDoc`): Pandoc
+ * synthesizes its own `word/settings.xml` from scratch and does not carry
+ * over the reference document's, unlike `sectPr`/`theme1.xml`/`styles.xml`.
+ * When `emojiFont` is true (default — spec §1.15/§2.5, "Lot 2"), also forces
+ * the emoji color font onto any run containing a pictographic character.
+ *
+ * @param docxPath - Path to the .docx to patch.
+ * @param options.toc - Whether a TOC was requested for this export.
+ * @param options.emojiFont - Whether to force the emoji color font (default `true`).
+ */
+export function postProcessDocx(docxPath, { toc = false, emojiFont = true } = {}) {
+  const archive = resolve(docxPath);
+  const zip = new AdmZip(archive);
+
+  const originalDocument = readZipEntry(zip, 'word/document.xml');
+  let patchedDocument = repositionTocAfterTitle(renumberDrawingIds(injectNamespaces(originalDocument)));
+  patchedDocument = collapseTrailingLandscapeSection(collapseAdjacentSectionBreaks(patchedDocument));
+  if (emojiFont) patchedDocument = forceEmojiColorFont(patchedDocument);
+  let changed = false;
+  if (patchedDocument !== originalDocument) {
+    setZipEntry(zip, 'word/document.xml', patchedDocument);
+    changed = true;
+  }
+
+  if (toc) {
+    const originalSettings = readZipEntry(zip, 'word/settings.xml');
+    const patchedSettings = patchSettings(originalSettings, { toc });
+    if (patchedSettings !== originalSettings) {
+      setZipEntry(zip, 'word/settings.xml', patchedSettings);
+      changed = true;
+    }
+  }
+
+  if (!changed) return;
+  // Replace only the entries that actually changed; every other part of
+  // Pandoc's archive is left byte-for-byte untouched.
+  zip.writeZip(archive);
+}
+
+/**
+ * SmartArt package wiring — the "notable postprocess.mjs extension" flagged
+ * in `docs/specs/FUTURE_mmd2smartart_SPEC.md` §8 as needing sign-off before writing
+ * (given 2026-09-03): adds brand-new ZIP entries, not just a same-path
+ * replacement like {@link postProcessDocx} above.
+ *
+ * Why this exists at all: `packages/pandoc-filter/bin/md2nativedocx-core.mjs`
+ * cannot add `.docx` package parts or relationships itself (Pandoc's Lua
+ * filter API has no such hook, `docs/specs/FUTURE_mmd2smartart_SPEC.md` §2) — it can
+ * only write the *body* XML Pandoc embeds where the ```mermaid block was
+ * (`@md2nativedocx/core`'s `buildSmartArtDrawingXml`). So for each SmartArt
+ * diagram it instead writes the diagram's 4 XML parts to a temp directory
+ * (`smartArtDir`, an env var the CLI sets before invoking Pandoc) under a
+ * random id, and embeds placeholder relationship ids
+ * (`SMARTART_PLACEHOLDER:<id>:dm` etc.) in `r:dm`/`r:lo`/`r:qs`/`r:cs` —
+ * never valid Word relationship ids, just a correlation key. This function
+ * is the package-aware step that runs after Pandoc has produced the whole
+ * `.docx`: it finds those placeholders, mints real `rId`s, writes the real
+ * parts into `word/diagrams/`, and wires up `[Content_Types].xml` +
+ * `word/_rels/document.xml.rels` to match — completing exactly the same 4
+ * relationships/parts a real Word-authored SmartArt diagram would have
+ * (spec §3).
+ */
+// The id is whatever the core bridge chose (randomUUID() in production, so
+// hex+dashes in practice) -- matched as "anything but the ':' delimiter"
+// rather than assuming that specific alphabet, so this isn't silently
+// fragile against a different id scheme later.
+const SMARTART_PLACEHOLDER_RE = /SMARTART_PLACEHOLDER:([^:]+):(dm|lo|qs|cs)/g;
+
+const SMARTART_RELTYPE = {
+  dm: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramData',
+  lo: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramLayout',
+  qs: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramQuickStyle',
+  cs: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramColors',
+};
+const SMARTART_CONTENTTYPE = {
+  dm: 'application/vnd.openxmlformats-officedocument.drawingml.diagramData+xml',
+  lo: 'application/vnd.openxmlformats-officedocument.drawingml.diagramLayout+xml',
+  qs: 'application/vnd.openxmlformats-officedocument.drawingml.diagramStyle+xml',
+  cs: 'application/vnd.openxmlformats-officedocument.drawingml.diagramColors+xml',
+};
+/** `data`/`layout`/`quickStyle`/`colors` — the on-disk part-name stem per kind (`qs` -> `quickStyle1.xml`, not `qs1.xml`). */
+const SMARTART_PART_STEM = { dm: 'data', lo: 'layout', qs: 'quickStyle', cs: 'colors' };
+/** The 4 files `md2nativedocx-core.mjs` writes per diagram id, one per relIds kind. */
+const SMARTART_SOURCE_FILE = { dm: 'data.xml', lo: 'layout.xml', qs: 'quickStyle.xml', cs: 'colors.xml' };
+
+/** The optional fifth part: the pre-rendered `dsp:drawing` Word and LibreOffice show as the diagram's cached rendering. */
+const SMARTART_DRAWING_RELTYPE = 'http://schemas.microsoft.com/office/2007/relationships/diagramDrawing';
+const SMARTART_DRAWING_CONTENTTYPE = 'application/vnd.ms-office.drawingml.diagramDrawing+xml';
+
+/** Every distinct placeholder diagram id referenced in `documentXml`, in first-seen order. */
+function findSmartArtPlaceholderIds(documentXml) {
+  const ids = [];
+  const seen = new Set();
+  for (const match of documentXml.matchAll(SMARTART_PLACEHOLDER_RE)) {
+    const id = match[1];
+    if (!seen.has(id)) {
+      seen.add(id);
+      ids.push(id);
+    }
+  }
+  return ids;
+}
+
+/** The next unused `word/diagrams/data{N}.xml` number, scanning the archive's existing entries (1 if none). */
+function nextSmartArtPartNumber(zip) {
+  let max = 0;
+  for (const entry of zip.getEntries()) {
+    const match = /^word\/diagrams\/data(\d+)\.xml$/.exec(entry.entryName);
+    if (match) max = Math.max(max, Number(match[1]));
+  }
+  return max + 1;
+}
+
+/** A relationship `Id` not already present in `relsXml`, built from `prefix` + an incrementing counter. */
+function nextFreeRelId(relsXml, prefix) {
+  let n = 1;
+  while (relsXml.includes(`Id="${prefix}${n}"`)) n += 1;
+  return `${prefix}${n}`;
+}
+
+/**
+ * Complete the SmartArt wiring for every placeholder diagram found in
+ * `docxPath`'s `word/document.xml` — a no-op (no extraction, no rezip) if
+ * none are present, which covers every export that never dispatched to
+ * SmartArt in the first place. Must run after {@link postProcessDocx} (this
+ * reads the already-namespace-fixed/id-renumbered `word/document.xml`).
+ *
+ * @param docxPath - Path to the .docx to patch.
+ * @param smartArtDir - The directory `MD2NATIVEDOCX_SMARTART_DIR` pointed
+ *   the core bridge at; each placeholder id names a `<smartArtDir>/<id>/`
+ *   subdirectory holding that diagram's `data.xml`/`layout.xml`/
+ *   `colors.xml`/`quickStyle.xml`.
+ */
+export function injectSmartArtParts(docxPath, smartArtDir) {
+  const archive = resolve(docxPath);
+  const zip = new AdmZip(archive);
+  let documentXml = readZipEntry(zip, 'word/document.xml');
+
+  const ids = findSmartArtPlaceholderIds(documentXml);
+  if (ids.length === 0) return;
+
+  if (!smartArtDir) {
+    throw new Error(
+      'md2nativedocx: document.xml references SmartArt placeholders but no smartArtDir was given'
+    );
+  }
+
+  let contentTypes = readZipEntry(zip, '[Content_Types].xml');
+  let relsXml = readZipEntry(zip, 'word/_rels/document.xml.rels');
+
+  let nextPartNumber = nextSmartArtPartNumber(zip);
+  const newParts = [];
+
+  for (const id of ids) {
+    const sourceDir = join(smartArtDir, id);
+    if (!existsSync(sourceDir)) {
+      throw new Error(`md2nativedocx: no SmartArt parts found for diagram "${id}" in ${smartArtDir}`);
+    }
+
+    const n = nextPartNumber++;
+
+    // Optional 5th part (`dsp:drawing`): written by the bridge only when SmartArt drawings are on. Its
+    // relationship id lives inside the *data* part (`dsp:dataModelExt/@relId`), not in document.xml.
+    let drawingRelId = null;
+    const drawingFile = join(sourceDir, 'drawing.xml');
+    if (existsSync(drawingFile)) {
+      drawingRelId = nextFreeRelId(relsXml, `rIdSmartArt${n}DR`);
+      relsXml = relsXml.replace(
+        '</Relationships>',
+        `<Relationship Id="${drawingRelId}" Type="${SMARTART_DRAWING_RELTYPE}" Target="diagrams/drawing${n}.xml" /></Relationships>`
+      );
+      contentTypes = contentTypes.replace(
+        '</Types>',
+        `<Override PartName="/word/diagrams/drawing${n}.xml" ContentType="${SMARTART_DRAWING_CONTENTTYPE}" /></Types>`
+      );
+      newParts.push([`word/diagrams/drawing${n}.xml`, readFileSync(drawingFile, 'utf8')]);
+    }
+
+    /** @type {Record<'dm'|'lo'|'qs'|'cs', string>} */
+    const relIds = {};
+    for (const kind of /** @type {const} */ (['dm', 'lo', 'qs', 'cs'])) {
+      const partName = `${SMARTART_PART_STEM[kind]}${n}.xml`;
+      const partPath = `word/diagrams/${partName}`;
+      let xml = readFileSync(join(sourceDir, SMARTART_SOURCE_FILE[kind]), 'utf8');
+      if (kind === 'dm') {
+        const token = `SMARTART_PLACEHOLDER:${id}:dr`;
+        if (drawingRelId) xml = xml.split(token).join(drawingRelId);
+        else if (xml.includes(token)) {
+          throw new Error(`md2nativedocx: SmartArt diagram "${id}" references a drawing part that was not written`);
+        }
+      }
+
+      const relId = nextFreeRelId(relsXml, `rIdSmartArt${n}${kind.toUpperCase()}`);
+      relIds[kind] = relId;
+      relsXml = relsXml.replace(
+        '</Relationships>',
+        `<Relationship Id="${relId}" Type="${SMARTART_RELTYPE[kind]}" Target="diagrams/${partName}" /></Relationships>`
+      );
+      contentTypes = contentTypes.replace(
+        '</Types>',
+        `<Override PartName="/${partPath}" ContentType="${SMARTART_CONTENTTYPE[kind]}" /></Types>`
+      );
+
+      newParts.push([partPath, xml]);
+    }
+
+    for (const kind of /** @type {const} */ (['dm', 'lo', 'qs', 'cs'])) {
+      documentXml = documentXml.split(`SMARTART_PLACEHOLDER:${id}:${kind}`).join(relIds[kind]);
+    }
+  }
+
+  // No rule #3 check here (unlike the from-scratch spike scripts this
+  // logic descends from): `relsXml` is the *real* document's existing
+  // rels file, which may legitimately already contain external
+  // relationships Pandoc itself created for Markdown hyperlinks --
+  // unrelated to anything this function adds. The 4 relationships added
+  // above are always internal (`Target="diagrams/..."`, no `TargetMode`
+  // attribute at all), by construction, not by a runtime check.
+  setZipEntry(zip, 'word/document.xml', documentXml);
+  setZipEntry(zip, '[Content_Types].xml', contentTypes);
+  setZipEntry(zip, 'word/_rels/document.xml.rels', relsXml);
+  for (const [partPath, xml] of newParts) {
+    setZipEntry(zip, partPath, xml);
+  }
+
+  zip.writeZip(archive);
+}