src/markdown-transformer/markdownToDocs.ts

// src/markdown-transformer/markdownToDocsRequests.ts
import { docs_v1 } from 'googleapis';
import MarkdownIt from 'markdown-it';
import type Token from 'markdown-it/lib/token.mjs';
import {
  buildUpdateTextStyleRequest,
  buildUpdateParagraphStyleRequest,
} from '../googleDocsApiHelpers.js';
import { MarkdownConversionError } from '../types.js';

// --- Markdown-it Setup ---

function createParser(): MarkdownIt {
  return new MarkdownIt({
    html: false,
    linkify: true,
    typographer: false,
    breaks: false,
    xhtmlOut: false,
  });
}

function getLinkHref(token: Token): string | null {
  if (token.type !== 'link_open') return null;
  const hrefAttr = token.attrs?.find((attr: [string, string]) => attr[0] === 'href');
  return hrefAttr ? hrefAttr[1] : null;
}

function getHeadingLevel(token: Token): number | null {
  if (!token.type.startsWith('heading_')) return null;
  const match = token.tag.match(/h(\d)/);
  return match ? parseInt(match[1], 10) : null;
}

// --- Internal Types ---

interface TextRange {
  startIndex: number;
  endIndex: number;
  formatting: FormattingState;
}

interface FormattingState {
  bold?: boolean;
  italic?: boolean;
  strikethrough?: boolean;
  link?: string;
  code?: boolean;
}

interface ParagraphRange {
  startIndex: number;
  endIndex: number;
  namedStyleType?: string;
}

interface ListState {
  type: 'bullet' | 'ordered';
  level: number;
}

interface PendingListItem {
  startIndex: number;
  endIndex?: number;
  nestingLevel: number;
  bulletPreset: 'NUMBERED_DECIMAL_ALPHA_ROMAN' | 'BULLET_DISC_CIRCLE_SQUARE' | 'BULLET_CHECKBOX';
  taskPrefixProcessed: boolean;
}

interface CodeBlockRange {
  tableStartIndex: number;
  textStartIndex: number;
  textEndIndex: number;
  language?: string;
}

interface TableCellData {
  text: string;
  isHeader: boolean;
  textRanges: { startIndex: number; endIndex: number; formatting: FormattingState }[];
}

interface TableState {
  rows: TableCellData[][];
  currentRow: TableCellData[];
  inHeader: boolean;
  currentCell: TableCellData | null;
}

export interface ConversionOptions {
  /** Treat the first H1 (`# ...`) as a Google Docs TITLE instead of HEADING_1. Default false. */
  firstHeadingAsTitle?: boolean;
}

interface ConversionContext {
  currentIndex: number;
  insertRequests: docs_v1.Schema$Request[];
  formatRequests: docs_v1.Schema$Request[];
  textRanges: TextRange[];
  formattingStack: FormattingState[];
  listStack: ListState[];
  paragraphRanges: ParagraphRange[];
  normalParagraphRanges: { startIndex: number; endIndex: number }[];
  listSpacingRanges: { startIndex: number; endIndex: number }[];
  pendingListItems: PendingListItem[];
  openListItemStack: number[];
  hrRanges: { startIndex: number; endIndex: number }[];
  codeBlockRanges: CodeBlockRange[];
  tableState?: TableState;
  inTableCell: boolean;
  tabId?: string;
  currentParagraphStart?: number;
  currentHeadingLevel?: number;
  /** When firstHeadingAsTitle is on, tracks whether the title H1 has been consumed. */
  titleConsumed: boolean;
  firstHeadingAsTitle: boolean;
}

const CODE_FONT_FAMILY = 'Roboto Mono';
const CODE_TEXT_HEX = '#188038';
const CODE_BACKGROUND_HEX = '#F1F3F4';

// --- Code Block (table-based) Constants ---
// Google Docs "Code Block" building block is a styled 1x1 table.
// 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

