@wonderwhy-er/desktop-commander 0.2.36 → 0.2.37

package/README.md

@@ -2,6 +2,7 @@
 ### Search, update, manage files and run terminal commands with AI
 
 [![npm downloads](https://img.shields.io/npm/dw/@wonderwhy-er/desktop-commander)](https://www.npmjs.com/package/@wonderwhy-er/desktop-commander)
+[![AgentAudit Verified](https://agentaudit.dev/api/badge/desktop-commander)](https://agentaudit.dev/skills/desktop-commander)
 [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/wonderwhy-er/DesktopCommanderMCP)](https://archestra.ai/mcp-catalog/wonderwhy-er__desktopcommandermcp)
 [![smithery badge](https://smithery.ai/badge/@wonderwhy-er/desktop-commander)](https://smithery.ai/server/@wonderwhy-er/desktop-commander)
 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow.svg)](https://www.buymeacoffee.com/wonderwhyer)

package/dist/remote-device/remote-channel.d.ts

@@ -36,10 +36,15 @@ export declare class RemoteChannel {
         id: any;
         device_name: any;
     } | null>;
-    updateDevice(deviceId: string, updates: any): Promise<import("@supabase/postgrest-js").PostgrestSingleResponse<null>>;
-    createDevice(deviceData: DeviceData): Promise<import("@supabase/postgrest-js").PostgrestSingleResponse<any>>;
+    updateDevice(deviceId: string, updates: any): Promise<{
+        data: any[] | null;
+        error: import("@supabase/postgrest-js").PostgrestError | null;
+    }>;
+    createDevice(deviceData: DeviceData): Promise<{
+        data: any;
+        error: null;
+    }>;
     registerDevice(capabilities: any, currentDeviceId: string | undefined, deviceName: string, onToolCall: (payload: any) => void): Promise<void>;
-    subscribe(deviceId: string, onToolCall: (payload: any) => void): Promise<void>;
     /**
      * Create and subscribe to the channel.
      * This is used for both initial subscription and recreation after socket reconnects.

package/dist/remote-device/remote-channel.js

@@ -28,14 +28,26 @@ export class RemoteChannel {
             access_token: session.access_token,
             refresh_token: session.refresh_token || ''
         });
+        if (error) {
+            console.error('[DEBUG] Failed to set session:', error.message);
+            await captureRemote('remote_channel_set_session_error', { error });
+            return { error };
+        }
         // Get user info
         const { data: { user }, error: userError } = await this.client.auth.getUser();
         if (userError) {
-            console.debug('[DEBUG] Failed to get user:', userError.message);
+            console.error('[DEBUG] Failed to get user:', userError.message);
+            await captureRemote('remote_channel_get_user_error', { error: userError });
             throw userError;
         }
+        if (!user) {
+            const noUserError = new Error('No user returned after setSession');
+            console.error('[DEBUG] No user returned:', noUserError.message);
+            await captureRemote('remote_channel_get_user_empty', {});
+            throw noUserError;
+        }
         this._user = user;
-        console.debug('[DEBUG] Session set successfully, user:', user?.email);
+        console.debug('[DEBUG] Session set successfully, user:', user.email);
         return { error };
     }
     async getSession() {
@@ -52,26 +64,45 @@ export class RemoteChannel {
             .eq('id', deviceId)
             .eq('user_id', this.user?.id)
             .maybeSingle();
-        if (error)
+        if (error) {
+            console.error('[DEBUG] Failed to find device:', error.message);
+            await captureRemote('remote_channel_find_device_error', { error });
             throw error;
+        }
         return data;
     }
     async updateDevice(deviceId, updates) {
         if (!this.client)
             throw new Error('Client not initialized');
-        return await this.client
+        const { data, error } = await this.client
             .from('mcp_devices')
             .update(updates)
-            .eq('id', deviceId);
+            .eq('id', deviceId)
+            .select();
+        if (error) {
+            console.error('[DEBUG] Failed to update device:', error.message);
+            await captureRemote('remote_channel_update_device_error', { error });
+        }
+        else {
+            console.debug('[DEBUG] Device updated successfully');
+        }
+        return { data, error };
     }
     async createDevice(deviceData) {
         if (!this.client)
             throw new Error('Client not initialized');
-        return await this.client
+        const { data, error } = await this.client
             .from('mcp_devices')
             .insert(deviceData)
             .select()
             .single();
+        if (error) {
+            console.error('[DEBUG] Failed to create device:', error.message);
+            await captureRemote('remote_channel_create_device_error', { error });
+            throw error;
+        }
+        console.debug('[DEBUG] Device created successfully');
+        return { data, error };
     }
     async registerDevice(capabilities, currentDeviceId, deviceName, onToolCall) {
         console.debug('[DEBUG] RemoteChannel.registerDevice() called, deviceId:', currentDeviceId);
@@ -95,7 +126,10 @@ export class RemoteChannel {
             console.debug(`⏳ Subscribing to tool call channel...`);
             // Create and subscribe to the channel
             console.debug('[DEBUG] Calling createChannel()');
-            await this.createChannel();
+            // ! Ignore silently in Inialization to reconnect after
+            await this.createChannel().catch((error) => {
+                console.debug('[DEBUG] Failed to create channel, will retry after socket reconnect', error);
+            });
         }
         else {
             console.error(`   - ❌ Device not found: ${currentDeviceId}`);
@@ -103,16 +137,6 @@ export class RemoteChannel {
             throw new Error(`Device not found: ${currentDeviceId}`);
         }
     }
-    async subscribe(deviceId, onToolCall) {
-        if (!this.client)
-            throw new Error('Client not initialized');
-        // Store parameters for channel recreation
-        this.deviceId = deviceId;
-        this.onToolCall = onToolCall;
-        console.debug(`⏳ Subscribing to tool call channel...`);
-        // Create and subscribe to the channel
-        await this.createChannel();
-    }
     /**
      * Create and subscribe to the channel.
      * This is used for both initial subscription and recreation after socket reconnects.
@@ -156,7 +180,7 @@ export class RemoteChannel {
                     reject(err || new Error('Failed to initialize tool call channel subscription'));
                 }
                 else if (status === 'TIMED_OUT') {
-                    console.error('⏱️ Channel subscription timed out');
+                    console.error('⏱️ Channel subscription timed out, Reconnecting...');
                     this.setOnlineStatus(this.deviceId, 'offline');
                     captureRemote('remote_channel_subscription_timeout', {}).catch(() => { });
                     reject(new Error('Tool call channel subscription timed out'));
@@ -213,10 +237,17 @@ export class RemoteChannel {
     async markCallExecuting(callId) {
         if (!this.client)
             throw new Error('Client not initialized');
-        await this.client
+        const { error } = await this.client
             .from('mcp_remote_calls')
             .update({ status: 'executing' })
             .eq('id', callId);
+        if (error) {
+            console.error('[DEBUG] Failed to mark call executing:', error.message);
+            await captureRemote('remote_channel_mark_call_executing_error', { error });
+        }
+        else {
+            console.debug('[DEBUG] Call marked executing:', callId);
+        }
     }
     async updateCallResult(callId, status, result = null, errorMessage = null) {
         if (!this.client)
@@ -229,19 +260,31 @@ export class RemoteChannel {
             updateData.result = result;
         if (errorMessage !== null)
             updateData.error_message = errorMessage;
-        await this.client
+        console.debug('[DEBUG] Updating call result:', updateData);
+        const { data, error } = await this.client
             .from('mcp_remote_calls')
             .update(updateData)
             .eq('id', callId);
+        if (error) {
+            console.error('[DEBUG] Failed to update call result:', error.message);
+            await captureRemote('remote_channel_update_call_result_error', { error });
+        }
+        else {
+            console.debug('[DEBUG] Call result updated successfully:', data);
+        }
     }
     async updateHeartbeat(deviceId) {
         if (!this.client)
             return;
         try {
-            await this.client
+            const { error } = await this.client
                 .from('mcp_devices')
                 .update({ last_seen: new Date().toISOString() })
                 .eq('id', deviceId);
+            if (error) {
+                console.error('[DEBUG] Heartbeat update failed:', error.message);
+                await captureRemote('remote_channel_heartbeat_error', { error });
+            }
             // console.log(`🔌 Heartbeat sent for device: ${deviceId}`);
         }
         catch (error) {
@@ -283,12 +326,16 @@ export class RemoteChannel {
             .update({ status: status, last_seen: new Date().toISOString() })
             .eq('id', deviceId);
         if (error) {
+            console.error(`[DEBUG] Failed to set status ${status}:`, error.message);
             if (status == "online") {
                 console.error('Failed to update device status:', error.message);
             }
             await captureRemote('remote_channel_status_update_error', { error, status });
             return;
         }
+        else {
+            console.debug(`[DEBUG] Device status set to ${status}`);
+        }
         // console.log(status === 'online' ? `🔌 Device marked as ${status}` : `❌ Device marked as ${status}`);
     }
     async setOffline(deviceId) {

package/dist/search-manager.d.ts

@@ -97,6 +97,19 @@ export interface SearchSessionOptions {
      * Find all Excel files in a directory recursively
      */
     private findExcelFiles;
+    /**
+     * Determine if DOCX search should be included based on context
+     */
+    private shouldIncludeDocxSearch;
+    /**
+     * Search DOCX files for content matches
+     * Extracts <w:t> text from document.xml and searches it
+     */
+    private searchDocxFiles;
+    /**
+     * Find all DOCX files in a directory recursively
+     */
+    private findDocxFiles;
     /**
      * Extract context around a match for display (show surrounding text)
      */

package/dist/search-manager.js

@@ -5,6 +5,7 @@ import { validatePath } from './tools/filesystem.js';
 import { capture } from './utils/capture.js';
 import { getRipgrepPath } from './utils/ripgrep-resolver.js';
 import { isExcelFile } from './utils/files/index.js';
+import PizZip from 'pizzip';
 /**
  * Search Session Manager - handles ripgrep processes like terminal sessions
  * Supports both file search and content search with progressive results
@@ -105,6 +106,19 @@ import { isExcelFile } from './utils/files/index.js';
                 capture('excel_search_error', { error: err instanceof Error ? err.message : String(err) });
             });
         }
+        // For content searches, also search DOCX files
+        const shouldSearchDocx = options.searchType === 'content' &&
+            this.shouldIncludeDocxSearch(options.filePattern, validPath);
+        if (shouldSearchDocx) {
+            this.searchDocxFiles(validPath, options.pattern, options.ignoreCase !== false, options.maxResults, options.filePattern).then(docxResults => {
+                for (const result of docxResults) {
+                    session.results.push(result);
+                    session.totalMatches++;
+                }
+            }).catch((err) => {
+                capture('docx_search_error', { error: err instanceof Error ? err.message : String(err) });
+            });
+        }
         // Wait for first chunk of data or early completion instead of fixed delay
         // Excel search runs in background and results are merged via readSearchResults
         const firstChunk = new Promise(resolve => {
@@ -349,6 +363,138 @@ import { isExcelFile } from './utils/files/index.js';
         }
         return excelFiles;
     }
+    /**
+     * Determine if DOCX search should be included based on context
+     */
+    shouldIncludeDocxSearch(filePattern, rootPath) {
+        const docxExtensions = ['.docx'];
+        if (rootPath) {
+            const lowerPath = rootPath.toLowerCase();
+            if (docxExtensions.some(ext => lowerPath.endsWith(ext))) {
+                return true;
+            }
+        }
+        if (filePattern) {
+            const lowerPattern = filePattern.toLowerCase();
+            if (docxExtensions.some(ext => lowerPattern.includes(`*${ext}`) || lowerPattern.endsWith(ext))) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Search DOCX files for content matches
+     * Extracts <w:t> text from document.xml and searches it
+     */
+    async searchDocxFiles(rootPath, pattern, ignoreCase, maxResults, filePattern) {
+        const results = [];
+        const flags = ignoreCase ? 'i' : '';
+        let regex;
+        try {
+            regex = new RegExp(pattern, flags);
+        }
+        catch {
+            const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            regex = new RegExp(escaped, flags);
+        }
+        let docxFiles = await this.findDocxFiles(rootPath);
+        if (filePattern) {
+            const patterns = filePattern.split('|').map(p => p.trim()).filter(Boolean);
+            docxFiles = docxFiles.filter(filePath => {
+                const fileName = path.basename(filePath);
+                return patterns.some(pat => {
+                    if (pat.includes('*')) {
+                        const regexPat = pat.replace(/\./g, '\\.').replace(/\*/g, '.*');
+                        return new RegExp(`^${regexPat}$`, 'i').test(fileName);
+                    }
+                    return fileName.toLowerCase() === pat.toLowerCase();
+                });
+            });
+        }
+        for (const filePath of docxFiles) {
+            if (maxResults && results.length >= maxResults)
+                break;
+            try {
+                const buf = await fs.readFile(filePath);
+                const zip = new PizZip(buf);
+                // Search all XML parts that can contain text
+                const xmlParts = ['word/document.xml', 'word/header1.xml', 'word/header2.xml',
+                    'word/header3.xml', 'word/footer1.xml', 'word/footer2.xml', 'word/footer3.xml'];
+                for (const xmlPath of xmlParts) {
+                    if (maxResults && results.length >= maxResults)
+                        break;
+                    const file = zip.file(xmlPath);
+                    if (!file)
+                        continue;
+                    const xml = file.asText();
+                    // Extract all <w:t> text with position tracking
+                    const wtRe = /<w:t(?:\s[^>]*)?>([^<]*)<\/w:t>/g;
+                    let m;
+                    let lineNum = 0;
+                    while ((m = wtRe.exec(xml)) !== null) {
+                        if (maxResults && results.length >= maxResults)
+                            break;
+                        const text = m[1];
+                        if (!text || !text.trim())
+                            continue;
+                        lineNum++;
+                        if (regex.test(text)) {
+                            const match = text.match(regex);
+                            const matchContext = match
+                                ? this.getMatchContext(text, match.index || 0, match[0].length)
+                                : text.substring(0, 150);
+                            const partName = xmlPath === 'word/document.xml' ? '' : `:${xmlPath.replace('word/', '')}`;
+                            results.push({
+                                file: `${filePath}${partName}`,
+                                line: lineNum,
+                                match: matchContext,
+                                type: 'content'
+                            });
+                        }
+                    }
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return results;
+    }
+    /**
+     * Find all DOCX files in a directory recursively
+     */
+    async findDocxFiles(rootPath) {
+        const docxFiles = [];
+        const isDocx = (name) => name.toLowerCase().endsWith('.docx');
+        async function walk(dir) {
+            try {
+                const entries = await fs.readdir(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    const fullPath = path.join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+                            await walk(fullPath);
+                        }
+                    }
+                    else if (entry.isFile() && isDocx(entry.name)) {
+                        docxFiles.push(fullPath);
+                    }
+                }
+            }
+            catch { /* skip */ }
+        }
+        try {
+            const stats = await fs.stat(rootPath);
+            if (stats.isFile() && isDocx(rootPath)) {
+                return [rootPath];
+            }
+            else if (stats.isDirectory()) {
+                await walk(rootPath);
+            }
+        }
+        catch { /* skip */ }
+        return docxFiles;
+    }
     /**
      * Extract context around a match for display (show surrounding text)
      */

package/dist/server.js

@@ -242,6 +242,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         - PDF: Extracts text content as markdown with page structure
                           * offset/length work as page pagination (0-based)
                           * Includes embedded images when available
+                        - DOCX (.docx): Two modes depending on parameters:
+                          * DEFAULT (no offset/length): Returns a text-bearing outline — shows paragraphs with text,
+                            tables with cell content, styles, image refs. Skips shapes/drawings/SVG noise.
+                            Each element shows its body index [0], [1], etc.
+                          * WITH offset/length: Returns raw pretty-printed XML with line pagination.
+                            Use this to drill into specific sections or see the actual XML for editing.
+                          * EDITING WORKFLOW: 1) read_file to get outline, 2) read_file with offset/length
+                            to see raw XML around what you want to edit, 3) edit_block with old_string/new_string
+                            using XML fragments copied from the read output.
+                          * IMPORTANT: offset MUST be non-zero to get raw XML (use offset=1 to start from line 1).
+                            offset=0 always returns the outline regardless of length.
+                          * For BULK changes (translation, mass replacements): use start_process with Python
+                            zipfile module to find/replace all <w:t> elements at once.
 
                         ${PATH_GUIDANCE}
                         ${CMD_PREFIX_DESCRIPTION}`,
@@ -279,6 +292,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         Write or append to file contents.
 
                         IMPORTANT: DO NOT use this tool to create PDF files. Use 'write_pdf' for all PDF creation tasks.
+                        DO NOT use this tool to edit DOCX files. Use 'edit_block' with old_string/new_string instead.
+                        To CREATE a new DOCX, use write_file with .docx extension — text content with markdown headings (#, ##, ###) is converted to styled DOCX paragraphs.
 
                         CHUNKING IS STANDARD PRACTICE: Always write files in chunks of 25-30 lines maximum.
                         This is the normal, recommended way to write files - not an emergency measure.
@@ -657,6 +672,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         - new_string: Replacement text
                         - expected_replacements: Optional number of replacements (default: 1)
 
+                        DOCX FILES (.docx) - XML Find/Replace mode:
+                        Takes same parameters as text files (old_string, new_string, expected_replacements).
+                        Operates on the pretty-printed XML inside the DOCX — the same XML you see from
+                        read_file with offset/length. Copy XML fragments from read output as old_string.
+                        After editing, the XML is repacked into a valid DOCX.
+                        Also searches headers/footers if not found in document body.
+                        Examples:
+                        - Replace text: old_string="<w:t>Old Text</w:t>" new_string="<w:t>New Text</w:t>"
+                        - Change style: old_string='<w:pStyle w:val="Normal"/>' new_string='<w:pStyle w:val="Heading1"/>'
+                        - Add content: include surrounding XML context in old_string, add new elements in new_string
+
                         By default, replaces only ONE occurrence of the search text.
                         To replace multiple occurrences, provide expected_replacements with
                         the exact number of matches expected.

package/dist/test-docx.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/docx/builders/table.d.ts

@@ -1,8 +1,10 @@
 /**
  * Table builder — creates w:tbl elements with headers, rows, and styling.
+ * Supports multiple paragraphs per cell with different styles.
  */
 import type { DocxContentTable, InsertTableOp } from '../types.js';
 /**
  * Build a table element from content structure or operation.
+ * Supports cells with multiple paragraphs, each with its own style.
  */
 export declare function buildTable(doc: Document, spec: DocxContentTable | InsertTableOp): Element;

package/dist/tools/docx/builders/table.js

@@ -1,8 +1,11 @@
 /**
  * Table builder — creates w:tbl elements with headers, rows, and styling.
+ * Supports multiple paragraphs per cell with different styles.
  */
+import { buildParagraph } from './paragraph.js';
 /**
  * Build a table element from content structure or operation.
+ * Supports cells with multiple paragraphs, each with its own style.
  */
 export function buildTable(doc, spec) {
     const tbl = doc.createElement('w:tbl');
@@ -29,12 +32,13 @@ export function buildTable(doc, spec) {
     }
     tblPr.appendChild(tblBorders);
     tbl.appendChild(tblPr);
-    // Table grid
+    // Determine column count
     const colCount = spec.headers
         ? spec.headers.length
         : spec.rows.length > 0
             ? spec.rows[0].length
             : 0;
+    // Table grid
     if (colCount > 0) {
         const tblGrid = doc.createElement('w:tblGrid');
         for (let c = 0; c < colCount; c++) {
@@ -45,9 +49,15 @@ export function buildTable(doc, spec) {
         }
         tbl.appendChild(tblGrid);
     }
-    // Helper to build a cell
-    const buildCell = (text, isHeader, widthTwips) => {
+    /**
+     * Build a cell from content.
+     * Content can be:
+     * - A string: creates one paragraph with that text
+     * - An array of DocxContentParagraph: creates multiple paragraphs, each with its own style
+     */
+    const buildCell = (content, isHeader, widthTwips) => {
         const tc = doc.createElement('w:tc');
+        // Cell properties (width)
         if (widthTwips) {
             const tcPr = doc.createElement('w:tcPr');
             const tcW = doc.createElement('w:tcW');
@@ -56,20 +66,54 @@ export function buildTable(doc, spec) {
             tcPr.appendChild(tcW);
             tc.appendChild(tcPr);
         }
-        const p = doc.createElement('w:p');
-        const r = doc.createElement('w:r');
-        if (isHeader) {
-            const rPr = doc.createElement('w:rPr');
-            const b = doc.createElement('w:b');
-            rPr.appendChild(b);
-            r.appendChild(rPr);
+        // Handle content: string or array of paragraphs
+        if (typeof content === 'string') {
+            // Simple case: single paragraph
+            const p = doc.createElement('w:p');
+            const r = doc.createElement('w:r');
+            // Header cells get bold
+            if (isHeader) {
+                const rPr = doc.createElement('w:rPr');
+                const b = doc.createElement('w:b');
+                rPr.appendChild(b);
+                r.appendChild(rPr);
+            }
+            const t = doc.createElement('w:t');
+            t.setAttribute('xml:space', 'preserve');
+            t.textContent = content;
+            r.appendChild(t);
+            p.appendChild(r);
+            tc.appendChild(p);
+        }
+        else {
+            // Complex case: multiple paragraphs with different styles
+            for (const paraSpec of content) {
+                const p = buildParagraph(doc, paraSpec);
+                // If header and first paragraph, ensure bold on runs
+                if (isHeader) {
+                    const runs = p.getElementsByTagName('w:r');
+                    for (let i = 0; i < runs.length; i++) {
+                        const run = runs.item(i);
+                        let rPr = run.getElementsByTagName('w:rPr').item(0);
+                        if (!rPr) {
+                            rPr = doc.createElement('w:rPr');
+                            if (run.firstChild) {
+                                run.insertBefore(rPr, run.firstChild);
+                            }
+                            else {
+                                run.appendChild(rPr);
+                            }
+                        }
+                        // Add bold if not already present
+                        if (!rPr.getElementsByTagName('w:b').length) {
+                            const b = doc.createElement('w:b');
+                            rPr.appendChild(b);
+                        }
+                    }
+                }
+                tc.appendChild(p);
+            }
         }
-        const t = doc.createElement('w:t');
-        t.setAttribute('xml:space', 'preserve');
-        t.textContent = text;
-        r.appendChild(t);
-        p.appendChild(r);
-        tc.appendChild(p);
         return tc;
     };
     // Header row

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

@@ -23,6 +23,17 @@ export declare function getBody(doc: Document): Element;
  * Includes w:p, w:tbl, w:sdt, w:sectPr, etc.
  */
 export declare function getBodyChildren(body: Element): Element[];
+/**
+ * Return ALL top‑level tables that are logically in the body, including those
+ * wrapped in structured document tags (w:sdt / w:sdtContent).
+ *
+ * Previous logic only saw tables that were direct children of <w:body>. That
+ * meant tables inside SDTs were invisible to table operations and readDocxOutline.
+ * This helper walks the body tree and collects any <w:tbl> that appears as a
+ * *first‑class* block (we do not recurse into tables themselves, so nested
+ * tables are not double‑counted).
+ */
+export declare function getAllBodyTables(body: Element): Element[];
 /**
  * Build a compact signature string from the body children array.
  * Maps each node's qualified name to a short local name:
@@ -34,13 +45,75 @@ export declare function bodySignature(children: Element[]): string;
 export declare function getParagraphText(p: Element): string;
 /** Read the style id from w:pPr/w:pStyle/@w:val, or null if absent. */
 export declare function getParagraphStyle(p: Element): string | null;
+/**
+ * Extract all text content from a table cell (w:tc).
+ * Returns the concatenated text from all paragraphs in the cell.
+ */
+export declare function getCellText(tc: Element): string;
+/**
+ * Extract all rows from a table (w:tbl).
+ * Returns an array of rows, where each row is an array of cell text strings.
+ * First row is treated as header if it exists.
+ */
+export declare function getTableContent(tbl: Element): {
+    headers?: string[];
+    rows: string[][];
+};
+/**
+ * Get table style from w:tblPr/w:tblStyle/@w:val, or null if absent.
+ */
+export declare function getTableStyle(tbl: Element): string | null;
+/**
+ * Extract image reference from a w:drawing element.
+ * Returns the relationship ID (rId) and media file path if found.
+ */
+export declare function getImageReference(drawing: Element): {
+    rId: string | null;
+    mediaPath: string | null;
+};
 /**
  * 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.
+ * Does NOT remove/recreate runs or remove paragraph properties.
+ *
+ * WARNING: This function does NOT preserve multiple runs with different styles.
+ * Use setParagraphTextPreservingStyles() for cells with multiple styled runs.
  */
 export declare function setParagraphTextMinimal(p: Element, text: string): void;
+/**
+ * Replace paragraph text while preserving all run styles.
+ *
+ * This function preserves the structure of all runs (w:r) and their
+ * properties (w:rPr), distributing the new text across existing runs.
+ *
+ * Strategy:
+ * 1. Collect all runs with their properties
+ * 2. Distribute new text across runs (preserving run count and styles)
+ * 3. If new text is longer, extend the last run
+ * 4. If new text is shorter, clear excess runs but keep their structure
+ */
+export declare function setParagraphTextPreservingStyles(p: Element, text: string): void;
+/**
+ * Replace cell text while preserving ALL paragraphs and their styles.
+ *
+ * This function works at the cell level:
+ * - Preserves ALL paragraphs in the cell (doesn't remove any)
+ * - Updates text in the first paragraph while preserving its styles
+ * - Keeps all other paragraphs intact with their original text and styles
+ *
+ * This ensures that cells with multiple paragraphs (each with different
+ * styles, font sizes, etc.) maintain their structure after text replacement.
+ *
+ * Example: If a cell has:
+ *   - Paragraph 1: "LAWN AND LANDSCAPE" (Heading1 style, large font, red color)
+ *   - Paragraph 2: "Take your weekends back..." (Normal style, smaller font, black color)
+ *
+ * Replacing with "EARTH AND MOUNTAIN" will:
+ *   - Update paragraph 1 to "EARTH AND MOUNTAIN" (preserving Heading1 style, large font, red color)
+ *   - Keep paragraph 2 completely intact with its original text and style
+ */
+export declare function setCellTextPreservingStyles(tc: Element, text: string): void;
 /**
  * Ensure a <w:r> element has w:rPr/w:color[@w:val=hex].
  * Creates w:rPr and w:color if they don't exist.