npm - @wonderwhy-er/desktop-commander - Versions diffs - 0.2.34 → 0.2.36 - Mend

@wonderwhy-er/desktop-commander 0.2.34 → 0.2.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (179) hide show

package/README.md +2 -0
package/dist/handlers/filesystem-handlers.js +58 -11
package/dist/handlers/history-handlers.d.ts +7 -0
package/dist/handlers/history-handlers.js +33 -1
package/dist/server.js +30 -4
package/dist/tools/docx/builders/html-builder.d.ts +17 -0
package/dist/tools/docx/builders/html-builder.js +92 -0
package/dist/tools/docx/builders/image.d.ts +14 -0
package/dist/tools/docx/builders/image.js +84 -0
package/dist/tools/docx/builders/index.d.ts +11 -0
package/dist/tools/docx/builders/index.js +11 -0
package/dist/tools/docx/builders/markdown-builder.d.ts +2 -0
package/dist/tools/docx/builders/markdown-builder.js +260 -0
package/dist/tools/docx/builders/paragraph.d.ts +12 -0
package/dist/tools/docx/builders/paragraph.js +29 -0
package/dist/tools/docx/builders/table.d.ts +8 -0
package/dist/tools/docx/builders/table.js +94 -0
package/dist/tools/docx/builders/utils.d.ts +5 -0
package/dist/tools/docx/builders/utils.js +18 -0
package/dist/tools/docx/constants.d.ts +32 -0
package/dist/tools/docx/constants.js +61 -0
package/dist/tools/docx/converters/markdown-to-html.d.ts +17 -0
package/dist/tools/docx/converters/markdown-to-html.js +111 -0
package/dist/tools/docx/create.d.ts +21 -0
package/dist/tools/docx/create.js +386 -0
package/dist/tools/docx/dom.d.ts +66 -0
package/dist/tools/docx/dom.js +228 -0
package/dist/tools/docx/errors.d.ts +28 -0
package/dist/tools/docx/errors.js +48 -0
package/dist/tools/docx/extractors/images.d.ts +14 -0
package/dist/tools/docx/extractors/images.js +40 -0
package/dist/tools/docx/extractors/metadata.d.ts +14 -0
package/dist/tools/docx/extractors/metadata.js +64 -0
package/dist/tools/docx/extractors/sections.d.ts +14 -0
package/dist/tools/docx/extractors/sections.js +61 -0
package/dist/tools/docx/html.d.ts +17 -0
package/dist/tools/docx/html.js +111 -0
package/dist/tools/docx/index.d.ts +10 -0
package/dist/tools/docx/index.js +10 -0
package/dist/tools/docx/markdown.d.ts +84 -0
package/dist/tools/docx/markdown.js +507 -0
package/dist/tools/docx/modify.d.ts +28 -0
package/dist/tools/docx/modify.js +271 -0
package/dist/tools/docx/operations/handlers/index.d.ts +39 -0
package/dist/tools/docx/operations/handlers/index.js +152 -0
package/dist/tools/docx/operations/html-manipulator.d.ts +24 -0
package/dist/tools/docx/operations/html-manipulator.js +352 -0
package/dist/tools/docx/operations/index.d.ts +14 -0
package/dist/tools/docx/operations/index.js +61 -0
package/dist/tools/docx/operations/operation-handlers.d.ts +3 -0
package/dist/tools/docx/operations/operation-handlers.js +67 -0
package/dist/tools/docx/operations/preprocessor.d.ts +14 -0
package/dist/tools/docx/operations/preprocessor.js +44 -0
package/dist/tools/docx/operations/xml-replacer.d.ts +9 -0
package/dist/tools/docx/operations/xml-replacer.js +35 -0
package/dist/tools/docx/operations.d.ts +13 -0
package/dist/tools/docx/operations.js +13 -0
package/dist/tools/docx/ops/delete-paragraph-at-body-index.d.ts +11 -0
package/dist/tools/docx/ops/delete-paragraph-at-body-index.js +23 -0
package/dist/tools/docx/ops/header-replace-text-exact.d.ts +13 -0
package/dist/tools/docx/ops/header-replace-text-exact.js +55 -0
package/dist/tools/docx/ops/index.d.ts +17 -0
package/dist/tools/docx/ops/index.js +67 -0
package/dist/tools/docx/ops/insert-image-after-text.d.ts +24 -0
package/dist/tools/docx/ops/insert-image-after-text.js +128 -0
package/dist/tools/docx/ops/insert-paragraph-after-text.d.ts +12 -0
package/dist/tools/docx/ops/insert-paragraph-after-text.js +74 -0
package/dist/tools/docx/ops/insert-table-after-text.d.ts +19 -0
package/dist/tools/docx/ops/insert-table-after-text.js +57 -0
package/dist/tools/docx/ops/replace-hyperlink-url.d.ts +12 -0
package/dist/tools/docx/ops/replace-hyperlink-url.js +37 -0
package/dist/tools/docx/ops/replace-paragraph-at-body-index.d.ts +9 -0
package/dist/tools/docx/ops/replace-paragraph-at-body-index.js +25 -0
package/dist/tools/docx/ops/replace-paragraph-text-exact.d.ts +9 -0
package/dist/tools/docx/ops/replace-paragraph-text-exact.js +21 -0
package/dist/tools/docx/ops/set-color-for-paragraph-exact.d.ts +8 -0
package/dist/tools/docx/ops/set-color-for-paragraph-exact.js +23 -0
package/dist/tools/docx/ops/set-color-for-style.d.ts +9 -0
package/dist/tools/docx/ops/set-color-for-style.js +27 -0
package/dist/tools/docx/ops/set-paragraph-style-at-body-index.d.ts +8 -0
package/dist/tools/docx/ops/set-paragraph-style-at-body-index.js +57 -0
package/dist/tools/docx/ops/table-set-cell-text.d.ts +9 -0
package/dist/tools/docx/ops/table-set-cell-text.js +72 -0
package/dist/tools/docx/parsers/image-extractor.d.ts +18 -0
package/dist/tools/docx/parsers/image-extractor.js +61 -0
package/dist/tools/docx/parsers/index.d.ts +9 -0
package/dist/tools/docx/parsers/index.js +9 -0
package/dist/tools/docx/parsers/paragraph-parser.d.ts +2 -0
package/dist/tools/docx/parsers/paragraph-parser.js +88 -0
package/dist/tools/docx/parsers/table-parser.d.ts +9 -0
package/dist/tools/docx/parsers/table-parser.js +72 -0
package/dist/tools/docx/parsers/xml-parser.d.ts +25 -0
package/dist/tools/docx/parsers/xml-parser.js +71 -0
package/dist/tools/docx/parsers/zip-reader.d.ts +23 -0
package/dist/tools/docx/parsers/zip-reader.js +52 -0
package/dist/tools/docx/read.d.ts +27 -0
package/dist/tools/docx/read.js +188 -0
package/dist/tools/docx/relationships.d.ts +22 -0
package/dist/tools/docx/relationships.js +76 -0
package/dist/tools/docx/structure.d.ts +25 -0
package/dist/tools/docx/structure.js +102 -0
package/dist/tools/docx/styled-html-parser.d.ts +23 -0
package/dist/tools/docx/styled-html-parser.js +1262 -0
package/dist/tools/docx/types.d.ts +184 -0
package/dist/tools/docx/types.js +5 -0
package/dist/tools/docx/utils/escaping.d.ts +13 -0
package/dist/tools/docx/utils/escaping.js +26 -0
package/dist/tools/docx/utils/images.d.ts +9 -0
package/dist/tools/docx/utils/images.js +26 -0
package/dist/tools/docx/utils/index.d.ts +12 -0
package/dist/tools/docx/utils/index.js +17 -0
package/dist/tools/docx/utils/markdown.d.ts +13 -0
package/dist/tools/docx/utils/markdown.js +32 -0
package/dist/tools/docx/utils/paths.d.ts +15 -0
package/dist/tools/docx/utils/paths.js +27 -0
package/dist/tools/docx/utils/versioning.d.ts +25 -0
package/dist/tools/docx/utils/versioning.js +55 -0
package/dist/tools/docx/utils.d.ts +101 -0
package/dist/tools/docx/utils.js +299 -0
package/dist/tools/docx/validate.d.ts +33 -0
package/dist/tools/docx/validate.js +49 -0
package/dist/tools/docx/validators.d.ts +13 -0
package/dist/tools/docx/validators.js +40 -0
package/dist/tools/docx/write.d.ts +17 -0
package/dist/tools/docx/write.js +88 -0
package/dist/tools/docx/zip.d.ts +21 -0
package/dist/tools/docx/zip.js +35 -0
package/dist/tools/schemas.d.ts +13 -0
package/dist/tools/schemas.js +5 -0
package/dist/types.d.ts +10 -0
package/dist/ui/contracts.d.ts +14 -0
package/dist/ui/contracts.js +18 -0
package/dist/ui/file-preview/index.html +16 -0
package/dist/ui/file-preview/preview-runtime.js +13977 -0
package/dist/ui/file-preview/shared/preview-file-types.d.ts +5 -0
package/dist/ui/file-preview/shared/preview-file-types.js +57 -0
package/dist/ui/file-preview/src/app.d.ts +4 -0
package/dist/ui/file-preview/src/app.js +800 -0
package/dist/ui/file-preview/src/components/code-viewer.d.ts +6 -0
package/dist/ui/file-preview/src/components/code-viewer.js +73 -0
package/dist/ui/file-preview/src/components/highlighting.d.ts +2 -0
package/dist/ui/file-preview/src/components/highlighting.js +54 -0
package/dist/ui/file-preview/src/components/html-renderer.d.ts +9 -0
package/dist/ui/file-preview/src/components/html-renderer.js +63 -0
package/dist/ui/file-preview/src/components/markdown-renderer.d.ts +1 -0
package/dist/ui/file-preview/src/components/markdown-renderer.js +21 -0
package/dist/ui/file-preview/src/components/toolbar.d.ts +6 -0
package/dist/ui/file-preview/src/components/toolbar.js +75 -0
package/dist/ui/file-preview/src/image-preview.d.ts +3 -0
package/dist/ui/file-preview/src/image-preview.js +21 -0
package/dist/ui/file-preview/src/main.d.ts +1 -0
package/dist/ui/file-preview/src/main.js +5 -0
package/dist/ui/file-preview/src/types.d.ts +1 -0
package/dist/ui/file-preview/src/types.js +1 -0
package/dist/ui/file-preview/styles.css +764 -0
package/dist/ui/resources.d.ts +21 -0
package/dist/ui/resources.js +72 -0
package/dist/ui/shared/escape-html.d.ts +4 -0
package/dist/ui/shared/escape-html.js +11 -0
package/dist/ui/shared/host-lifecycle.d.ts +16 -0
package/dist/ui/shared/host-lifecycle.js +35 -0
package/dist/ui/shared/rpc-client.d.ts +14 -0
package/dist/ui/shared/rpc-client.js +72 -0
package/dist/ui/shared/theme-adaptation.d.ts +10 -0
package/dist/ui/shared/theme-adaptation.js +118 -0
package/dist/ui/shared/tool-header.d.ts +9 -0
package/dist/ui/shared/tool-header.js +25 -0
package/dist/ui/shared/tool-shell.d.ts +16 -0
package/dist/ui/shared/tool-shell.js +65 -0
package/dist/ui/shared/widget-state.d.ts +28 -0
package/dist/ui/shared/widget-state.js +60 -0
package/dist/utils/capture.d.ts +1 -0
package/dist/utils/capture.js +10 -4
package/dist/utils/files/docx.d.ts +34 -0
package/dist/utils/files/docx.js +145 -0
package/dist/utils/files/text.js +9 -1
package/dist/version.d.ts +1 -1
package/dist/version.js +1 -1
package/package.json +5 -2