// 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:
//
//   T       → paragraph break ("\n") — auto-inserted by the API
//   T + 1   → table.startIndex       (the actual table element)
//   T + 2   → tableRow.startIndex
//   T + 3   → tableCell.startIndex
//   T + 4   → paragraph.startIndex   ← cell content (text insertion point)
//   T + 6   → table.endIndex
//
// Therefore:
//   CELL_CONTENT_OFFSET = 4  (from insertTable target T to cell content at T+4)
//   EMPTY_1x1_TABLE_SIZE = 6 (total positions: 1 newline + 5 table structure)
//   Actual table start for updateTableCellStyle = T + 1 (NOT T)
//
// Verified empirically via documents.get on a real document with a 1x1 table.
const CELL_CONTENT_OFFSET = 4;
const EMPTY_1x1_TABLE_SIZE = 6;

// --- Main Conversion Function ---

/**
 * Converts a markdown string to an array of Google Docs API batch update requests.
 *
 * This is an internal function -- callers should use `insertMarkdown()` from
 * the barrel export instead.
 *
 * @param markdown - The markdown content to convert
 * @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)
 */
export function convertMarkdownToRequests(
  markdown: string,
  startIndex: number = 1,
  tabId?: string,
  options?: ConversionOptions
): docs_v1.Schema$Request[] {
  if (!markdown || markdown.trim().length === 0) {
    return [];
  }

  const parser = createParser();
  const tokens = parser.parse(markdown, {});

  const context: ConversionContext = {
    currentIndex: startIndex,
    insertRequests: [],
    formatRequests: [],
    textRanges: [],
    formattingStack: [],
    listStack: [],
    paragraphRanges: [],
    normalParagraphRanges: [],
    listSpacingRanges: [],
    pendingListItems: [],
    openListItemStack: [],
    hrRanges: [],
    codeBlockRanges: [],
    tableState: undefined,
    inTableCell: false,
    tabId,
    titleConsumed: false,
    firstHeadingAsTitle: options?.firstHeadingAsTitle ?? false,
  };

  try {
    for (const token of tokens) {
      processToken(token, context);
    }

    finalizeFormatting(context);

    return [...context.insertRequests, ...context.formatRequests];
  } catch (error) {
    if (error instanceof MarkdownConversionError) {
      throw error;
    }
    throw new MarkdownConversionError(
      `Failed to convert markdown: ${error instanceof Error ? error.message : 'Unknown error'}`
    );
  }
}

// --- Token Processing ---

