@wonderwhy-er/desktop-commander 0.2.34 → 0.2.36

package/dist/tools/docx/dom.js

@@ -0,0 +1,228 @@
+/**
+ * DOM utilities for DOCX XML manipulation.
+ *
+ * Single Responsibility: XML parsing, navigation, and minimal element
+ * mutation.  No file I/O — every function works on in-memory DOM nodes.
+ *
+ * Uses @xmldom/xmldom for parsing and serialisation so that the
+ * document-order of nodes is always preserved.
+ */
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+// ═══════════════════════════════════════════════════════════════════════
+// XML parse / serialize
+// ═══════════════════════════════════════════════════════════════════════
+export function parseXml(xmlStr) {
+    return new DOMParser().parseFromString(xmlStr, 'application/xml');
+}
+export function serializeXml(doc) {
+    return new XMLSerializer().serializeToString(doc);
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Generic DOM helpers
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Convert any NodeList / HTMLCollection-like object into a real array.
+ */
+export function nodeListToArray(nl) {
+    const arr = [];
+    for (let i = 0; i < nl.length; i++) {
+        const n = nl.item(i);
+        if (n)
+            arr.push(n);
+    }
+    return arr;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Body access
+// ═══════════════════════════════════════════════════════════════════════
+/** Return the single <w:body> element from a parsed document.xml DOM. */
+export function getBody(doc) {
+    const body = doc.getElementsByTagName('w:body').item(0);
+    if (!body)
+        throw new Error('Invalid DOCX DOM: missing <w:body>');
+    return body;
+}
+/**
+ * Return ALL direct element children of w:body **in document order**.
+ * Includes w:p, w:tbl, w:sdt, w:sectPr, etc.
+ */
+export function getBodyChildren(body) {
+    const out = [];
+    for (const node of nodeListToArray(body.childNodes)) {
+        if (node.nodeType === 1)
+            out.push(node);
+    }
+    return out;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Body signature
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Build a compact signature string from the body children array.
+ * Maps each node's qualified name to a short local name:
+ *   w:p → p, w:tbl → tbl, w:sdt → sdt, w:sectPr → sectPr, …
+ * Returns e.g. "p,tbl,p,p,sectPr".
+ */
+export function bodySignature(children) {
+    return children
+        .map((ch) => {
+        const name = ch.nodeName;
+        const idx = name.indexOf(':');
+        return idx >= 0 ? name.substring(idx + 1) : name;
+    })
+        .join(',');
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Paragraph text helpers
+// ═══════════════════════════════════════════════════════════════════════
+/** Concatenate text from every <w:t> descendant of a paragraph. */
+export function getParagraphText(p) {
+    const tNodes = p.getElementsByTagName('w:t');
+    let out = '';
+    for (let i = 0; i < tNodes.length; i++) {
+        out += tNodes.item(i)?.textContent ?? '';
+    }
+    return out;
+}
+/** Read the style id from w:pPr/w:pStyle/@w:val, or null if absent. */
+export function getParagraphStyle(p) {
+    for (const child of nodeListToArray(p.childNodes)) {
+        if (child.nodeType === 1 && child.nodeName === 'w:pPr') {
+            const pPr = child;
+            for (const prChild of nodeListToArray(pPr.childNodes)) {
+                if (prChild.nodeType === 1 && prChild.nodeName === 'w:pStyle') {
+                    return prChild.getAttribute('w:val');
+                }
+            }
+            return null;
+        }
+    }
+    return null;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Minimal text replacement
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Replace the text of a paragraph with minimal DOM changes.
+ * Sets the FIRST w:t to `text`, clears every subsequent w:t.
+ * Sets xml:space="preserve" so leading/trailing spaces survive.
+ * Does NOT recreate runs or remove paragraph properties.
+ */
+export function setParagraphTextMinimal(p, text) {
+    const tNodes = p.getElementsByTagName('w:t');
+    if (tNodes.length === 0)
+        return;
+    const first = tNodes.item(0);
+    first.textContent = text;
+    first.setAttribute('xml:space', 'preserve');
+    for (let i = 1; i < tNodes.length; i++) {
+        tNodes.item(i).textContent = '';
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Run-level formatting helpers
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Ensure a <w:r> element has w:rPr/w:color[@w:val=hex].
+ * Creates w:rPr and w:color if they don't exist.
+ * Only touches the colour — leaves every other run property intact.
+ */
+export function ensureRunColor(run, hex) {
+    const doc = run.ownerDocument;
+    if (!doc)
+        return;
+    let rPr = findDirectChild(run, 'w:rPr');
+    if (!rPr) {
+        rPr = doc.createElement('w:rPr');
+        if (run.firstChild) {
+            run.insertBefore(rPr, run.firstChild);
+        }
+        else {
+            run.appendChild(rPr);
+        }
+    }
+    let colorEl = findDirectChild(rPr, 'w:color');
+    if (!colorEl) {
+        colorEl = doc.createElement('w:color');
+        rPr.appendChild(colorEl);
+    }
+    colorEl.setAttribute('w:val', hex);
+}
+/**
+ * Apply run-level colour to every <w:r> in a paragraph.
+ */
+export function colorParagraphRuns(p, color) {
+    const runs = nodeListToArray(p.getElementsByTagName('w:r'));
+    for (const r of runs) {
+        ensureRunColor(r, color);
+    }
+}
+/**
+ * Apply bold / italic / color to every <w:r> in a paragraph.
+ * Preserves all existing w:rPr children; only modifies specified props.
+ */
+export function styleParagraphRuns(p, style) {
+    const doc = p.ownerDocument;
+    if (!doc)
+        return;
+    const runs = nodeListToArray(p.getElementsByTagName('w:r'));
+    for (const r of runs) {
+        let rPr = findDirectChild(r, 'w:rPr');
+        if (!rPr) {
+            rPr = doc.createElement('w:rPr');
+            if (r.firstChild) {
+                r.insertBefore(rPr, r.firstChild);
+            }
+            else {
+                r.appendChild(rPr);
+            }
+        }
+        if (style.color) {
+            let colorNode = findDirectChild(rPr, 'w:color');
+            if (!colorNode) {
+                colorNode = doc.createElement('w:color');
+                rPr.appendChild(colorNode);
+            }
+            colorNode.setAttribute('w:val', style.color);
+        }
+        if (style.bold !== undefined) {
+            toggleElement(doc, rPr, 'w:b', style.bold);
+        }
+        if (style.italic !== undefined) {
+            toggleElement(doc, rPr, 'w:i', style.italic);
+        }
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Counting helpers
+// ═══════════════════════════════════════════════════════════════════════
+/** Count direct w:tbl children of body. */
+export function countTables(children) {
+    return children.filter((ch) => ch.nodeName === 'w:tbl').length;
+}
+/** Count <w:drawing> descendants (rough image count). */
+export function countImages(body) {
+    return body.getElementsByTagName('w:drawing').length;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Private helpers (DRY: used by multiple public functions)
+// ═══════════════════════════════════════════════════════════════════════
+/** Find the first direct child element with the given nodeName. */
+function findDirectChild(parent, nodeName) {
+    for (const child of nodeListToArray(parent.childNodes)) {
+        if (child.nodeType === 1 && child.nodeName === nodeName) {
+            return child;
+        }
+    }
+    return null;
+}
+/** Add or remove a simple flag element (e.g. w:b, w:i) inside a parent. */
+function toggleElement(doc, parent, nodeName, enabled) {
+    const existing = findDirectChild(parent, nodeName);
+    if (enabled && !existing) {
+        parent.appendChild(doc.createElement(nodeName));
+    }
+    else if (!enabled && existing) {
+        parent.removeChild(existing);
+    }
+}

package/dist/tools/docx/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DOCX Error Handling
+ *
+ * Centralised error class and async error-wrapping utility.
+ *
+ * @module docx/errors
+ */
+export declare class DocxError extends Error {
+    readonly code: string;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, context?: Record<string, unknown> | undefined);
+    toJSON(): Record<string, unknown>;
+}
+export declare enum DocxErrorCode {
+    INVALID_DOCX = "INVALID_DOCX",
+    INVALID_PATH = "INVALID_PATH",
+    OPERATION_FAILED = "OPERATION_FAILED",
+    UNKNOWN_OPERATION = "UNKNOWN_OPERATION",
+    UNSUPPORTED_OPERATION = "UNSUPPORTED_OPERATION",
+    DOCX_CREATE_FAILED = "DOCX_CREATE_FAILED",
+    DOCX_EDIT_FAILED = "DOCX_EDIT_FAILED",
+    DOCX_READ_FAILED = "DOCX_READ_FAILED",
+    INVALID_IMAGE_FILE = "INVALID_IMAGE_FILE",
+    INVALID_IMAGE_DATA_URL = "INVALID_IMAGE_DATA_URL",
+    GET_INFO_FAILED = "GET_INFO_FAILED"
+}
+/** Wrap an async operation — re-throws existing DocxErrors, wraps everything else. */
+export declare function withErrorContext<T>(operation: () => Promise<T>, errorCode: DocxErrorCode | string, context?: Record<string, unknown>): Promise<T>;

package/dist/tools/docx/errors.js

@@ -0,0 +1,48 @@
+/**
+ * DOCX Error Handling
+ *
+ * Centralised error class and async error-wrapping utility.
+ *
+ * @module docx/errors
+ */
+export class DocxError extends Error {
+    constructor(message, code, context) {
+        super(message);
+        this.code = code;
+        this.context = context;
+        this.name = 'DocxError';
+        Error.captureStackTrace?.(this, DocxError);
+    }
+    toJSON() {
+        return { name: this.name, message: this.message, code: this.code, context: this.context };
+    }
+}
+export var DocxErrorCode;
+(function (DocxErrorCode) {
+    DocxErrorCode["INVALID_DOCX"] = "INVALID_DOCX";
+    DocxErrorCode["INVALID_PATH"] = "INVALID_PATH";
+    DocxErrorCode["OPERATION_FAILED"] = "OPERATION_FAILED";
+    DocxErrorCode["UNKNOWN_OPERATION"] = "UNKNOWN_OPERATION";
+    DocxErrorCode["UNSUPPORTED_OPERATION"] = "UNSUPPORTED_OPERATION";
+    DocxErrorCode["DOCX_CREATE_FAILED"] = "DOCX_CREATE_FAILED";
+    DocxErrorCode["DOCX_EDIT_FAILED"] = "DOCX_EDIT_FAILED";
+    DocxErrorCode["DOCX_READ_FAILED"] = "DOCX_READ_FAILED";
+    DocxErrorCode["INVALID_IMAGE_FILE"] = "INVALID_IMAGE_FILE";
+    DocxErrorCode["INVALID_IMAGE_DATA_URL"] = "INVALID_IMAGE_DATA_URL";
+    DocxErrorCode["GET_INFO_FAILED"] = "GET_INFO_FAILED";
+})(DocxErrorCode || (DocxErrorCode = {}));
+/** Wrap an async operation — re-throws existing DocxErrors, wraps everything else. */
+export async function withErrorContext(operation, errorCode, context) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof DocxError)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        throw new DocxError(message, errorCode, {
+            ...context,
+            originalError: error instanceof Error ? error.stack : String(error),
+        });
+    }
+}

package/dist/tools/docx/extractors/images.d.ts

@@ -0,0 +1,14 @@
+/**
+ * DOCX Image Extractor (Mammoth Fallback)
+ *
+ * Extracts images from HTML generated by mammoth.js fallback.
+ * Only used when styled parser is not available.
+ *
+ * @module docx/extractors/images
+ */
+import type { DocxImage } from '../types.js';
+/**
+ * Extract base64-encoded images from HTML (mammoth.js fallback only).
+ * Returns empty array if parsing fails.
+ */
+export declare function extractImagesFromHtml(html: string): DocxImage[];

package/dist/tools/docx/extractors/images.js

@@ -0,0 +1,40 @@
+/**
+ * DOCX Image Extractor (Mammoth Fallback)
+ *
+ * Extracts images from HTML generated by mammoth.js fallback.
+ * Only used when styled parser is not available.
+ *
+ * @module docx/extractors/images
+ */
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const { DOMParser } = require('@xmldom/xmldom');
+/**
+ * Extract base64-encoded images from HTML (mammoth.js fallback only).
+ * Returns empty array if parsing fails.
+ */
+export function extractImagesFromHtml(html) {
+    const images = [];
+    try {
+        const doc = new DOMParser().parseFromString(html, 'text/html');
+        const imgElements = doc.getElementsByTagName('img');
+        for (let i = 0; i < imgElements.length; i++) {
+            const src = imgElements[i].getAttribute('src') || '';
+            const alt = imgElements[i].getAttribute('alt') || '';
+            const match = src.match(/^data:([^;]+);base64,(.+)$/);
+            if (match) {
+                images.push({
+                    id: `img_${i}`,
+                    data: match[2],
+                    mimeType: match[1],
+                    altText: alt || undefined,
+                    originalSize: Buffer.from(match[2], 'base64').length,
+                });
+            }
+        }
+    }
+    catch {
+        // Non-critical
+    }
+    return images;
+}

package/dist/tools/docx/extractors/metadata.d.ts

@@ -0,0 +1,14 @@
+/**
+ * DOCX Metadata Extractor
+ *
+ * Extracts document metadata (title, author, dates, etc.) from DOCX core properties.
+ * Follows Single Responsibility Principle — only handles metadata extraction.
+ *
+ * @module docx/extractors/metadata
+ */
+import type { DocxMetadata } from '../types.js';
+/**
+ * Extract metadata from a DOCX buffer.
+ * Returns minimal metadata if extraction fails (non-critical operation).
+ */
+export declare function extractDocxMetadata(buffer: Buffer, fileSize?: number): Promise<DocxMetadata>;

package/dist/tools/docx/extractors/metadata.js

@@ -0,0 +1,64 @@
+/**
+ * DOCX Metadata Extractor
+ *
+ * Extracts document metadata (title, author, dates, etc.) from DOCX core properties.
+ * Follows Single Responsibility Principle — only handles metadata extraction.
+ *
+ * @module docx/extractors/metadata
+ */
+import { createRequire } from 'module';
+import { CORE_PROPERTIES_PATH, DOCX_NAMESPACES } from '../constants.js';
+const require = createRequire(import.meta.url);
+const { DOMParser } = require('@xmldom/xmldom');
+/**
+ * Extract metadata from a DOCX buffer.
+ * Returns minimal metadata if extraction fails (non-critical operation).
+ */
+export async function extractDocxMetadata(buffer, fileSize) {
+    const metadata = { fileSize };
+    try {
+        const JSZip = require('jszip');
+        const zip = await JSZip.loadAsync(buffer);
+        const corePropsFile = zip.file(CORE_PROPERTIES_PATH);
+        if (!corePropsFile)
+            return metadata;
+        const corePropsXml = await corePropsFile.async('string');
+        const doc = new DOMParser().parseFromString(corePropsXml, 'application/xml');
+        /** Extract text content from a namespaced tag. */
+        const getText = (tag, nsList = [DOCX_NAMESPACES.DUBLIN_CORE, DOCX_NAMESPACES.CUSTOM_PROPERTIES]) => {
+            for (const ns of nsList) {
+                const els = doc.getElementsByTagName(`${ns}:${tag}`);
+                if (els.length > 0 && els[0].textContent) {
+                    const text = els[0].textContent.trim();
+                    return text || undefined;
+                }
+            }
+            return undefined;
+        };
+        /** Extract date from a DCTERMS namespaced tag. */
+        const getDate = (tag) => {
+            const els = doc.getElementsByTagName(`${DOCX_NAMESPACES.DCTERMS}:${tag}`);
+            if (els.length > 0 && els[0].textContent) {
+                const dateStr = els[0].textContent.trim();
+                if (dateStr) {
+                    const d = new Date(dateStr);
+                    if (!isNaN(d.getTime()))
+                        return d;
+                }
+            }
+            return undefined;
+        };
+        metadata.title = getText('title');
+        metadata.author = getText('creator');
+        metadata.subject = getText('subject');
+        metadata.description = getText('description');
+        metadata.lastModifiedBy = getText('lastModifiedBy', [DOCX_NAMESPACES.CUSTOM_PROPERTIES]);
+        metadata.revision = getText('revision', [DOCX_NAMESPACES.CUSTOM_PROPERTIES]);
+        metadata.creationDate = getDate('created');
+        metadata.modificationDate = getDate('modified');
+    }
+    catch {
+        // Non-critical — return metadata with fileSize only
+    }
+    return metadata;
+}

package/dist/tools/docx/extractors/sections.d.ts

@@ -0,0 +1,14 @@
+/**
+ * DOCX Section Parser
+ *
+ * Parses HTML into structured sections (headings, paragraphs, tables, lists, images).
+ * Follows Single Responsibility Principle — only handles section parsing.
+ *
+ * @module docx/extractors/sections
+ */
+import type { DocxSection } from '../types.js';
+/**
+ * Parse HTML into structured sections.
+ * Returns a single paragraph section if parsing fails.
+ */
+export declare function parseHtmlIntoSections(html: string): DocxSection[];

package/dist/tools/docx/extractors/sections.js

@@ -0,0 +1,61 @@
+/**
+ * DOCX Section Parser
+ *
+ * Parses HTML into structured sections (headings, paragraphs, tables, lists, images).
+ * Follows Single Responsibility Principle — only handles section parsing.
+ *
+ * @module docx/extractors/sections
+ */
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const { DOMParser } = require('@xmldom/xmldom');
+/**
+ * Parse HTML into structured sections.
+ * Returns a single paragraph section if parsing fails.
+ */
+export function parseHtmlIntoSections(html) {
+    const sections = [];
+    try {
+        const doc = new DOMParser().parseFromString(html, 'text/html');
+        const body = doc.getElementsByTagName('body')[0];
+        if (!body) {
+            sections.push({ type: 'paragraph', content: html });
+            return sections;
+        }
+        for (let i = 0; i < body.childNodes.length; i++) {
+            const child = body.childNodes[i];
+            if (child.nodeType !== 1)
+                continue;
+            const element = child;
+            const tag = element.tagName.toLowerCase();
+            const content = element.outerHTML || element.innerHTML;
+            // Heading detection
+            const headingMatch = tag.match(/^h([1-6])$/);
+            if (headingMatch) {
+                sections.push({ type: 'heading', level: parseInt(headingMatch[1], 10), content });
+                continue;
+            }
+            // Other element types
+            switch (tag) {
+                case 'img':
+                    sections.push({ type: 'image', content });
+                    break;
+                case 'table':
+                    sections.push({ type: 'table', content });
+                    break;
+                case 'ul':
+                case 'ol':
+                    sections.push({ type: 'list', content });
+                    break;
+                case 'p':
+                case 'div':
+                    sections.push({ type: 'paragraph', content });
+                    break;
+            }
+        }
+    }
+    catch {
+        sections.push({ type: 'paragraph', content: html });
+    }
+    return sections;
+}

package/dist/tools/docx/html.d.ts

@@ -0,0 +1,17 @@
+/**
+ * DOCX → HTML Conversion
+ *
+ * Primary:  Direct DOCX XML parsing (`styled-html-parser`) — preserves inline styles
+ *           (font colours, sizes, families, alignment, highlights, etc.)
+ * Fallback: mammoth.js — semantic-only conversion, strips visual styles.
+ *
+ * @module docx/html
+ */
+import type { DocxParseResult, DocxParseOptions } from './types.js';
+/**
+ * Parse a DOCX file to styled HTML.
+ *
+ * Uses direct XML parsing when `preserveFormatting` is true (default).
+ * Falls back to mammoth.js if direct parsing fails or a custom `styleMap` is provided.
+ */
+export declare function parseDocxToHtml(source: string, options?: DocxParseOptions): Promise<DocxParseResult>;

package/dist/tools/docx/html.js

@@ -0,0 +1,111 @@
+/**
+ * DOCX → HTML Conversion
+ *
+ * Primary:  Direct DOCX XML parsing (`styled-html-parser`) — preserves inline styles
+ *           (font colours, sizes, families, alignment, highlights, etc.)
+ * Fallback: mammoth.js — semantic-only conversion, strips visual styles.
+ *
+ * @module docx/html
+ */
+import fs from 'fs/promises';
+import { createRequire } from 'module';
+import { DocxError, DocxErrorCode, withErrorContext } from './errors.js';
+import { DEFAULT_CONVERSION_OPTIONS } from './constants.js';
+import { isUrl } from './utils/paths.js';
+import { convertDocxToStyledHtml } from './styled-html-parser.js';
+import { extractDocxMetadata } from './extractors/metadata.js';
+import { parseHtmlIntoSections } from './extractors/sections.js';
+import { extractImagesFromHtml } from './extractors/images.js';
+const require = createRequire(import.meta.url);
+const mammoth = require('mammoth');
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Parse a DOCX file to styled HTML.
+ *
+ * Uses direct XML parsing when `preserveFormatting` is true (default).
+ * Falls back to mammoth.js if direct parsing fails or a custom `styleMap` is provided.
+ */
+export async function parseDocxToHtml(source, options = {}) {
+    return withErrorContext(async () => {
+        const { includeImages = DEFAULT_CONVERSION_OPTIONS.includeImages, preserveFormatting = DEFAULT_CONVERSION_OPTIONS.preserveFormatting, styleMap = DEFAULT_CONVERSION_OPTIONS.styleMap, } = options;
+        const buffer = await loadDocxToBuffer(source);
+        let fileSize;
+        if (!isUrl(source)) {
+            try {
+                fileSize = (await fs.stat(source)).size;
+            }
+            catch { /* ignore */ }
+        }
+        const { html: rawHtml, images, documentDefaults } = await convertToHtml(buffer, includeImages, preserveFormatting, styleMap);
+        const metadata = await extractDocxMetadata(buffer, fileSize);
+        const html = postProcessHtml(rawHtml);
+        const sections = parseHtmlIntoSections(html);
+        return { html, metadata, images, sections, documentDefaults };
+    }, DocxErrorCode.DOCX_READ_FAILED, { path: source });
+}
+// ─── Buffer Loading ──────────────────────────────────────────────────────────
+async function loadDocxToBuffer(source) {
+    return withErrorContext(async () => {
+        if (isUrl(source)) {
+            const response = await fetch(source);
+            if (!response.ok) {
+                throw new DocxError(`Failed to fetch DOCX from URL: ${response.statusText}`, DocxErrorCode.DOCX_READ_FAILED, { url: source, status: response.status });
+            }
+            return Buffer.from(await response.arrayBuffer());
+        }
+        return await fs.readFile(source);
+    }, DocxErrorCode.DOCX_READ_FAILED, { source });
+}
+// ─── Conversion Dispatch ─────────────────────────────────────────────────────
+/**
+ * Pick the best converter: direct XML parser (preserves styles) or mammoth.js (semantic only).
+ */
+async function convertToHtml(buffer, includeImages, preserveFormatting, styleMap) {
+    // Use the styled XML parser when no custom styleMap is provided and formatting is requested
+    if (preserveFormatting && styleMap.length === 0) {
+        try {
+            return await convertDocxToStyledHtml(buffer, includeImages);
+        }
+        catch {
+            // Fall through to mammoth.js fallback
+        }
+    }
+    const mammothResult = await convertWithMammoth(buffer, includeImages, styleMap, preserveFormatting);
+    return { ...mammothResult, documentDefaults: undefined };
+}
+/** Fallback: mammoth.js (semantic-only — strips visual styles). */
+async function convertWithMammoth(buffer, includeImages, styleMap, preserveFormatting) {
+    const mammothOptions = {};
+    if (includeImages) {
+        mammothOptions.convertImage = mammoth.images.imgElement((image) => image.read('base64').then((base64Data) => ({
+            src: `data:${image.contentType};base64,${base64Data}`,
+        })));
+    }
+    if (styleMap.length > 0) {
+        mammothOptions.styleMap = [...styleMap];
+    }
+    else if (preserveFormatting) {
+        mammothOptions.styleMap = [
+            "p[style-name='Heading 1'] => h1:fresh",
+            "p[style-name='Heading 2'] => h2:fresh",
+            "p[style-name='Heading 3'] => h3:fresh",
+            "p[style-name='Heading 4'] => h4:fresh",
+            "p[style-name='Heading 5'] => h5:fresh",
+            "p[style-name='Heading 6'] => h6:fresh",
+            "p[style-name='Title'] => h1:fresh",
+            "p[style-name='Subtitle'] => h2:fresh",
+            "p[style-name='Quote'] => blockquote:fresh",
+            "r[style-name='Strong'] => strong",
+            "r[style-name='Emphasis'] => em",
+        ];
+    }
+    const result = await mammoth.convertToHtml({ buffer }, mammothOptions);
+    const html = result.value;
+    const images = extractImagesFromHtml(html);
+    return { html, images };
+}
+// ─── Post-Processing ─────────────────────────────────────────────────────────
+/** Minimal whitespace cleanup — preserves all inline style attributes. */
+function postProcessHtml(html) {
+    return html.replace(/>\s{2,}</g, '>\n<').trim();
+}

package/dist/tools/docx/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * DOCX file manipulation tools — barrel exports.
+ */
+export { readDocxOutline } from './read.js';
+export { writeDocxPatched } from './write.js';
+export { createDocxNew } from './create.js';
+export type { DocxContentStructure, DocxContentItem, DocxContentParagraph, DocxContentTable, DocxContentImage, } from './types.js';
+export { readDocx, extractTextFromDocx, getDocxMetadata, extractBodyXml } from './read.js';
+export { writeDocx, modifyDocxContent, replaceBodyXml } from './modify.js';
+export type { DocxMetadata, DocxParagraph, DocxRun, DocxModification, ParagraphOutline, ReadDocxResult, WriteDocxStats, WriteDocxResult, BodySnapshot, DocxOp, OpResult, } from './types.js';

package/dist/tools/docx/index.js

@@ -0,0 +1,10 @@
+/**
+ * DOCX file manipulation tools — barrel exports.
+ */
+// Patch-based tools (read_docx / write_docx)
+export { readDocxOutline } from './read.js';
+export { writeDocxPatched } from './write.js';
+export { createDocxNew } from './create.js';
+// Legacy functions (used by read_file, write_file, edit_block handlers)
+export { readDocx, extractTextFromDocx, getDocxMetadata, extractBodyXml } from './read.js';
+export { writeDocx, modifyDocxContent, replaceBodyXml } from './modify.js';