package/dist/tools/docx/operations/html-manipulator.js ADDED Viewed

@@ -0,0 +1,352 @@
+/**
+ * HTML DOM Manipulation
+ *
+ * DOM-based insert / append / replace / update for HTML content.
+ * Uses @xmldom/xmldom as the parser (not a browser DOMParser).
+ *
+ * IMPORTANT: All public functions use `Base64Guard` to protect base64 data URLs
+ * from corruption during xmldom parse/serialize cycles. Without this, images
+ * (which are embedded as long `data:image/...;base64,...` strings in `src` attributes)
+ * can be lost or mangled by the XML serializer.
+ *
+ * @module docx/operations/html-manipulator
+ */
+import { createRequire } from 'module';
+import { DocxError, DocxErrorCode } from '../errors.js';
+const require = createRequire(import.meta.url);
+const { DOMParser, XMLSerializer } = require('@xmldom/xmldom');
+// ─── Selector Patterns (pre-compiled) ────────────────────────────────────────
+const RE_CONTAINS = /^([a-zA-Z][a-zA-Z0-9]*)?:contains\((.+)\)$/i;
+const RE_NTH_OF_TYPE = /^([a-zA-Z][a-zA-Z0-9]*):nth-of-type\((\d+)\)$/i;
+const RE_FIRST_OF_TYPE = /^([a-zA-Z][a-zA-Z0-9]*):first-of-type$/i;
+const RE_LAST_OF_TYPE = /^([a-zA-Z][a-zA-Z0-9]*):last-of-type$/i;
+// ─── Base64 Data URL Protection ──────────────────────────────────────────────
+/**
+ * Protects base64 data URLs from corruption during xmldom parse/serialize.
+ *
+ * Problem: xmldom's DOMParser + XMLSerializer can mangle very long attribute
+ * values (base64 image data). Symptoms range from silent truncation to dropped
+ * `<img>` elements.
+ *
+ * Solution: Before DOM operations, replace all `data:…` URLs in `src` attributes
+ * with short placeholder URNs. After serialization, restore the originals.
+ * This keeps the DOM tree lightweight and avoids serializer issues.
+ */
+class Base64Guard {
+    constructor() {
+        this.store = [];
+    }
+    /** Replace all data: URLs in src attributes with short placeholders. */
+    protect(html) {
+        if (!html.includes('data:'))
+            return html; // Fast path: no data URLs
+        return html.replace(/\bsrc="(data:[^"]+)"/g, (_, dataUrl) => {
+            const index = this.store.length;
+            this.store.push(dataUrl);
+            return `src="urn:b64:${index}"`;
+        });
+    }
+    /** Restore original data: URLs from placeholders. */
+    restore(html) {
+        if (this.store.length === 0)
+            return html; // Fast path: nothing to restore
+        let result = html;
+        // Use split/join to avoid $-pattern issues in String.replace
+        for (let i = 0; i < this.store.length; i++) {
+            result = result.split(`urn:b64:${i}`).join(this.store[i]);
+        }
+        return result;
+    }
+}
+// ─── Internal Helpers ────────────────────────────────────────────────────────
+/** Re-throw any non-DocxError as a DocxError. */
+function rethrowAsDocxError(error, message, context) {
+    if (error instanceof DocxError)
+        throw error;
+    throw new DocxError(`${message}: ${error instanceof Error ? error.message : String(error)}`, DocxErrorCode.OPERATION_FAILED, context);
+}
+/**
+ * Parse HTML string into a DOM Document.
+ *
+ * @xmldom/xmldom is an XML parser — it does NOT auto-create `<html>/<body>` wrappers
+ * like a browser would. We always ensure a proper structure so that
+ * `getElementsByTagName('body')` works reliably.
+ */
+function parseHtml(html) {
+    try {
+        let htmlToParse = html;
+        const lower = html.toLowerCase();
+        if (!lower.includes('<body'))
+            htmlToParse = `<html><body>${html}</body></html>`;
+        else if (!lower.includes('<html'))
+            htmlToParse = `<html>${html}</html>`;
+        const doc = new DOMParser().parseFromString(htmlToParse, 'text/html');
+        const parserErrors = doc.getElementsByTagName('parsererror');
+        if (parserErrors.length > 0) {
+            throw new DocxError('Failed to parse HTML: invalid structure', DocxErrorCode.OPERATION_FAILED, { htmlSnippet: html.substring(0, 100) });
+        }
+        return doc;
+    }
+    catch (error) {
+        rethrowAsDocxError(error, 'Failed to parse HTML', { htmlSnippet: html.substring(0, 100) });
+    }
+}
+/**
+ * Serialize a DOM Document back to an HTML string.
+ * Returns only the inner content of `<body>` (no wrapper tags) because we
+ * added those in `parseHtml` for xmldom compatibility.
+ */
+function serializeHtml(doc) {
+    try {
+        const serializer = new XMLSerializer();
+        const body = doc.getElementsByTagName('body')[0];
+        if (body) {
+            let content = '';
+            for (let i = 0; i < body.childNodes.length; i++) {
+                content += serializer.serializeToString(body.childNodes[i]);
+            }
+            return content;
+        }
+        return doc.documentElement ? serializer.serializeToString(doc.documentElement) : '';
+    }
+    catch (error) {
+        throw new DocxError(`Failed to serialize HTML: ${error instanceof Error ? error.message : String(error)}`, DocxErrorCode.OPERATION_FAILED);
+    }
+}
+/** Get the root element (body or documentElement) for querying. */
+function getRootElement(doc) {
+    return doc.getElementsByTagName('body')[0] || doc.documentElement;
+}
+/** Clone nodes from one document into another. */
+function cloneNodesToDocument(sourceNodes, targetDoc) {
+    const nodes = [];
+    for (let i = 0; i < sourceNodes.length; i++) {
+        nodes.push(targetDoc.importNode(sourceNodes[i], true));
+    }
+    return nodes;
+}
+// ─── CSS-like Selector Engine ────────────────────────────────────────────────
+/**
+ * Find elements using an extended CSS-like selector.
+ *
+ * Supported:
+ *   `#id`, `.class`, `tag`,
+ *   `tag:contains(text)`, `:contains(text)`,
+ *   `tag:nth-of-type(N)`, `tag:first-of-type`, `tag:last-of-type`
+ */
+function querySelectorAll(doc, selector) {
+    const s = selector?.trim();
+    if (!s)
+        return [];
+    const root = getRootElement(doc);
+    const elements = [];
+    try {
+        // #id
+        if (s.startsWith('#')) {
+            const el = doc.getElementById(s.substring(1));
+            if (el)
+                elements.push(el);
+            return elements;
+        }
+        // .class
+        if (s.startsWith('.')) {
+            const found = root.getElementsByClassName(s.substring(1));
+            for (let i = 0; i < found.length; i++)
+                elements.push(found[i]);
+            return elements;
+        }
+        // tag:contains(text)
+        const containsMatch = s.match(RE_CONTAINS);
+        if (containsMatch) {
+            const tag = containsMatch[1] || '*';
+            const needle = containsMatch[2].trim().toLowerCase();
+            const candidates = root.getElementsByTagName(tag);
+            for (let i = 0; i < candidates.length; i++) {
+                if ((candidates[i].textContent || '').toLowerCase().includes(needle)) {
+                    elements.push(candidates[i]);
+                }
+            }
+            return elements;
+        }
+        // tag:nth-of-type(N)
+        const nthMatch = s.match(RE_NTH_OF_TYPE);
+        if (nthMatch) {
+            const n = parseInt(nthMatch[2], 10);
+            const found = root.getElementsByTagName(nthMatch[1]);
+            if (n >= 1 && n <= found.length)
+                elements.push(found[n - 1]);
+            return elements;
+        }
+        // tag:first-of-type
+        const firstMatch = s.match(RE_FIRST_OF_TYPE);
+        if (firstMatch) {
+            const found = root.getElementsByTagName(firstMatch[1]);
+            if (found.length > 0)
+                elements.push(found[0]);
+            return elements;
+        }
+        // tag:last-of-type
+        const lastMatch = s.match(RE_LAST_OF_TYPE);
+        if (lastMatch) {
+            const found = root.getElementsByTagName(lastMatch[1]);
+            if (found.length > 0)
+                elements.push(found[found.length - 1]);
+            return elements;
+        }
+        // Plain tag name (fallback)
+        const found = root.getElementsByTagName(s);
+        for (let i = 0; i < found.length; i++)
+            elements.push(found[i]);
+    }
+    catch (error) {
+        throw new DocxError(`Failed to query selector "${selector}": ${error instanceof Error ? error.message : String(error)}`, DocxErrorCode.OPERATION_FAILED);
+    }
+    return elements;
+}
+// ─── DOM Position Helper ─────────────────────────────────────────────────────
+/** Insert `node` relative to `target` at the given `position`. */
+function insertAtPosition(node, target, position) {
+    switch (position) {
+        case 'before':
+            target.parentNode?.insertBefore(node, target);
+            break;
+        case 'inside':
+            target.appendChild(node);
+            break;
+        case 'after':
+        default:
+            if (target.nextSibling)
+                target.parentNode?.insertBefore(node, target.nextSibling);
+            else
+                target.parentNode?.appendChild(node);
+            break;
+    }
+}
+// ─── Public Operations ───────────────────────────────────────────────────────
+// All public functions use Base64Guard to protect image data URLs from
+// corruption during the xmldom parse → manipulate → serialize cycle.
+/** Append HTML content to the end of the document body. */
+export function appendHtml(html, content) {
+    if (!content?.trim())
+        return html;
+    const guard = new Base64Guard();
+    const safeHtml = guard.protect(html);
+    const safeContent = guard.protect(content);
+    try {
+        const doc = parseHtml(safeHtml);
+        const body = doc.getElementsByTagName('body')[0];
+        if (!body)
+            return html.trim() + '\n' + content.trim();
+        const contentDoc = parseHtml(safeContent);
+        const contentRoot = getRootElement(contentDoc);
+        for (const node of cloneNodesToDocument(contentRoot.childNodes, doc)) {
+            body.appendChild(node);
+        }
+        return guard.restore(serializeHtml(doc));
+    }
+    catch (error) {
+        rethrowAsDocxError(error, 'Failed to append HTML');
+    }
+}
+/**
+ * Insert HTML content at a specific position relative to a selector target.
+ * If no selector is given, appends to the root element.
+ */
+export function insertHtml(html, content, selector, position = 'after') {
+    if (!content?.trim())
+        return html;
+    const guard = new Base64Guard();
+    const safeHtml = guard.protect(html);
+    const safeContent = guard.protect(content);
+    try {
+        const doc = parseHtml(safeHtml);
+        const root = getRootElement(doc);
+        const contentDoc = parseHtml(safeContent);
+        const contentRoot = getRootElement(contentDoc);
+        const nodesToInsert = cloneNodesToDocument(contentRoot.childNodes, doc);
+        if (!selector) {
+            for (const node of nodesToInsert)
+                root.appendChild(node);
+            return guard.restore(serializeHtml(doc));
+        }
+        const targets = querySelectorAll(doc, selector);
+        if (targets.length === 0) {
+            throw new DocxError(`Target element not found for selector: "${selector}"`, DocxErrorCode.OPERATION_FAILED, { selector });
+        }
+        // Insert at FIRST match only to prevent duplication
+        const target = targets[0];
+        for (const node of nodesToInsert) {
+            insertAtPosition(node.cloneNode(true), target, position);
+        }
+        return guard.restore(serializeHtml(doc));
+    }
+    catch (error) {
+        rethrowAsDocxError(error, 'Failed to insert HTML', { selector, position });
+    }
+}
+/** Replace matched elements with new HTML content. */
+export function replaceHtml(html, selector, content, replaceAll = false) {
+    if (!selector?.trim())
+        return html;
+    const guard = new Base64Guard();
+    const safeHtml = guard.protect(html);
+    const safeContent = guard.protect(content);
+    try {
+        const doc = parseHtml(safeHtml);
+        const targets = querySelectorAll(doc, selector);
+        if (targets.length === 0) {
+            throw new DocxError(`Target element not found for selector: "${selector}"`, DocxErrorCode.OPERATION_FAILED, { selector });
+        }
+        const contentDoc = parseHtml(safeContent);
+        const contentRoot = getRootElement(contentDoc);
+        const replaceNodes = cloneNodesToDocument(contentRoot.childNodes, doc);
+        for (const target of replaceAll ? targets : [targets[0]]) {
+            const parent = target.parentNode;
+            if (!parent)
+                continue;
+            for (const node of replaceNodes)
+                parent.insertBefore(node.cloneNode(true), target);
+            parent.removeChild(target);
+        }
+        return guard.restore(serializeHtml(doc));
+    }
+    catch (error) {
+        rethrowAsDocxError(error, 'Failed to replace HTML', { selector, replaceAll });
+    }
+}
+/** Update matched elements' content and/or attributes. */
+export function updateHtml(html, selector, content, attributes, updateAll = false) {
+    if (!selector?.trim())
+        return html;
+    const guard = new Base64Guard();
+    const safeHtml = guard.protect(html);
+    const safeContent = content !== undefined ? guard.protect(content) : undefined;
+    try {
+        const doc = parseHtml(safeHtml);
+        const targets = querySelectorAll(doc, selector);
+        if (targets.length === 0) {
+            throw new DocxError(`Target element not found for selector: "${selector}"`, DocxErrorCode.OPERATION_FAILED, { selector });
+        }
+        for (const target of updateAll ? targets : [targets[0]]) {
+            // Replace innerHTML via DOM methods (xmldom doesn't support .innerHTML setter)
+            if (safeContent !== undefined) {
+                while (target.firstChild)
+                    target.removeChild(target.firstChild);
+                const contentDoc = parseHtml(safeContent);
+                const contentRoot = getRootElement(contentDoc);
+                for (const child of cloneNodesToDocument(contentRoot.childNodes, doc)) {
+                    target.appendChild(child);
+                }
+            }
+            if (attributes) {
+                for (const [key, value] of Object.entries(attributes)) {
+                    target.setAttribute(key, value);
+                }
+            }
+        }
+        return guard.restore(serializeHtml(doc));
+    }
+    catch (error) {
+        rethrowAsDocxError(error, 'Failed to update HTML', { selector, updateAll });
+    }
+}