function processToken(token: Token, context: ConversionContext): void {
  switch (token.type) {
    // Headings
    case 'heading_open':
      handleHeadingOpen(token, context);
      break;
    case 'heading_close':
      handleHeadingClose(context);
      break;

    // Paragraphs
    case 'paragraph_open':
      handleParagraphOpen(context);
      break;
    case 'paragraph_close':
      handleParagraphClose(context);
      break;

    // Text content
    case 'text':
      handleTextToken(token, context);
      break;
    case 'code_inline':
      handleCodeInlineToken(token, context);
      break;

    // Inline formatting
    case 'strong_open':
      context.formattingStack.push({ bold: true });
      break;
    case 'strong_close':
      popFormatting(context, 'bold');
      break;
    case 'em_open':
      context.formattingStack.push({ italic: true });
      break;
    case 'em_close':
      popFormatting(context, 'italic');
      break;
    case 's_open':
      context.formattingStack.push({ strikethrough: true });
      break;
    case 's_close':
      popFormatting(context, 'strikethrough');
      break;

    // Links
    case 'link_open': {
      const href = getLinkHref(token);
      if (href) {
        context.formattingStack.push({ link: href });
      }
      break;
    }
    case 'link_close':
      popFormatting(context, 'link');
      break;

    // Lists
    case 'bullet_list_open':
      context.listStack.push({ type: 'bullet', level: context.listStack.length });
      break;
    case 'bullet_list_close':
      handleListClose(context);
      break;
    case 'ordered_list_open':
      context.listStack.push({ type: 'ordered', level: context.listStack.length });
      break;
    case 'ordered_list_close':
      handleListClose(context);
      break;
    case 'list_item_open':
      handleListItemOpen(context);
      break;
    case 'list_item_close':
      handleListItemClose(context);
      break;

    // Breaks
    case 'softbreak':
      if (context.inTableCell && context.tableState?.currentCell) {
        context.tableState.currentCell.text += ' ';
      } else {
        insertText(' ', context);
      }
      break;
    case 'hardbreak':
      if (context.inTableCell && context.tableState?.currentCell) {
        context.tableState.currentCell.text += '\n';
      } else {
        insertText('\n', context);
      }
      break;

    // Inline container
    case 'inline':
      if (token.children) {
        for (const child of token.children) {
          processToken(child, context);
        }
      }
      break;

    // Tables
    case 'table_open':
      context.tableState = { rows: [], currentRow: [], inHeader: false, currentCell: null };
      break;
    case 'thead_open':
      if (context.tableState) context.tableState.inHeader = true;
      break;
    case 'thead_close':
      if (context.tableState) context.tableState.inHeader = false;
      break;
    case 'tbody_open':
    case 'tbody_close':
      break;
    case 'tr_open':
      if (context.tableState) context.tableState.currentRow = [];
      break;
    case 'tr_close':
      if (context.tableState && context.tableState.currentRow.length > 0) {
        context.tableState.rows.push([...context.tableState.currentRow]);
        context.tableState.currentRow = [];
      }
      break;
    case 'th_open':
    case 'td_open': {
      if (context.tableState) {
        context.tableState.currentCell = {
          text: '',
          isHeader: context.tableState.inHeader || token.type === 'th_open',
          textRanges: [],
        };
        context.inTableCell = true;
      }
      break;
    }
    case 'th_close':
    case 'td_close':
      if (context.tableState?.currentCell) {
        context.tableState.currentRow.push(context.tableState.currentCell);
        context.tableState.currentCell = null;
      }
      context.inTableCell = false;
      break;
    case 'table_close':
      if (context.tableState) {
        handleTableClose(context.tableState, context);
        context.tableState = undefined;
        context.inTableCell = false;
      }
      break;

    // Code blocks
    case 'fence':
    case 'code_block':
      handleCodeBlockToken(token, context);
      break;

    // Horizontal rules
    case 'hr':
      handleHorizontalRule(context);
      break;

    // Blockquotes (skip for now)
    case 'blockquote_open':
    case 'blockquote_close':
      break;

    default:
      break;
  }
}

// --- Heading Handlers ---

function handleHeadingOpen(token: Token, context: ConversionContext): void {
  const level = getHeadingLevel(token);
  if (level) {
    context.currentHeadingLevel = level;
    context.currentParagraphStart = context.currentIndex;
  }
}

function handleHeadingClose(context: ConversionContext): void {
  if (context.currentHeadingLevel && context.currentParagraphStart !== undefined) {
    // When firstHeadingAsTitle is enabled, the very first H1 becomes a TITLE.
    const useTitle =
      context.firstHeadingAsTitle && !context.titleConsumed && context.currentHeadingLevel === 1;

    if (useTitle) {
      context.titleConsumed = true;
    }

    context.paragraphRanges.push({
      startIndex: context.currentParagraphStart,
      endIndex: context.currentIndex,
      namedStyleType: useTitle ? 'TITLE' : `HEADING_${context.currentHeadingLevel}`,
    });

    insertText('\n', context);
    context.currentHeadingLevel = undefined;
    context.currentParagraphStart = undefined;
  }
}

// --- Horizontal Rule ---

function handleHorizontalRule(context: ConversionContext): void {
  if (!lastInsertEndsWithNewline(context)) {
    insertText('\n', context);
  }

  const start = context.currentIndex;
  insertText('\n', context);

  context.hrRanges.push({ startIndex: start, endIndex: context.currentIndex });
}

