google-tools-mcp 1.2.12 → 2.0.0

package/dist/markdown-transformer/docsToMarkdown.js

@@ -4,6 +4,134 @@
  * When these are detected on a text run, we render backtick code in markdown.
  */
 const CODE_FONT_FAMILIES = new Set(['Roboto Mono', 'Courier New', 'Consolas', 'monospace']);
+/**
+ * Inspects the body content that replaceDocumentWithMarkdown will delete and
+ * re-insert, and reports anything docsJsonToMarkdown cannot represent at all.
+ * Returns an array of human-readable warning strings (empty if the content
+ * converts losslessly). Call before replaceDocumentWithMarkdown to warn the AI
+ * about what a body replacement will permanently lose.
+ *
+ * Checked: inline/positioned images and footnote references, neither of which
+ * has any markdown representation in either direction of this converter; a
+ * generated table of contents; and, generically, every OTHER Docs API
+ * `ParagraphElement` variant that `extractFormattedText()` does not render.
+ *
+ * `extractFormattedText()` only ever renders `textRun` (see below). The Docs
+ * API `ParagraphElement` union also defines `autoText`, `pageBreak`,
+ * `columnBreak`, `horizontalRule`, `equation`, `person`, `richLink`, and
+ * `dateElement` (https://developers.google.com/workspace/docs/api/reference/rest/v1/documents#ParagraphElement).
+ * None of those has a markdown representation, so a body replacement deletes
+ * them permanently and the current markdown output never mentions they were
+ * there. Rather than enumerate that list (and silently miss whatever variant
+ * Google adds next), this scanner is deny-by-default: any paragraph-element
+ * key other than `startIndex`/`endIndex` (position metadata) and the three
+ * keys explicitly handled elsewhere in this function (`textRun`, rendered;
+ * `inlineObjectElement`/`footnoteReference`, already counted above) is
+ * treated as an unhandled content variant and reported by name.
+ *
+ * NOT checked (intentionally): custom text/highlight colors and non-default
+ * paragraph alignment. Those round-trip losslessly through the rich-markdown
+ * HTML extensions this converter emits by default (`<span style="color:...">`,
+ * `<p align="...">`, table alignment markers) and their inverse parsing in
+ * markdownToDocs.js, so warning about them here would be inaccurate.
+ *
+ * IMPORTANT — accuracy: every warning is derived from `bodyContent` itself,
+ * i.e. the exact body (a specific tab's body in tab mode, the document body
+ * otherwise) that the replacement mutates. This deliberately does NOT inspect
+ * document-level `headers`/`footers`, which are separate document segments a
+ * body-content replacement does not delete, nor the global `inlineObjects`/
+ * `footnotes` maps, which can include content belonging to OTHER tabs that a
+ * scoped replacement never touches.
+ *
+ * @param {Array} bodyContent structural elements of the body being replaced
+ *   (e.g. `contentSource.body.content`).
+ * @returns {string[]} warnings
+ */
+// ParagraphElement keys this converter already accounts for: startIndex/
+// endIndex are position metadata (not content); textRun is rendered by
+// extractFormattedText(); inlineObjectElement/footnoteReference are counted
+// as their own dedicated warnings below. Any other key on a ParagraphElement
+// is, by the Docs API's own union contract, an unhandled content-bearing
+// variant (autoText, pageBreak, columnBreak, horizontalRule, equation,
+// person, richLink, dateElement, or a future addition) that extractFormattedText
+// silently drops.
+const HANDLED_PARAGRAPH_ELEMENT_KEYS = new Set([
+    'startIndex',
+    'endIndex',
+    'textRun',
+    'inlineObjectElement',
+    'footnoteReference',
+]);
+export function checkMarkdownFidelity(bodyContent) {
+    const warnings = [];
+    let imageCount = 0;
+    let footnoteCount = 0;
+    let tocCount = 0;
+    const unhandledElementCounts = {};
+    function scanParagraphElements(elements) {
+        for (const pe of elements) {
+            // Inline images embedded in the body flow — deleted with the body.
+            if (pe.inlineObjectElement) {
+                imageCount++;
+            }
+            // Footnote references live in the body; deleting the body removes them
+            // (and Docs then drops the orphaned footnote).
+            if (pe.footnoteReference) {
+                footnoteCount++;
+            }
+            // Deny-by-default: anything that isn't a key we explicitly handle is an
+            // unhandled ParagraphElement variant. Grouped and named below rather
+            // than warning per element.
+            for (const key of Object.keys(pe)) {
+                if (!HANDLED_PARAGRAPH_ELEMENT_KEYS.has(key)) {
+                    unhandledElementCounts[key] = (unhandledElementCounts[key] ?? 0) + 1;
+                }
+            }
+        }
+    }
+    function scanBodyContent(content) {
+        for (const element of content) {
+            if (element.paragraph) {
+                // Positioned (floating) images anchored to this paragraph are also
+                // removed when the paragraph is deleted.
+                if (Array.isArray(element.paragraph.positionedObjectIds)) {
+                    imageCount += element.paragraph.positionedObjectIds.length;
+                }
+                scanParagraphElements(element.paragraph.elements ?? []);
+            }
+            else if (element.table) {
+                for (const row of (element.table.tableRows ?? [])) {
+                    for (const cell of (row.tableCells ?? [])) {
+                        scanBodyContent(cell.content ?? []);
+                    }
+                }
+            }
+            // A generated table of contents sits in the body, so the replacement
+            // deletes it, and markdown has no way to express one, so the importer
+            // cannot put it back. Without this the whole round trip drops the TOC
+            // with nothing said about it.
+            else if (element.tableOfContents) {
+                tocCount++;
+            }
+        }
+    }
+    scanBodyContent(bodyContent ?? []);
+    if (imageCount > 0) {
+        warnings.push(`${imageCount} image(s) — will be removed`);
+    }
+    if (footnoteCount > 0) {
+        warnings.push(`${footnoteCount} footnote(s) — will be removed`);
+    }
+    if (tocCount > 0) {
+        warnings.push(`${tocCount} table(s) of contents — will be removed (markdown cannot express a generated TOC; reinsert it in Docs afterward)`);
+    }
+    const unhandledKeys = Object.keys(unhandledElementCounts).sort();
+    if (unhandledKeys.length > 0) {
+        const parts = unhandledKeys.map((key) => `${unhandledElementCounts[key]} ${key}`).join(', ');
+        warnings.push(`${parts} — unsupported content type(s) with no markdown representation; will be removed`);
+    }
+    return warnings;
+}
 // --- Main Conversion ---
 /**
  * Converts Google Docs JSON structure to a markdown string.

package/dist/markdown-transformer/index.js

@@ -12,24 +12,31 @@
 import { docsJsonToMarkdown } from './docsToMarkdown.js';
 import { convertMarkdownToRequests } from './markdownToDocs.js';
 import { executeBatchUpdateWithSplitting, findTabById } from '../googleDocsApiHelpers.js';
-export { docsJsonToMarkdown } from './docsToMarkdown.js';
+export { docsJsonToMarkdown, checkMarkdownFidelity } from './docsToMarkdown.js';
 /** Formats InsertMarkdownResult into a concise human-readable debug summary. */
 export function formatInsertResult(result) {
     const lines = [];
+    if (result.warnings?.length) {
+        lines.push('WARNINGS (content dropped):');
+        for (const warning of result.warnings) {
+            lines.push(`  - ${warning}`);
+        }
+        lines.push('');
+    }
     lines.push(`Markdown insert completed in ${result.totalElapsedMs}ms`);
     lines.push(`  Parse: ${result.parseElapsedMs}ms`);
     lines.push(`  Requests: ${result.totalRequests} total (${Object.entries(result.requestsByType)
         .map(([k, v]) => `${v} ${k}`)
         .join(', ')})`);
     lines.push(`  API calls: ${result.batchUpdate.totalApiCalls} batchUpdate calls in ${result.batchUpdate.totalElapsedMs}ms`);
-    const { phases } = result.batchUpdate;
-    if (phases.delete.requests > 0) {
+    const phases = result.batchUpdate.phases;
+    if (phases?.delete?.requests > 0) {
         lines.push(`    Delete phase: ${phases.delete.requests} requests, ${phases.delete.apiCalls} calls, ${phases.delete.elapsedMs}ms`);
     }
-    if (phases.insert.requests > 0) {
+    if (phases?.insert?.requests > 0) {
         lines.push(`    Insert phase: ${phases.insert.requests} requests, ${phases.insert.apiCalls} calls, ${phases.insert.elapsedMs}ms`);
     }
-    if (phases.format.requests > 0) {
+    if (phases?.format?.requests > 0) {
         lines.push(`    Format phase: ${phases.format.requests} requests, ${phases.format.apiCalls} calls, ${phases.format.elapsedMs}ms`);
     }
     return lines.join('\n');
@@ -85,6 +92,7 @@ export async function insertMarkdown(docs, documentId, markdown, options) {
     const overallStart = performance.now();
     const startIndex = options?.startIndex ?? 1;
     const tabId = options?.tabId;
+    const writeControl = options?.writeControl;
     // Fetch the document's default text style so we can explicitly set
     // foreground color on inserted text (fixes issue #14 — text without
     // explicit color shows "no color selected" in the Docs color picker).
@@ -109,7 +117,7 @@ export async function insertMarkdown(docs, documentId, markdown, options) {
         ...(options?.firstHeadingAsTitle && { firstHeadingAsTitle: true }),
         ...(defaultForegroundColor && { defaultForegroundColor }),
     };
-    const requests = convertMarkdownToRequests(markdown, startIndex, tabId, conversionOptions);
+    const { requests, warnings } = convertMarkdownToRequests(markdown, startIndex, tabId, conversionOptions);
     const parseElapsedMs = Math.round(performance.now() - parseStart);
     // Count requests by type
     const requestsByType = {};
@@ -119,6 +127,7 @@ export async function insertMarkdown(docs, documentId, markdown, options) {
     }
     if (requests.length === 0) {
         return {
+            warnings,
             totalRequests: 0,
             requestsByType,
             parseElapsedMs,
@@ -135,8 +144,9 @@ export async function insertMarkdown(docs, documentId, markdown, options) {
             totalElapsedMs: Math.round(performance.now() - overallStart),
         };
     }
-    const batchUpdate = await executeBatchUpdateWithSplitting(docs, documentId, requests);
+    const batchUpdate = await executeBatchUpdateWithSplitting(docs, documentId, requests, undefined, writeControl);
     return {
+        warnings,
         totalRequests: requests.length,
         requestsByType,
         parseElapsedMs,

package/dist/markdown-transformer/markdownToDocs.js

@@ -47,34 +47,119 @@ function alignmentToDocs(value) {
             return null;
     }
 }
-function parseStyleDeclarations(style) {
+// Human-readable hints for recognized CSS properties, used when a declaration
+// is dropped so the warning tells the author what format IS supported.
+const STYLE_PROPERTY_HINTS = {
+    'color': 'a 6-digit hex value like #ff0000',
+    'foreground-color': 'a 6-digit hex value like #ff0000',
+    'background-color': 'a 6-digit hex value like #ff0000',
+    'background': 'a 6-digit hex value like #ff0000',
+    'font-size': 'a point value like 12pt',
+    'font-family': 'a plain font name (letters, digits, spaces, hyphens, periods only)',
+    'text-align': 'left, center, right, or justify',
+};
+/**
+ * Parses an inline `style="..."` attribute into the subset of formatting this
+ * converter understands, AND reports every declaration that could not be
+ * applied. This is deny-by-default: nothing is silently dropped without a
+ * matching entry in `unhandled` (issue #34 follow-up: recognized tags like
+ * <span> were losing unrecognized CSS properties/values with no warning).
+ *
+ * @param options.allowAlignment - Pass true when the caller separately applies
+ *   `text-align` at the paragraph level (e.g. <p>/<div>/table cells) so a
+ *   valid `text-align` isn't double-reported as unhandled here.
+ * @param options.allowRunFormatting - Whether color/background-color/font-size/
+ *   font-family can actually be applied in this context. Only <span> (and other
+ *   run-level formatting) pushes these onto the character formatting stack; a
+ *   wrapping <p>/<div>/table cell never applies them to its contained text, so
+ *   for those callers this must be false -- otherwise a *validly formatted*
+ *   declaration (e.g. `color:#ff0000` on a <p>) would be marked "handled" even
+ *   though nothing ever consumes it, recreating the exact silent-drop bug this
+ *   function exists to prevent. Defaults to true (the <span> case).
+ */
+function parseStyleDeclarations(style, options = {}) {
+    const allowAlignment = options.allowAlignment === true;
+    const allowRunFormatting = options.allowRunFormatting !== false;
     const formatting = {};
+    const unhandled = [];
     if (!style)
-        return formatting;
+        return { formatting, unhandled };
     for (const declaration of style.split(';')) {
         const [rawName, ...rawValueParts] = declaration.split(':');
         if (!rawName || rawValueParts.length === 0)
             continue;
         const name = rawName.trim().toLowerCase();
         const value = rawValueParts.join(':').trim();
-        if ((name === 'color' || name === 'foreground-color') && /^#[0-9a-f]{6}$/i.test(value)) {
-            formatting.foregroundColor = value;
+        if (!value)
+            continue;
+        const isColor = name === 'color' || name === 'foreground-color';
+        const isBackground = name === 'background-color' || name === 'background';
+        const isFontSize = name === 'font-size';
+        const isFontFamily = name === 'font-family';
+        if (isColor || isBackground || isFontSize || isFontFamily) {
+            if (!allowRunFormatting) {
+                unhandled.push({ property: name, value, reason: 'not-applicable-here' });
+                continue;
+            }
+            if (isColor && /^#[0-9a-f]{6}$/i.test(value)) {
+                formatting.foregroundColor = value;
+                continue;
+            }
+            if (isBackground && /^#[0-9a-f]{6}$/i.test(value)) {
+                formatting.backgroundColor = value;
+                continue;
+            }
+            if (isFontSize) {
+                const match = value.match(/^(\d+(?:\.\d+)?)pt$/i);
+                if (match) {
+                    formatting.fontSize = Number(match[1]);
+                    continue;
+                }
+            }
+            if (isFontFamily) {
+                const family = value.split(',')[0]?.trim().replace(/^['"]|['"]$/g, '');
+                if (family && /^[\w .-]+$/.test(family)) {
+                    formatting.fontFamily = family;
+                    continue;
+                }
+            }
+            unhandled.push({ property: name, value, reason: 'unsupported-value' });
+            continue;
         }
-        else if ((name === 'background-color' || name === 'background') && /^#[0-9a-f]{6}$/i.test(value)) {
-            formatting.backgroundColor = value;
+        if (name === 'text-align') {
+            const alignment = alignmentToDocs(value);
+            if (!alignment) {
+                unhandled.push({ property: name, value, reason: 'unsupported-value' });
+                continue;
+            }
+            if (!allowAlignment) {
+                unhandled.push({ property: name, value, reason: 'not-applicable-here' });
+            }
+            continue;
         }
-        else if (name === 'font-size') {
-            const match = value.match(/^(\d+(?:\.\d+)?)pt$/i);
-            if (match)
-                formatting.fontSize = Number(match[1]);
+        unhandled.push({ property: name, value, reason: 'unsupported-property' });
+    }
+    return { formatting, unhandled };
+}
+/**
+ * Emits one warning per style declaration that `parseStyleDeclarations`
+ * could not apply, so recognized tags never discard formatting silently.
+ */
+function addUnhandledStyleWarnings(context, tag, unhandled) {
+    for (const { property, value, reason } of unhandled) {
+        let detail;
+        if (reason === 'not-applicable-here') {
+            detail = property === 'text-align'
+                ? `text-align is only applied on block-level elements like <p> or <div>, not <${tag}>`
+                : `${property} is only applied on inline elements like <span>, not on the <${tag}> wrapper itself`;
         }
-        else if (name === 'font-family') {
-            const family = value.split(',')[0]?.trim().replace(/^['"]|['"]$/g, '');
-            if (family && /^[\w .-]+$/.test(family))
-                formatting.fontFamily = family;
+        else {
+            detail = STYLE_PROPERTY_HINTS[property]
+                ? `expected ${STYLE_PROPERTY_HINTS[property]}`
+                : 'this CSS property is not supported';
         }
+        addWarning(context, `Dropped unsupported style declaration "${property}: ${value}" on <${tag}> (${detail}); the formatting was not applied.`);
     }
-    return formatting;
 }
 function parseRichHtmlTag(rawHtml) {
     const trimmed = rawHtml.trim();
@@ -104,6 +189,10 @@ const CODE_BACKGROUND_HEX = '#F1F3F4';
 // These constants define the visual style for programmatically created code blocks.
 const CODE_BLOCK_BG_RGB = { red: 0.937, green: 0.945, blue: 0.953 }; // #EFF1F3
 const CODE_BLOCK_BORDER_RGB = { red: 0.855, green: 0.863, blue: 0.878 }; // #DADCE0
+// Google's native horizontal-rule color, #878787 (rgb 135/255) — measured by
+// rasterizing a PDF export of a doc containing a native (Insert > Horizontal
+// line) rule. See the horizontal rule styling comment below for context.
+const HR_BORDER_RGB = { red: 0.5294117647, green: 0.5294117647, blue: 0.5294117647 }; // #878787
 // IMPORTANT: The Google Docs API always inserts a newline character ("\n") BEFORE
 // the table when processing an insertTable request. So calling insertTable at index T
 // produces the following document structure:
@@ -134,11 +223,13 @@ const EMPTY_1x1_TABLE_SIZE = 6;
  * @param startIndex - The document index where content should be inserted (1-based)
  * @param tabId - Optional tab ID for multi-tab documents
  * @param options - Optional conversion options (e.g. firstHeadingAsTitle)
- * @returns Array of Google Docs API requests (insertions first, then formatting)
+ * @returns `{ requests, warnings }` — Google Docs API requests (insertions
+ *   first, then formatting) and human-readable warnings for any markdown
+ *   constructs that were silently dropped during conversion.
  */
 export function convertMarkdownToRequests(markdown, startIndex = 1, tabId, options) {
     if (!markdown || markdown.trim().length === 0) {
-        return [];
+        return { requests: [], warnings: [] };
     }
     const parser = createParser();
     const tokens = parser.parse(markdown, {});
@@ -161,6 +252,8 @@ export function convertMarkdownToRequests(markdown, startIndex = 1, tabId, optio
         inTableCell: false,
         paragraphFormattingStack: [],
         htmlParagraphPushStack: [],
+        htmlSpanPushStack: [],
+        warningCounts: new Map(),
         tabId,
         titleConsumed: false,
         firstHeadingAsTitle: options?.firstHeadingAsTitle ?? false,
@@ -171,7 +264,10 @@ export function convertMarkdownToRequests(markdown, startIndex = 1, tabId, optio
             processToken(token, context);
         }
         finalizeFormatting(context);
-        return [...context.insertRequests, ...context.formatRequests];
+        return {
+            requests: [...context.insertRequests, ...context.formatRequests],
+            warnings: collectWarnings(context),
+        };
     }
     catch (error) {
         if (error instanceof MarkdownConversionError) {
@@ -204,6 +300,12 @@ function processToken(token, context) {
         case 'code_inline':
             handleCodeInlineToken(token, context);
             break;
+        case 'image': {
+            const alt = token.content || getAttr(token, 'alt') || 'image';
+            const src = getAttr(token, 'src') || 'unknown URL';
+            addWarning(context, `Dropped image "${alt}" (${src}) — the Docs API path does not support inline images from markdown; use the insertImage tool instead.`);
+            break;
+        }
         // Inline formatting
         case 'strong_open':
             context.formattingStack.push({ bold: true });
@@ -306,7 +408,10 @@ function processToken(token, context) {
         case 'th_open':
         case 'td_open': {
             if (context.tableState) {
-                const alignment = parseAlignmentFromStyle(getAttr(token, 'style'));
+                const cellStyle = getAttr(token, 'style');
+                const alignment = parseAlignmentFromStyle(cellStyle);
+                const { unhandled } = parseStyleDeclarations(cellStyle, { allowAlignment: true, allowRunFormatting: false });
+                addUnhandledStyleWarnings(context, token.type === 'th_open' ? 'th' : 'td', unhandled);
                 context.tableState.currentCell = {
                     text: '',
                     isHeader: context.tableState.inHeader || token.type === 'th_open',
@@ -357,6 +462,9 @@ function processToken(token, context) {
             handleHtmlBlockToken(token, context);
             break;
         default:
+            if (token.content?.trim()) {
+                addWarning(context, `Dropped unsupported markdown token "${token.type}" containing "${summarizeContent(token.content)}".`);
+            }
             break;
     }
 }
@@ -396,11 +504,15 @@ function handleHorizontalRule(context) {
 }
 function handleHtmlInlineToken(token, context) {
     const parsed = parseRichHtmlTag(token.content);
-    if (!parsed)
+    if (!parsed) {
+        addWarning(context, `Dropped unsupported inline HTML "${summarizeContent(token.content)}".`);
         return;
+    }
     const attrs = parseAttrs(parsed.attrs);
-    if (parsed.selfClosing && parsed.tag !== 'br')
+    if (parsed.selfClosing && parsed.tag !== 'br') {
+        addWarning(context, `Dropped unsupported inline HTML <${parsed.tag}>.`);
         return;
+    }
     if (parsed.closing) {
         switch (parsed.tag) {
             case 'u':
@@ -409,9 +521,12 @@ function handleHtmlInlineToken(token, context) {
             case 'mark':
                 popFormatting(context, 'backgroundColor');
                 break;
-            case 'span':
-                popFormatting(context, 'richSpan');
+            case 'span': {
+                const pushed = context.htmlSpanPushStack.pop();
+                if (pushed)
+                    popFormatting(context, 'richSpan');
                 break;
+            }
             case 'p':
             case 'div': {
                 const pushed = context.htmlParagraphPushStack.pop();
@@ -422,6 +537,8 @@ function handleHtmlInlineToken(token, context) {
             case 'blockquote':
                 context.paragraphFormattingStack.pop();
                 break;
+            default:
+                addWarning(context, `Ignored unsupported inline HTML tag </${parsed.tag}>; its text content was preserved where possible.`);
         }
         return;
     }
@@ -433,16 +550,23 @@ function handleHtmlInlineToken(token, context) {
             context.formattingStack.push({ backgroundColor: '#FFF2CC' });
             break;
         case 'span': {
-            const formatting = parseStyleDeclarations(attrs.style);
+            const { formatting, unhandled } = parseStyleDeclarations(attrs.style);
+            addUnhandledStyleWarnings(context, 'span', unhandled);
             if (hasFormatting(formatting)) {
                 formatting.richSpan = true;
                 context.formattingStack.push(formatting);
+                context.htmlSpanPushStack.push(true);
+            }
+            else {
+                context.htmlSpanPushStack.push(false);
             }
             break;
         }
         case 'p':
         case 'div': {
             const alignment = alignmentToDocs(attrs.align ?? '') ?? parseAlignmentFromStyle(attrs.style);
+            const { unhandled } = parseStyleDeclarations(attrs.style, { allowAlignment: true, allowRunFormatting: false });
+            addUnhandledStyleWarnings(context, parsed.tag, unhandled);
             if (alignment) {
                 context.paragraphFormattingStack.push({ alignment });
                 context.htmlParagraphPushStack.push(true);
@@ -461,13 +585,18 @@ function handleHtmlInlineToken(token, context) {
         case 'br':
             insertText('\n', context);
             break;
+        default:
+            addWarning(context, `Ignored unsupported inline HTML tag <${parsed.tag}>; its text content was preserved where possible.`);
     }
 }
 function handleHtmlBlockToken(token, context) {
     const content = token.content.trim();
     const match = content.match(/^<\s*(p|div|blockquote)\b([^>]*)>([\s\S]*)<\/\s*\1\s*>$/i);
-    if (!match)
+    if (!match) {
+        const tag = content.match(/^<\s*([a-z0-9]+)/i)?.[1]?.toLowerCase();
+        addWarning(context, `Dropped unsupported HTML block${tag ? ` <${tag}>` : ''} containing "${summarizeContent(content)}".`);
         return;
+    }
     const tag = match[1].toLowerCase();
     const attrs = parseAttrs(match[2]);
     const inner = match[3];
@@ -481,6 +610,8 @@ function handleHtmlBlockToken(token, context) {
     }
     else {
         const alignment = alignmentToDocs(attrs.align ?? '') ?? parseAlignmentFromStyle(attrs.style);
+        const { unhandled } = parseStyleDeclarations(attrs.style, { allowAlignment: true, allowRunFormatting: false });
+        addUnhandledStyleWarnings(context, tag, unhandled);
         if (alignment) {
             context.paragraphFormattingStack.push({ alignment });
             pushedParagraphFormatting = true;
@@ -494,6 +625,22 @@ function handleHtmlBlockToken(token, context) {
         context.paragraphFormattingStack.pop();
     }
 }
+function addWarning(context, warning) {
+    // Deduplicate by message but keep a count so repeated drops of the same
+    // construct are reported as "(N occurrences)" rather than collapsing to one.
+    context.warningCounts.set(warning, (context.warningCounts.get(warning) ?? 0) + 1);
+}
+function collectWarnings(context) {
+    const warnings = [];
+    for (const [message, count] of context.warningCounts) {
+        warnings.push(count > 1 ? `${message} (${count} occurrences)` : message);
+    }
+    return warnings;
+}
+function summarizeContent(content) {
+    const normalized = content.replace(/\s+/g, ' ').trim();
+    return normalized.length > 80 ? `${normalized.slice(0, 77)}...` : normalized;
+}
 // --- Paragraph Handlers ---
 function handleParagraphOpen(context) {
     if (context.listStack.length === 0) {
@@ -1051,7 +1198,18 @@ function finalizeFormatting(context) {
             },
         });
     }
-    // Horizontal rule styling (bottom border on empty paragraphs)
+    // Horizontal rule styling (bottom border on empty paragraphs).
+    //
+    // The Google Docs REST API cannot insert a true native horizontal rule
+    // (the `horizontalRule` ParagraphElement produced by Insert > Horizontal
+    // line); that remains an open API limitation
+    // (https://issuetracker.google.com/issues/152996327). A bottom border on
+    // an empty paragraph is the closest achievable emulation.
+    //
+    // Color/weight are matched to Google's native rule, which renders at
+    // #878787 (rgb 135/255) and 1pt thick — measured by rasterizing a PDF
+    // export of a doc containing native rules. The previous value (0.75 grey,
+    // #bfbfbf) rendered noticeably lighter than the real thing.
     for (const hrRange of context.hrRanges) {
         const range = {
             startIndex: hrRange.startIndex,
@@ -1066,7 +1224,7 @@ function finalizeFormatting(context) {
                 paragraphStyle: {
                     borderBottom: {
                         color: {
-                            color: { rgbColor: { red: 0.75, green: 0.75, blue: 0.75 } },
+                            color: { rgbColor: HR_BORDER_RGB },
                         },
                         width: { magnitude: 1, unit: 'PT' },
                         padding: { magnitude: 6, unit: 'PT' },