package/dist/tools/docx/operations/index.d.ts ADDED Viewed

@@ -0,0 +1,14 @@
+/**
+ * DOCX Editing Operations
+ *
+ * Reads DOCX → HTML (via direct XML parser or mammoth fallback),
+ * applies a sequence of operations to the HTML DOM,
+ * then converts the modified HTML → DOCX (html-to-docx).
+ *
+ * @module docx/operations
+ */
+import type { DocxEditOptions, DocxOperation } from '../types.js';
+/**
+ * Apply a sequence of edit operations to a DOCX file and return the modified DOCX as a Buffer.
+ */
+export declare function editDocxWithOperations(docxPath: string, operations: DocxOperation[], options?: DocxEditOptions): Promise<Buffer>;

package/dist/tools/docx/operations/index.js ADDED Viewed

@@ -0,0 +1,61 @@
+/**
+ * DOCX Editing Operations
+ *
+ * Reads DOCX → HTML (via direct XML parser or mammoth fallback),
+ * applies a sequence of operations to the HTML DOM,
+ * then converts the modified HTML → DOCX (html-to-docx).
+ *
+ * @module docx/operations
+ */
+import path from 'path';
+import { DocxError, DocxErrorCode, withErrorContext } from '../errors.js';
+import { parseDocxToHtml } from '../html.js';
+import { createDocxFromHtml } from '../builders/html-builder.js';
+import { DEFAULT_CONVERSION_OPTIONS } from '../constants.js';
+import { DocxOperationSchema } from '../../schemas.js';
+import { validateDocxPath, validateOperations } from '../validators.js';
+import { applyOperation } from './handlers/index.js';
+import { preprocessOperations } from './preprocessor.js';
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Apply a sequence of edit operations to a DOCX file and return the modified DOCX as a Buffer.
+ */
+export async function editDocxWithOperations(docxPath, operations, options = {}) {
+    return withErrorContext(async () => {
+        validateDocxPath(docxPath);
+        validateOperations(operations);
+        const normalizedPath = docxPath.trim();
+        const baseDir = options.baseDir ?? path.dirname(normalizedPath);
+        const parseOptions = {
+            includeImages: options.includeImages ?? DEFAULT_CONVERSION_OPTIONS.includeImages,
+            preserveFormatting: options.preserveFormatting ?? DEFAULT_CONVERSION_OPTIONS.preserveFormatting,
+            ...(options.styleMap && { styleMap: options.styleMap }),
+        };
+        // Read DOCX → HTML
+        const docxResult = await parseDocxToHtml(normalizedPath, parseOptions);
+        let html = docxResult.html;
+        const { documentDefaults } = docxResult;
+        // Preprocess operations (e.g., convert local image paths to base64)
+        const preprocessedOps = await preprocessOperations(operations, baseDir);
+        // Apply each operation sequentially
+        for (let i = 0; i < preprocessedOps.length; i++) {
+            const op = preprocessedOps[i];
+            try {
+                const validatedOp = DocxOperationSchema.parse(op);
+                html = applyOperation(html, validatedOp, baseDir);
+            }
+            catch (error) {
+                if (error instanceof DocxError)
+                    throw error;
+                // Zod validation errors
+                if (error instanceof Error && 'issues' in error) {
+                    throw new DocxError(`Invalid operation at index ${i}: ${error.message}`, DocxErrorCode.OPERATION_FAILED, { path: normalizedPath, operationIndex: i, operation: op, validationError: error });
+                }
+                // Other errors
+                throw new DocxError(`Failed to apply operation at index ${i}: ${error instanceof Error ? error.message : String(error)}`, DocxErrorCode.OPERATION_FAILED, { path: normalizedPath, operationIndex: i, operation: op });
+            }
+        }
+        // HTML → DOCX, preserving the original document's default styles
+        return await createDocxFromHtml(html, { baseDir, documentDefaults });
+    }, DocxErrorCode.DOCX_EDIT_FAILED, { path: docxPath, operationCount: operations.length });
+}