// --- Paragraph Handlers ---

function handleParagraphOpen(context: ConversionContext): void {
  if (context.listStack.length === 0) {
    context.currentParagraphStart = context.currentIndex;
  }
}

function handleParagraphClose(context: ConversionContext): void {
  // Track normal (non-list) paragraph ranges for spacing
  const paragraphStart = context.currentParagraphStart;

  if (!lastInsertEndsWithNewline(context)) {
    insertText('\n', context);
  }

  const currentListItem = getCurrentOpenListItem(context);
  if (currentListItem) {
    const paragraphEndIndex = lastInsertEndsWithNewline(context)
      ? context.currentIndex - 1
      : context.currentIndex;
    if (paragraphEndIndex > currentListItem.startIndex) {
      currentListItem.endIndex = paragraphEndIndex;
    }
  }

  // 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({
      startIndex: paragraphStart,
      endIndex: context.currentIndex,
    });
  }

  context.currentParagraphStart = undefined;
}

// --- List Handlers ---

function handleListItemOpen(context: ConversionContext): void {
  if (context.listStack.length === 0) {
    throw new MarkdownConversionError('List item found outside of list context');
  }

  const currentList = context.listStack[context.listStack.length - 1];
  const itemStart = context.currentIndex;

  if (currentList.level > 0) {
    insertText('\t'.repeat(currentList.level), context);
  }

  const listItem: PendingListItem = {
    startIndex: itemStart,
    nestingLevel: currentList.level,
    bulletPreset:
      currentList.type === 'ordered' ? 'NUMBERED_DECIMAL_ALPHA_ROMAN' : 'BULLET_DISC_CIRCLE_SQUARE',
    taskPrefixProcessed: false,
  };
  context.pendingListItems.push(listItem);
  context.openListItemStack.push(context.pendingListItems.length - 1);
}

function handleListItemClose(context: ConversionContext): void {
  const openIndex = context.openListItemStack.pop();
  if (openIndex === undefined) return;

  const listItem = context.pendingListItems[openIndex];
  if (listItem.endIndex === undefined) {
    const computedEndIndex = lastInsertEndsWithNewline(context)
      ? context.currentIndex - 1
      : context.currentIndex;
    if (computedEndIndex > listItem.startIndex) {
      listItem.endIndex = computedEndIndex;
    }
  }

  if (!lastInsertEndsWithNewline(context)) {
    insertText('\n', context);
  }
}

function handleListClose(context: ConversionContext): void {
  context.listStack.pop();

  // When a top-level list closes (stack becomes empty), record the range of the
  // last list item's paragraph so we can apply spaceBelow to it. This creates a
  // visible gap between the end of a list and the following content.
  if (context.listStack.length === 0) {
    // Find the last pending list item that has a valid endIndex
    for (let i = context.pendingListItems.length - 1; i >= 0; i--) {
      const item = context.pendingListItems[i];
      if (item.endIndex !== undefined && item.endIndex > item.startIndex) {
        context.listSpacingRanges.push({
          startIndex: item.startIndex,
          endIndex: item.endIndex,
        });
        break;
      }
    }
  }
}

// --- Text Handling ---

function handleTextToken(token: Token, context: ConversionContext): void {
  let text = token.content;
  if (!text) return;

  // Intercept text when inside a table cell — collect into cell buffer
  if (context.inTableCell && context.tableState?.currentCell) {
    const cell = context.tableState.currentCell;
    const startIndex = cell.text.length;
    cell.text += text;
    const formatting = mergeFormattingStack(context.formattingStack);
    if (hasFormatting(formatting)) {
      cell.textRanges.push({ startIndex, endIndex: cell.text.length, formatting });
    }
    return;
  }

  const currentListItem = getCurrentOpenListItem(context);
  if (currentListItem && !currentListItem.taskPrefixProcessed) {
    currentListItem.taskPrefixProcessed = true;
    const taskPrefixMatch = text.match(/^\[( |x|X)\]\s+/);
    if (taskPrefixMatch) {
      currentListItem.bulletPreset = 'BULLET_CHECKBOX';
      text = text.slice(taskPrefixMatch[0].length);
      if (!text) return;
    }
  }

  const startIndex = context.currentIndex;
  const endIndex = startIndex + text.length;

  insertText(text, context);

  const currentFormatting = mergeFormattingStack(context.formattingStack);
  if (hasFormatting(currentFormatting)) {
    context.textRanges.push({ startIndex, endIndex, formatting: currentFormatting });
  }
}

