google-tools-mcp 1.2.11 → 2.0.0

package/dist/markdown-transformer/markdownToDocs.js

@@ -4,7 +4,7 @@ import { MarkdownConversionError } from '../types.js';
 // --- Markdown-it Setup ---
 function createParser() {
     return new MarkdownIt({
-        html: false,
+        html: true,
         linkify: true,
         typographer: false,
         breaks: false,
@@ -23,6 +23,164 @@ function getHeadingLevel(token) {
     const match = token.tag.match(/h(\d)/);
     return match ? parseInt(match[1], 10) : null;
 }
+function getAttr(token, name) {
+    return token.attrs?.find((attr) => attr[0].toLowerCase() === name.toLowerCase())?.[1] ?? null;
+}
+function parseAlignmentFromStyle(style) {
+    const match = style?.match(/(?:^|;)\s*text-align\s*:\s*(left|center|right|justify)\s*(?:;|$)/i);
+    if (!match)
+        return null;
+    return alignmentToDocs(match[1]);
+}
+function alignmentToDocs(value) {
+    switch (value.toLowerCase()) {
+        case 'center':
+            return 'CENTER';
+        case 'right':
+            return 'END';
+        case 'justify':
+        case 'justified':
+            return 'JUSTIFIED';
+        case 'left':
+            return 'START';
+        default:
+            return null;
+    }
+}
+// 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, 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 (!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;
+        }
+        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;
+        }
+        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 {
+            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.`);
+    }
+}
+function parseRichHtmlTag(rawHtml) {
+    const trimmed = rawHtml.trim();
+    const match = trimmed.match(/^<\/?\s*([a-z0-9]+)([^>]*)\/?>$/i);
+    if (!match)
+        return null;
+    const tag = match[1].toLowerCase();
+    const attrs = match[2] ?? '';
+    const closing = /^<\s*\//.test(trimmed);
+    const selfClosing = /\/\s*>$/.test(trimmed);
+    return { tag, attrs, closing, selfClosing };
+}
+function parseAttrs(rawAttrs) {
+    const attrs = {};
+    const attrRegex = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/g;
+    let match;
+    while ((match = attrRegex.exec(rawAttrs)) !== null) {
+        attrs[match[1].toLowerCase()] = match[2] ?? match[3] ?? match[4] ?? '';
+    }
+    return attrs;
+}
 const CODE_FONT_FAMILY = 'Roboto Mono';
 const CODE_TEXT_HEX = '#188038';
 const CODE_BACKGROUND_HEX = '#F1F3F4';
@@ -31,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:
@@ -61,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, {});
@@ -86,6 +250,10 @@ export function convertMarkdownToRequests(markdown, startIndex = 1, tabId, optio
         codeBlockRanges: [],
         tableState: undefined,
         inTableCell: false,
+        paragraphFormattingStack: [],
+        htmlParagraphPushStack: [],
+        htmlSpanPushStack: [],
+        warningCounts: new Map(),
         tabId,
         titleConsumed: false,
         firstHeadingAsTitle: options?.firstHeadingAsTitle ?? false,
@@ -96,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) {
@@ -129,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 });
@@ -231,10 +408,15 @@ function processToken(token, context) {
         case 'th_open':
         case 'td_open': {
             if (context.tableState) {
+                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',
                     textRanges: [],
+                    alignment,
                 };
                 context.inTableCell = true;
             }
@@ -264,11 +446,25 @@ function processToken(token, context) {
         case 'hr':
             handleHorizontalRule(context);
             break;
-        // Blockquotes (skip for now)
         case 'blockquote_open':
+            context.paragraphFormattingStack.push({
+                indentStart: 36,
+                borderLeft: true,
+            });
+            break;
         case 'blockquote_close':
+            context.paragraphFormattingStack.pop();
+            break;
+        case 'html_inline':
+            handleHtmlInlineToken(token, context);
+            break;
+        case 'html_block':
+            handleHtmlBlockToken(token, context);
             break;
         default:
+            if (token.content?.trim()) {
+                addWarning(context, `Dropped unsupported markdown token "${token.type}" containing "${summarizeContent(token.content)}".`);
+            }
             break;
     }
 }
@@ -306,6 +502,145 @@ function handleHorizontalRule(context) {
     insertText('\n', context);
     context.hrRanges.push({ startIndex: start, endIndex: context.currentIndex });
 }
+function handleHtmlInlineToken(token, context) {
+    const parsed = parseRichHtmlTag(token.content);
+    if (!parsed) {
+        addWarning(context, `Dropped unsupported inline HTML "${summarizeContent(token.content)}".`);
+        return;
+    }
+    const attrs = parseAttrs(parsed.attrs);
+    if (parsed.selfClosing && parsed.tag !== 'br') {
+        addWarning(context, `Dropped unsupported inline HTML <${parsed.tag}>.`);
+        return;
+    }
+    if (parsed.closing) {
+        switch (parsed.tag) {
+            case 'u':
+                popFormatting(context, 'underline');
+                break;
+            case 'mark':
+                popFormatting(context, 'backgroundColor');
+                break;
+            case 'span': {
+                const pushed = context.htmlSpanPushStack.pop();
+                if (pushed)
+                    popFormatting(context, 'richSpan');
+                break;
+            }
+            case 'p':
+            case 'div': {
+                const pushed = context.htmlParagraphPushStack.pop();
+                if (pushed)
+                    context.paragraphFormattingStack.pop();
+                break;
+            }
+            case 'blockquote':
+                context.paragraphFormattingStack.pop();
+                break;
+            default:
+                addWarning(context, `Ignored unsupported inline HTML tag </${parsed.tag}>; its text content was preserved where possible.`);
+        }
+        return;
+    }
+    switch (parsed.tag) {
+        case 'u':
+            context.formattingStack.push({ underline: true });
+            break;
+        case 'mark':
+            context.formattingStack.push({ backgroundColor: '#FFF2CC' });
+            break;
+        case 'span': {
+            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);
+            }
+            else {
+                context.htmlParagraphPushStack.push(false);
+            }
+            break;
+        }
+        case 'blockquote':
+            context.paragraphFormattingStack.push({
+                indentStart: 36,
+                borderLeft: true,
+            });
+            break;
+        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) {
+        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];
+    let pushedParagraphFormatting = false;
+    if (tag === 'blockquote') {
+        context.paragraphFormattingStack.push({
+            indentStart: 36,
+            borderLeft: true,
+        });
+        pushedParagraphFormatting = true;
+    }
+    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;
+        }
+    }
+    const parser = createParser();
+    for (const child of parser.parse(inner, {})) {
+        processToken(child, context);
+    }
+    if (pushedParagraphFormatting) {
+        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) {
@@ -329,10 +664,15 @@ function handleParagraphClose(context) {
     }
     // Record the range for normal paragraphs (not list items) so we can apply spacing later
     if (paragraphStart !== undefined && context.listStack.length === 0) {
-        context.normalParagraphRanges.push({
+        const paragraphRange = {
             startIndex: paragraphStart,
             endIndex: context.currentIndex,
-        });
+        };
+        const paragraphFormatting = mergeParagraphFormattingStack(context.paragraphFormattingStack);
+        if (hasParagraphFormatting(paragraphFormatting)) {
+            paragraphRange.formatting = paragraphFormatting;
+        }
+        context.normalParagraphRanges.push(paragraphRange);
     }
     context.currentParagraphStart = undefined;
 }
@@ -548,15 +888,13 @@ function handleTableClose(tableState, context) {
                 if (range.formatting.bold ||
                     range.formatting.italic ||
                     range.formatting.strikethrough ||
-                    range.formatting.code) {
-                    const styleReq = buildUpdateTextStyleRequest(absStart, absEnd, {
-                        bold: range.formatting.bold,
-                        italic: range.formatting.italic,
-                        strikethrough: range.formatting.strikethrough,
-                        fontFamily: range.formatting.code ? CODE_FONT_FAMILY : undefined,
-                        foregroundColor: range.formatting.code ? CODE_TEXT_HEX : undefined,
-                        backgroundColor: range.formatting.code ? CODE_BACKGROUND_HEX : undefined,
-                    }, context.tabId);
+                    range.formatting.code ||
+                    range.formatting.underline ||
+                    range.formatting.foregroundColor ||
+                    range.formatting.backgroundColor ||
+                    range.formatting.fontSize ||
+                    range.formatting.fontFamily) {
+                    const styleReq = buildUpdateTextStyleRequest(absStart, absEnd, formattingToTextStyle(range.formatting), context.tabId);
                     if (styleReq)
                         context.formatRequests.push(styleReq.request);
                 }
@@ -572,6 +910,11 @@ function handleTableClose(tableState, context) {
                 if (headerStyleReq)
                     context.formatRequests.push(headerStyleReq.request);
             }
+            if (cell.alignment) {
+                const alignmentReq = buildUpdateParagraphStyleRequest(adjustedIndex, adjustedIndex + cell.text.length, { alignment: cell.alignment }, context.tabId);
+                if (alignmentReq)
+                    context.formatRequests.push(alignmentReq.request);
+            }
             cumulativeTextLength += cell.text.length;
         }
     }
@@ -606,6 +949,18 @@ function mergeFormattingStack(stack) {
             merged.code = state.code;
         if (state.link !== undefined)
             merged.link = state.link;
+        if (state.underline !== undefined)
+            merged.underline = state.underline;
+        if (state.foregroundColor !== undefined)
+            merged.foregroundColor = state.foregroundColor;
+        if (state.backgroundColor !== undefined)
+            merged.backgroundColor = state.backgroundColor;
+        if (state.fontSize !== undefined)
+            merged.fontSize = state.fontSize;
+        if (state.fontFamily !== undefined)
+            merged.fontFamily = state.fontFamily;
+        if (state.richSpan !== undefined)
+            merged.richSpan = state.richSpan;
     }
     return merged;
 }
@@ -614,7 +969,41 @@ function hasFormatting(formatting) {
         formatting.italic === true ||
         formatting.strikethrough === true ||
         formatting.code === true ||
-        formatting.link !== undefined);
+        formatting.link !== undefined ||
+        formatting.underline === true ||
+        formatting.foregroundColor !== undefined ||
+        formatting.backgroundColor !== undefined ||
+        formatting.fontSize !== undefined ||
+        formatting.fontFamily !== undefined);
+}
+function formattingToTextStyle(formatting) {
+    return {
+        bold: formatting.bold,
+        italic: formatting.italic,
+        underline: formatting.underline,
+        strikethrough: formatting.strikethrough,
+        fontFamily: formatting.code ? CODE_FONT_FAMILY : formatting.fontFamily,
+        fontSize: formatting.fontSize,
+        foregroundColor: formatting.code ? CODE_TEXT_HEX : formatting.foregroundColor,
+        backgroundColor: formatting.code ? CODE_BACKGROUND_HEX : formatting.backgroundColor,
+    };
+}
+function mergeParagraphFormattingStack(stack) {
+    const merged = {};
+    for (const state of stack) {
+        if (state.alignment !== undefined)
+            merged.alignment = state.alignment;
+        if (state.indentStart !== undefined)
+            merged.indentStart = state.indentStart;
+        if (state.borderLeft !== undefined)
+            merged.borderLeft = state.borderLeft;
+    }
+    return merged;
+}
+function hasParagraphFormatting(formatting) {
+    return (formatting.alignment !== undefined ||
+        formatting.indentStart !== undefined ||
+        formatting.borderLeft === true);
 }
 function popFormatting(context, type) {
     for (let i = context.formattingStack.length - 1; i >= 0; i--) {
@@ -661,15 +1050,13 @@ function finalizeFormatting(context) {
         if (range.formatting.bold ||
             range.formatting.italic ||
             range.formatting.strikethrough ||
-            range.formatting.code) {
-            const styleRequest = buildUpdateTextStyleRequest(range.startIndex, range.endIndex, {
-                bold: range.formatting.bold,
-                italic: range.formatting.italic,
-                strikethrough: range.formatting.strikethrough,
-                fontFamily: range.formatting.code ? CODE_FONT_FAMILY : undefined,
-                foregroundColor: range.formatting.code ? CODE_TEXT_HEX : undefined,
-                backgroundColor: range.formatting.code ? CODE_BACKGROUND_HEX : undefined,
-            }, context.tabId);
+            range.formatting.code ||
+            range.formatting.underline ||
+            range.formatting.foregroundColor ||
+            range.formatting.backgroundColor ||
+            range.formatting.fontSize ||
+            range.formatting.fontFamily) {
+            const styleRequest = buildUpdateTextStyleRequest(range.startIndex, range.endIndex, formattingToTextStyle(range.formatting), context.tabId);
             if (styleRequest) {
                 context.formatRequests.push(styleRequest.request);
             }
@@ -711,6 +1098,38 @@ function finalizeFormatting(context) {
                 fields: 'spaceBelow',
             },
         });
+        if (normalRange.formatting) {
+            const paraStyle = {};
+            const fields = [];
+            if (normalRange.formatting.alignment) {
+                paraStyle.alignment = normalRange.formatting.alignment;
+                fields.push('alignment');
+            }
+            if (normalRange.formatting.indentStart !== undefined) {
+                paraStyle.indentStart = { magnitude: normalRange.formatting.indentStart, unit: 'PT' };
+                fields.push('indentStart');
+            }
+            if (normalRange.formatting.borderLeft) {
+                paraStyle.borderLeft = {
+                    color: {
+                        color: { rgbColor: { red: 0.75, green: 0.75, blue: 0.75 } },
+                    },
+                    width: { magnitude: 2, unit: 'PT' },
+                    padding: { magnitude: 6, unit: 'PT' },
+                    dashStyle: 'SOLID',
+                };
+                fields.push('borderLeft');
+            }
+            if (fields.length > 0) {
+                context.formatRequests.push({
+                    updateParagraphStyle: {
+                        range,
+                        paragraphStyle: paraStyle,
+                        fields: fields.join(','),
+                    },
+                });
+            }
+        }
     }
     // List trailing spacing: apply spaceBelow to the last paragraph of each
     // top-level list so there is a visible gap between the list and the content
@@ -779,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,
@@ -794,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' },