package/dist/tools/docx/operations/operation-handlers.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+import type { DocxStructure } from '../types.js';
+import type { DocxOperation } from '../types.js';
+export declare function applyOperationToStructure(structure: DocxStructure, op: DocxOperation, baseDir: string): Promise<void>;

package/dist/tools/docx/operations/operation-handlers.js ADDED Viewed

@@ -0,0 +1,67 @@
+import { DocxError, DocxErrorCode } from '../errors.js';
+import { createDocxFromMarkdown } from '../builders/markdown-builder.js';
+import { parseDocxStructure } from '../structure.js';
+import { buildMarkdownTableFromRows, prepareImageForDocx, createImageRun, } from '../utils.js';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+// @ts-ignore
+import * as docx from 'docx';
+const { Paragraph, AlignmentType } = docx;
+export async function applyOperationToStructure(structure, op, baseDir) {
+    switch (op.type) {
+        case 'replaceText':
+            throw new DocxError('replaceText should use XML manipulation', DocxErrorCode.UNSUPPORTED_OPERATION);
+        case 'appendMarkdown':
+            await handleAppendMarkdown(structure, op, baseDir);
+            break;
+        case 'insertTable':
+            await handleInsertTable(structure, op);
+            break;
+        case 'insertImage':
+            await handleInsertImage(structure, op, baseDir);
+            break;
+        default:
+            throw new DocxError(`Unknown operation: ${op.type}`, DocxErrorCode.UNKNOWN_OPERATION);
+    }
+}
+async function handleAppendMarkdown(structure, op, baseDir) {
+    if (!op.markdown?.trim())
+        return;
+    const appendBuffer = await createDocxFromMarkdown(op.markdown, { baseDir });
+    const appendStructure = await parseDocxStructure(appendBuffer);
+    structure.elements.push(...appendStructure.elements);
+    for (const [relId, imgBuffer] of appendStructure.images.entries()) {
+        structure.images.set(relId, imgBuffer);
+    }
+    for (const [relId, rel] of appendStructure.relationships.entries()) {
+        structure.relationships.set(relId, rel);
+    }
+}
+async function handleInsertTable(structure, op) {
+    let tableMarkdown = op.markdownTable;
+    if (!tableMarkdown && op.rows?.length) {
+        tableMarkdown = buildMarkdownTableFromRows(op.rows);
+    }
+    if (!tableMarkdown?.trim())
+        return;
+    const tableBuffer = await createDocxFromMarkdown(tableMarkdown, {});
+    const tableStructure = await parseDocxStructure(tableBuffer);
+    const tableElement = tableStructure.elements.find(el => el.type === 'table');
+    if (tableElement) {
+        structure.elements.push(tableElement);
+    }
+    else {
+        structure.elements.push(...tableStructure.elements);
+    }
+}
+async function handleInsertImage(structure, op, baseDir) {
+    if (!op.imagePath?.trim())
+        return;
+    const imageData = await prepareImageForDocx(op.imagePath, op.altText || '', baseDir);
+    const imageRun = createImageRun(imageData);
+    const paragraph = new Paragraph({
+        children: [imageRun],
+        alignment: AlignmentType.CENTER,
+    });
+    structure.elements.push({ type: 'paragraph', content: paragraph });
+}