function handleCodeInlineToken(token: Token, context: ConversionContext): void {
  context.formattingStack.push({ code: true });
  handleTextToken(token, context);
  popFormatting(context, 'code');
}

function handleCodeBlockToken(token: Token, context: ConversionContext): void {
  const normalizedContent = token.content.endsWith('\n')
    ? token.content.slice(0, -1)
    : token.content;
  const language = token.info?.trim() || undefined;

  // Ensure previous content ends with a newline before inserting the table
  if (context.insertRequests.length > 0 && !lastInsertEndsWithNewline(context)) {
    insertText('\n', context);
  }

  const tableStartIndex = context.currentIndex;

  // 1. Insert a 1x1 table (creates the table structure with an empty paragraph in the cell)
  const tableLocation: Record<string, unknown> = { index: tableStartIndex };
  if (context.tabId) tableLocation.tabId = context.tabId;
  context.insertRequests.push({
    insertTable: {
      location: tableLocation as docs_v1.Schema$Location,
      rows: 1,
      columns: 1,
    },
  });

  // 2. Insert code text into the cell paragraph
  // For a 1x1 table at index N, the cell paragraph content starts at N + CELL_CONTENT_OFFSET
  const cellContentIndex = tableStartIndex + CELL_CONTENT_OFFSET;
  const textLength = normalizedContent.length;

  if (textLength > 0) {
    const cellLocation: Record<string, unknown> = { index: cellContentIndex };
    if (context.tabId) cellLocation.tabId = context.tabId;
    context.insertRequests.push({
      insertText: {
        location: cellLocation as docs_v1.Schema$Location,
        text: normalizedContent,
      },
    });
  }

  // 3. Track the code block for table/text formatting in finalization
  context.codeBlockRanges.push({
    tableStartIndex,
    textStartIndex: cellContentIndex,
    textEndIndex: cellContentIndex + textLength,
    language,
  });

  // 4. Advance currentIndex past the entire table structure
  // Total table size = EMPTY_1x1_TABLE_SIZE + inserted text length
  context.currentIndex = tableStartIndex + EMPTY_1x1_TABLE_SIZE + textLength;

  // 5. Ensure a newline after the table for paragraph separation
  insertText('\n', context);
}

// --- Table Handler ---
//
// Google Docs API table index layout for an R×C table inserted at T:
//
//   T          → newline (auto-inserted before table)
//   T + 1      → table element
//   T + 2      → row[0]
//   T + 3      → cell[0][0]
//   T + 4      → paragraph in cell[0][0]  ← content insertion point
//   T + 5      → cell[0][1]  (for C > 1)
//   T + 6      → paragraph in cell[0][1]
//   ...
//   T + 2+C    → row[1]  (for R > 1)
//   ...
//   T + end    → table end
//
// Formulas (verified empirically via CELL_CONTENT_OFFSET and EMPTY_1x1_TABLE_SIZE):
//   cellContentIndex(T, r, c, C) = T + 4 + r * (1 + 2*C) + 2*c
//   emptyTableSize(R, C)         = 3 + R * (1 + 2*C)