package/dist/tools/docx/operations/preprocessor.d.ts ADDED Viewed

@@ -0,0 +1,14 @@
+/**
+ * DOCX Operation Preprocessor
+ *
+ * Preprocesses operations before execution (e.g., converting local image paths to base64).
+ * Follows Single Responsibility Principle — only handles operation preprocessing.
+ *
+ * @module docx/operations/preprocessor
+ */
+import type { DocxOperation } from '../types.js';
+/**
+ * Resolve local image paths to base64 data URLs before operations are applied.
+ * html-to-docx cannot handle `file://` URLs — only base64 data URLs and HTTP URLs work.
+ */
+export declare function preprocessOperations(operations: DocxOperation[], baseDir: string): Promise<DocxOperation[]>;

package/dist/tools/docx/operations/preprocessor.js ADDED Viewed

@@ -0,0 +1,44 @@
+/**
+ * DOCX Operation Preprocessor
+ *
+ * Preprocesses operations before execution (e.g., converting local image paths to base64).
+ * Follows Single Responsibility Principle — only handles operation preprocessing.
+ *
+ * @module docx/operations/preprocessor
+ */
+import fs from 'fs/promises';
+import { DocxError, DocxErrorCode } from '../errors.js';
+import { isDataUrl, isUrl, resolveImagePath } from '../utils/paths.js';
+import { getMimeType } from '../utils/images.js';
+/**
+ * Resolve local image paths to base64 data URLs before operations are applied.
+ * html-to-docx cannot handle `file://` URLs — only base64 data URLs and HTTP URLs work.
+ */
+export async function preprocessOperations(operations, baseDir) {
+    const processed = [];
+    for (const op of operations) {
+        if (op.type !== 'insertImage') {
+            processed.push(op);
+            continue;
+        }
+        const imgOp = op;
+        const trimmedPath = imgOp.imagePath?.trim();
+        if (!trimmedPath || isDataUrl(trimmedPath) || isUrl(trimmedPath)) {
+            processed.push(op);
+            continue;
+        }
+        const resolvedPath = resolveImagePath(trimmedPath, baseDir);
+        try {
+            const imageBuffer = await fs.readFile(resolvedPath);
+            const mimeType = getMimeType(resolvedPath) || 'image/png';
+            processed.push({
+                ...imgOp,
+                imagePath: `data:${mimeType};base64,${imageBuffer.toString('base64')}`,
+            });
+        }
+        catch (err) {
+            throw new DocxError(`Failed to read image file: ${trimmedPath} (resolved: ${resolvedPath}). ${err instanceof Error ? err.message : String(err)}`, DocxErrorCode.INVALID_IMAGE_FILE, { imagePath: trimmedPath, resolvedPath, baseDir });
+        }
+    }
+    return processed;
+}

package/dist/tools/docx/operations/xml-replacer.d.ts ADDED Viewed

@@ -0,0 +1,9 @@
+/**
+ * XML Text Replacer
+ * Handles direct XML manipulation for text replacements (preserves formatting)
+ */
+/**
+ * Replace text directly in DOCX XML without converting to markdown
+ * This preserves all formatting, tables, styles, etc.
+ */
+export declare function replaceTextInDocxXml(docxPath: string, searchText: string, replaceText: string): Promise<Buffer>;

package/dist/tools/docx/operations/xml-replacer.js ADDED Viewed

@@ -0,0 +1,35 @@
+/**
+ * XML Text Replacer
+ * Handles direct XML manipulation for text replacements (preserves formatting)
+ */
+import fs from 'fs/promises';
+import JSZip from 'jszip';
+import { DocxError, DocxErrorCode, withErrorContext } from '../errors.js';
+/**
+ * Replace text directly in DOCX XML without converting to markdown
+ * This preserves all formatting, tables, styles, etc.
+ */
+export async function replaceTextInDocxXml(docxPath, searchText, replaceText) {
+    return withErrorContext(async () => {
+        const docxBuffer = await fs.readFile(docxPath);
+        const zip = await JSZip.loadAsync(docxBuffer);
+        const documentXml = await zip.file('word/document.xml')?.async('string');
+        if (!documentXml) {
+            throw new DocxError('Invalid DOCX file: word/document.xml not found', DocxErrorCode.INVALID_DOCX, { path: docxPath });
+        }
+        // Escape XML special characters
+        const escapeXml = (str) => str
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&apos;');
+        const escapedSearch = escapeXml(searchText);
+        const escapedReplace = escapeXml(replaceText);
+        // Simple replacement in text nodes
+        const modifiedXml = documentXml.replace(new RegExp(escapedSearch, 'g'), escapedReplace);
+        zip.file('word/document.xml', modifiedXml);
+        const arrayBuffer = await zip.generateAsync({ type: 'uint8array' });
+        return Buffer.from(arrayBuffer);
+    }, DocxErrorCode.DOCX_XML_REPLACE_FAILED, { searchText, replaceText });
+}