function handleTableClose(tableState: TableState, context: ConversionContext): void {
  const rows = tableState.rows;
  if (rows.length === 0) return;

  const numRows = rows.length;
  const numCols = rows.reduce((max, row) => Math.max(max, row.length), 0);
  if (numCols === 0) return;

  // Ensure newline before table
  if (!lastInsertEndsWithNewline(context)) {
    insertText('\n', context);
  }

  const tableStartIndex = context.currentIndex;

  // Insert the table structure
  const tableLocation: Record<string, unknown> = { index: tableStartIndex };
  if (context.tabId) tableLocation.tabId = context.tabId;

  context.insertRequests.push({
    insertTable: {
      location: tableLocation as docs_v1.Schema$Location,
      rows: numRows,
      columns: numCols,
    },
  });

  // Insert text into each cell, tracking cumulative offset from prior insertions
  let cumulativeTextLength = 0;

  for (let r = 0; r < numRows; r++) {
    for (let c = 0; c < numCols; c++) {
      const cell = rows[r]?.[c];
      if (!cell?.text) continue;

      const baseCellIndex = tableStartIndex + 4 + r * (1 + 2 * numCols) + 2 * c;
      const adjustedIndex = baseCellIndex + cumulativeTextLength;

      const cellLocation: Record<string, unknown> = { index: adjustedIndex };
      if (context.tabId) cellLocation.tabId = context.tabId;

      context.insertRequests.push({
        insertText: {
          location: cellLocation as docs_v1.Schema$Location,
          text: cell.text,
        },
      });

      // Apply inline formatting (bold, italic, links, etc.) from within the cell
      for (const range of cell.textRanges) {
        const absStart = adjustedIndex + range.startIndex;
        const absEnd = adjustedIndex + range.endIndex;

        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
          );
          if (styleReq) context.formatRequests.push(styleReq.request);
        }

        if (range.formatting.link) {
          const linkReq = buildUpdateTextStyleRequest(
            absStart,
            absEnd,
            { linkUrl: range.formatting.link },
            context.tabId
          );
          if (linkReq) context.formatRequests.push(linkReq.request);
        }
      }

      // Bold all text in header cells
      if (cell.isHeader && cell.text.length > 0) {
        const headerStyleReq = buildUpdateTextStyleRequest(
          adjustedIndex,
          adjustedIndex + cell.text.length,
          { bold: true },
          context.tabId
        );
        if (headerStyleReq) context.formatRequests.push(headerStyleReq.request);
      }

      cumulativeTextLength += cell.text.length;
    }
  }

  // Advance currentIndex past the full table (empty structure + all inserted text)
  const emptyTableSize = 3 + numRows * (1 + 2 * numCols);
  context.currentIndex = tableStartIndex + emptyTableSize + cumulativeTextLength;

  // Ensure newline after table
  insertText('\n', context);
}

// --- Insert Helper ---

function insertText(text: string, context: ConversionContext): void {
  const location: Record<string, unknown> = { index: context.currentIndex };
  if (context.tabId) {
    location.tabId = context.tabId;
  }

  context.insertRequests.push({
    insertText: { location: location as docs_v1.Schema$Location, text },
  });

  context.currentIndex += text.length;
}

// --- Formatting Stack ---

function mergeFormattingStack(stack: FormattingState[]): FormattingState {
  const merged: FormattingState = {};
  for (const state of stack) {
    if (state.bold !== undefined) merged.bold = state.bold;
    if (state.italic !== undefined) merged.italic = state.italic;
    if (state.strikethrough !== undefined) merged.strikethrough = state.strikethrough;
    if (state.code !== undefined) merged.code = state.code;
    if (state.link !== undefined) merged.link = state.link;
  }
  return merged;
}

function hasFormatting(formatting: FormattingState): boolean {
  return (
    formatting.bold === true ||
    formatting.italic === true ||
    formatting.strikethrough === true ||
    formatting.code === true ||
    formatting.link !== undefined
  );
}

function popFormatting(context: ConversionContext, type: keyof FormattingState): void {
  for (let i = context.formattingStack.length - 1; i >= 0; i--) {
    if (context.formattingStack[i][type] !== undefined) {
      context.formattingStack.splice(i, 1);
      break;
    }
  }
}

// --- Finalization ---

function finalizeFormatting(context: ConversionContext): void {
  // Character-level formatting (bold, italic, strikethrough, code, links)
  for (const range of context.textRanges) {
    const rangeLocation: docs_v1.Schema$Range = {
      startIndex: range.startIndex,
      endIndex: range.endIndex,
    };
    if (context.tabId) {
      rangeLocation.tabId = context.tabId;
    }

    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
      );
      if (styleRequest) {
        context.formatRequests.push(styleRequest.request);
      }
    }

    if (range.formatting.link) {
      const linkRequest = buildUpdateTextStyleRequest(
        range.startIndex,
        range.endIndex,
        { linkUrl: range.formatting.link },
        context.tabId
      );
      if (linkRequest) {
        context.formatRequests.push(linkRequest.request);
      }
    }
  }

  // Paragraph-level formatting (headings)
  for (const paraRange of context.paragraphRanges) {
    if (paraRange.namedStyleType) {
      const paraRequest = buildUpdateParagraphStyleRequest(
        paraRange.startIndex,
        paraRange.endIndex,
        { namedStyleType: paraRange.namedStyleType as any },
        context.tabId
      );
      if (paraRequest) {
        context.formatRequests.push(paraRequest.request);
      }
    }
  }

  // Normal paragraph spacing (spaceBelow so paragraphs have visible gaps between them,
  // matching the visual separation expected from markdown-rendered paragraphs).
  // The default Google Docs NORMAL_TEXT style has 0pt spacing, so without this
  // paragraphs would appear crammed together with no gap.
  for (const normalRange of context.normalParagraphRanges) {
    const range: docs_v1.Schema$Range = {
      startIndex: normalRange.startIndex,
      endIndex: normalRange.endIndex,
    };
    if (context.tabId) {
      range.tabId = context.tabId;
    }

    context.formatRequests.push({
      updateParagraphStyle: {
        range,
        paragraphStyle: {
          spaceBelow: { magnitude: 8, unit: 'PT' },
        },
        fields: 'spaceBelow',
      },
    });
  }

  // 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
  // that follows it.
  for (const listRange of context.listSpacingRanges) {
    const range: docs_v1.Schema$Range = {
      startIndex: listRange.startIndex,
      endIndex: listRange.endIndex,
    };
    if (context.tabId) {
      range.tabId = context.tabId;
    }

    context.formatRequests.push({
      updateParagraphStyle: {
        range,
        paragraphStyle: {
          spaceBelow: { magnitude: 8, unit: 'PT' },
        },
        fields: 'spaceBelow',
      },
    });
  }

  // Code block table formatting (1x1 table with background + monospace text)
  for (const codeBlock of context.codeBlockRanges) {
    // The actual table element starts at tableStartIndex + 1 because insertTable
    // auto-inserts a preceding newline at tableStartIndex (see constants comment above).
    const tableStartLocation: Record<string, unknown> = { index: codeBlock.tableStartIndex + 1 };
    if (context.tabId) tableStartLocation.tabId = context.tabId;

    // Style the text inside the cell as monospace
    if (codeBlock.textEndIndex > codeBlock.textStartIndex) {
      const codeTextStyle = buildUpdateTextStyleRequest(
        codeBlock.textStartIndex,
        codeBlock.textEndIndex,
        { fontFamily: CODE_FONT_FAMILY },
        context.tabId
      );
      if (codeTextStyle) {
        context.formatRequests.push(codeTextStyle.request);
      }
    }

    // Set cell background color to light gray
    const borderStyle = {
      color: { color: { rgbColor: CODE_BLOCK_BORDER_RGB } },
      width: { magnitude: 0.5, unit: 'PT' },
      dashStyle: 'SOLID',
    };

    context.formatRequests.push({
      updateTableCellStyle: {
        tableRange: {
          tableCellLocation: {
            tableStartLocation: tableStartLocation as docs_v1.Schema$Location,
            rowIndex: 0,
            columnIndex: 0,
          },
          rowSpan: 1,
          columnSpan: 1,
        },
        tableCellStyle: {
          backgroundColor: { color: { rgbColor: CODE_BLOCK_BG_RGB } },
          paddingTop: { magnitude: 8, unit: 'PT' },
          paddingBottom: { magnitude: 8, unit: 'PT' },
          paddingLeft: { magnitude: 12, unit: 'PT' },
          paddingRight: { magnitude: 12, unit: 'PT' },
          borderTop: borderStyle,
          borderBottom: borderStyle,
          borderLeft: borderStyle,
          borderRight: borderStyle,
        },
        fields:
          'backgroundColor,paddingTop,paddingBottom,paddingLeft,paddingRight,borderTop,borderBottom,borderLeft,borderRight',
      },
    });
  }

  // Horizontal rule styling (bottom border on empty paragraphs)
  for (const hrRange of context.hrRanges) {
    const range: docs_v1.Schema$Range = {
      startIndex: hrRange.startIndex,
      endIndex: hrRange.endIndex,
    };
    if (context.tabId) {
      range.tabId = context.tabId;
    }

    context.formatRequests.push({
      updateParagraphStyle: {
        range,
        paragraphStyle: {
          borderBottom: {
            color: {
              color: { rgbColor: { red: 0.75, green: 0.75, blue: 0.75 } },
            },
            width: { magnitude: 1, unit: 'PT' },
            padding: { magnitude: 6, unit: 'PT' },
            dashStyle: 'SOLID',
          },
        },
        fields: 'borderBottom',
      },
    });
  }

  // List formatting: merge *adjacent* items of the same bullet type into single
  // ranges so Google Docs treats them as one list (with sequential numbering).
  // Items are only merged when they're truly adjacent (gap of at most 1 char
  // for the newline between them). Separate lists with paragraphs, headings, or
  // other content between them must NOT be merged, otherwise
  // createParagraphBullets would turn all intervening content into bullets.
  const validListItems = context.pendingListItems
    .filter((item) => item.endIndex !== undefined && item.endIndex > item.startIndex)
    .sort((a, b) => a.startIndex - b.startIndex);

  const mergedListRanges: { startIndex: number; endIndex: number; bulletPreset: string }[] = [];
  for (const item of validListItems) {
    const last = mergedListRanges[mergedListRanges.length - 1];
    if (last && last.bulletPreset === item.bulletPreset && item.startIndex <= last.endIndex + 1) {
      last.endIndex = Math.max(last.endIndex, item.endIndex!);
    } else {
      mergedListRanges.push({
        startIndex: item.startIndex,
        endIndex: item.endIndex!,
        bulletPreset: item.bulletPreset,
      });
    }
  }

  // Apply bottom-to-top to avoid index shifts from tab consumption
  mergedListRanges.sort((a, b) => b.startIndex - a.startIndex);

  for (const merged of mergedListRanges) {
    const rangeLocation: docs_v1.Schema$Range = {
      startIndex: merged.startIndex,
      endIndex: merged.endIndex,
    };
    if (context.tabId) {
      rangeLocation.tabId = context.tabId;
    }

    context.formatRequests.push({
      createParagraphBullets: {
        range: rangeLocation,
        bulletPreset: merged.bulletPreset,
      },
    });
  }
}

// --- Utility ---

function getCurrentOpenListItem(context: ConversionContext): PendingListItem | null {
  const openIndex = context.openListItemStack[context.openListItemStack.length - 1];
  if (openIndex === undefined) return null;
  return context.pendingListItems[openIndex] ?? null;
}

function lastInsertEndsWithNewline(context: ConversionContext): boolean {
  const lastInsert = context.insertRequests[context.insertRequests.length - 1]?.insertText?.text;
  return Boolean(lastInsert && lastInsert.endsWith('\n'));
}