package/dist/tools/docx/operations.d.ts ADDED Viewed

@@ -0,0 +1,13 @@
+/**
+ * DOCX Creation and Editing Operations
+ *
+ * Main entry point for DOCX operations. This module provides:
+ * - Creating DOCX files from markdown
+ * - Editing existing DOCX files via operations
+ *
+ * @module docx/operations
+ */
+import { createDocxFromMarkdown } from './builders/markdown-builder.js';
+import { editDocxWithOperations } from './operations/index.js';
+export type { DocxBuildOptions, DocxEditOptions, DocxOperation, DocxReplaceTextOperation, DocxAppendMarkdownOperation, DocxInsertTableOperation, DocxInsertImageOperation, } from './types.js';
+export { createDocxFromMarkdown, editDocxWithOperations };

package/dist/tools/docx/operations.js ADDED Viewed

@@ -0,0 +1,13 @@
+/**
+ * DOCX Creation and Editing Operations
+ *
+ * Main entry point for DOCX operations. This module provides:
+ * - Creating DOCX files from markdown
+ * - Editing existing DOCX files via operations
+ *
+ * @module docx/operations
+ */
+import { createDocxFromMarkdown } from './builders/markdown-builder.js';
+import { editDocxWithOperations } from './operations/index.js';
+// Re-export main functions
+export { createDocxFromMarkdown, editDocxWithOperations };

package/dist/tools/docx/ops/delete-paragraph-at-body-index.d.ts ADDED Viewed

@@ -0,0 +1,11 @@
+/**
+ * Op: delete_paragraph_at_body_index
+ *
+ * Remove the w:p element at the given bodyChildIndex.
+ * Skips if the child is not a w:p.
+ *
+ * NOTE: This is a structural op — it decreases bodyChildCount by 1.
+ * The orchestrator must account for this when validating invariants.
+ */
+import type { DeleteParagraphAtBodyIndexOp, OpResult } from '../types.js';
+export declare function applyDeleteParagraphAtBodyIndex(body: Element, op: DeleteParagraphAtBodyIndexOp): OpResult;

package/dist/tools/docx/ops/delete-paragraph-at-body-index.js ADDED Viewed

@@ -0,0 +1,23 @@
+/**
+ * Op: delete_paragraph_at_body_index
+ *
+ * Remove the w:p element at the given bodyChildIndex.
+ * Skips if the child is not a w:p.
+ *
+ * NOTE: This is a structural op — it decreases bodyChildCount by 1.
+ * The orchestrator must account for this when validating invariants.
+ */
+import { getBodyChildren } from '../dom.js';
+export function applyDeleteParagraphAtBodyIndex(body, op) {
+    const children = getBodyChildren(body);
+    const idx = op.bodyChildIndex;
+    if (idx < 0 || idx >= children.length) {
+        return { op, status: 'skipped', matched: 0, reason: 'index_out_of_range' };
+    }
+    const child = children[idx];
+    if (child.nodeName !== 'w:p') {
+        return { op, status: 'skipped', matched: 0, reason: 'not_a_paragraph' };
+    }
+    body.removeChild(child);
+    return { op, status: 'applied', matched: 1 };
+}