Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

42.9 KB
Raw Blame
import type { Definition, Image, Link, Nodes, Parents } from 'mdast';
import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import type { Handle, Info, State } from 'mdast-util-to-markdown';
import { classifyCharacter } from 'micromark-util-classify-character';
import { isValidSourceLiteralRaw } from '../extensions/source-literal-mark.ts';
import {
  angleDestinationEscapesBackslashBefore,
  angleDestinationEscapesBracket,
} from './angle-destination-escapes.ts';
import { scanBraceSpans } from './autolink-void-html-guard.ts';
import { widenFenceLength } from './code-fence.ts';
import { type RawMdxFallbackMdast, validateEscapeProvenance } from './mdast-augmentation.ts';
import { TO_MARKDOWN_EXT } from './remark-mdx-agnostic.ts';
import { isInlineWhitespaceNumericCharRef } from './whitespace-char-ref.ts';
import { escapeDecodedTableCellPipes } from './wiki-escape.ts';

declare module 'mdast-util-to-markdown' {
  interface ConstructNameMap {
    mark: 'mark';
    underline: 'underline';
    comment: 'comment';
    commentBlock: 'commentBlock';
    strikethrough: 'strikethrough';
    okAtxHeading: 'okAtxHeading';
  }
}

type MdastToMarkdownHandlerFor<N extends Nodes['type']> = (
  node: Extract<Nodes, { type: N }>,
  parent: Parents | undefined,
  state: State,
  info: Info,
) => string;

type MdastToMarkdownHandlers = {
  [K in Nodes['type']]: MdastToMarkdownHandlerFor<K>;
} & {
  mdxJsxFlowElement: (node: Nodes, parent: Parents | undefined, state: State, info: Info) => string;
};

const inlineMathHandler = Object.assign(serializeInlineMath, { peek: () => '$' });

const deleteHandler = Object.assign(serializeDelete, { peek: () => '~' });

const upstreamMdxJsxFlowHandler: Handle = (() => {
  for (const ext of TO_MARKDOWN_EXT.extensions ?? []) {
    const handler = ext?.handlers?.mdxJsxFlowElement;
    if (typeof handler === 'function') return handler;
  }
  throw new Error(
    'mdast-util-mdx-jsx mdxJsxFlowElement to-markdown handler not found — the ' +
      'dirty MDX JSX serialize path cannot bind. Likely a breaking change in ' +
      'mdast-util-mdx-jsx (pinned in the root overrides); re-run the ' +
      'markdown-pipeline upgrade protocol (test:fidelity).',
  );
})();

const LAZY_UNSAFE_LINE_RE =
  /^[ \t]*(?:$|#{1,6}(?:[ \t]|[ \t]*$)|>|(?:[-+*]|\d{1,9}[.)])[ \t]|`{3,}|~{3,}|=+[ \t]*$|-+[ \t]*$|(?:\*[ \t]*){3,}$|(?:_[ \t]*){3,}$)/;

type JsxFlowChild = MdxJsxFlowElement['children'][number];

function keepVerbatimChildUnindented(child: JsxFlowChild): JsxFlowChild {
  const fallback = child as unknown as RawMdxFallbackMdast;
  if (fallback.type !== 'rawMdxFallback') return child;
  return {
    type: 'mdxJsxFlowElement',
    name: null,
    attributes: [],
    children: [],
    data: { sourceRaw: fallback.value ?? '' },
  } as unknown as JsxFlowChild;
}

export const toMarkdownHandlers = {
  text(node, _parent, state, info) {
    if (typeof node.data?.sourceRaw === 'string') {
      if (isValidSourceLiteralRaw(node.data.sourceRaw, node.value ?? '')) {
        return node.data.sourceRaw;
      }
    }

    const escapeProvenance = validateEscapeProvenance(node.data);
    if (
      escapeProvenance.kind === 'malformed' &&
      typeof process !== 'undefined' &&
      process.env?.OK_DEBUG_POSITION_SLICE === '1'
    ) {
      console.warn(
        '[escape-provenance] malformed escapedChars metadata: CommonMark-safe serialization applies',
      );
    }

    if (escapeProvenance.kind === 'valid' && escapeProvenance.data.escapedChars.length > 0) {
      const value: string = node.value ?? '';
      const escaped = escapeProvenance.data.escapedChars;
      let result = '';
      let lastIdx = 0;
      let previousEscapedChar: string | undefined;
      const appendPlain = (segment: string, after: string): void => {
        if (!segment) return;
        const escapedAngleEnd = previousEscapedChar === '<' ? segment.indexOf('>') : -1;
        if (escapedAngleEnd >= 0) {
          result += safeText(
            state,
            segment.slice(0, escapedAngleEnd + 1),
            {
              ...info,
              before: info.before + result,
              after: segment.slice(escapedAngleEnd + 1, escapedAngleEnd + 2) || after,
            },
            true,
          );
          segment = segment.slice(escapedAngleEnd + 1);
        }
        if (segment) {
          result += safeText(state, segment, {
            ...info,
            before: info.before + result,
            after,
          });
        }
      };
      for (const { offset, char } of escaped) {
        if (offset > lastIdx) {
          appendPlain(value.slice(lastIdx, offset), '\\');
        }
        result += `\\${char}`;
        lastIdx = offset + 1;
        previousEscapedChar = char;
      }
      if (lastIdx < value.length) {
        appendPlain(value.slice(lastIdx), info.after);
      }
      return result;
    }

    return safeText(state, node.value ?? '', info);
  },

  emphasis(node, _parent, state, info) {
    const delim = node.data?.sourceDelimiter ?? '*';
    const tracker = state.createTracker(info);
    const exit = state.enter('emphasis');
    let value = tracker.move(delim);
    value += encodeAttentionBoundaries(
      state.containerPhrasing(node, {
        before: value,
        after: delim,
        ...tracker.current(),
      }),
      info,
      delim,
    );
    value += tracker.move(delim);
    exit();
    return value;
  },

  strong(node, _parent, state, info) {
    const delim = node.data?.sourceDelimiter ?? '**';
    const tracker = state.createTracker(info);
    const exit = state.enter('strong');
    let value = tracker.move(delim);
    value += encodeAttentionBoundaries(
      state.containerPhrasing(node, {
        before: value,
        after: delim,
        ...tracker.current(),
      }),
      info,
      delim,
    );
    value += tracker.move(delim);
    exit();
    return value;
  },

  link(node, parent, state, info) {
    if (node.data?.sourceStyle === 'autolink' && linkTextIsUrl(node)) {
      return `<${node.url}>`;
    }
    if (node.data?.sourceStyle === 'gfm-autolink') {
      const onlyChild = node.children?.length === 1 ? node.children[0] : null;
      if (onlyChild?.type === 'text' && typeof onlyChild.value === 'string') {
        const literal = onlyChild.value;
        const form = gfmLiteralForm(literal, node.url);
        if (form === undefined) return literal;
        const neighbors = literalNeighborCodes(literal, node, parent, state, info);
        if (bareGfmLiteralReadsBack(form, neighbors)) return literal;
        if (form === 'protocol' && readsBackAsAngleAutolink(literal)) return `<${literal}>`;
      }
    }
    const tracker = state.createTracker(info);
    const exit = state.enter('link');
    const subexit = state.enter('label');
    let value = tracker.move('[');
    value += tracker.move(
      state.containerPhrasing(node, {
        before: value,
        after: '](',
        ...tracker.current(),
      }),
    );
    value += tracker.move('](');
    subexit();

    value += emitDestination(state, tracker, node);

    if (node.title) {
      const marker = node.data?.sourceTitleMarker ?? 'double';
      value += tracker.move(emitLinkTitle(node.title, marker));
    }
    value += tracker.move(')');
    exit();
    return value;
  },

  image(node, _parent, state, info) {
    const tracker = state.createTracker(info);
    const exit = state.enter('image');
    const subexit = state.enter('label');
    let value = tracker.move('![');
    value += tracker.move(
      state.safe(node.alt ?? '', {
        before: value,
        after: '](',
        ...tracker.current(),
      }),
    );
    value += tracker.move('](');
    subexit();

    value += emitDestination(state, tracker, node);

    if (node.title) {
      const titleExit = state.enter('titleQuote');
      value += tracker.move(' "');
      value += tracker.move(
        state.safe(node.title, { before: value, after: '"', ...tracker.current() }),
      );
      value += tracker.move('"');
      titleExit();
    }
    value += tracker.move(')');
    exit();
    return value;
  },

  definition(node, _parent, state, info) {
    const layout = node.data?.sourceLayout ?? 'inline';
    const marker = node.data?.sourceTitleMarker ?? 'double';

    const exit = state.enter('definition');
    const tracker = state.createTracker(info);

    const labelExit = state.enter('label');
    let value = tracker.move('[');
    value += tracker.move(
      state.safe(state.associationId(node), {
        before: value,
        after: ']',
        ...tracker.current(),
      }),
    );
    value += tracker.move(']:');
    labelExit();

    const sep1 = layout === 'multiline' ? '\n  ' : ' ';
    value += tracker.move(sep1);

    const urlRaw = String(node.url ?? '');
    value += emitDestination(state, tracker, node, !urlRaw || /[\0- ]/.test(urlRaw));

    if (node.title) {
      const titleSep = layout === 'multiline' ? '\n  ' : ' ';
      value += tracker.move(emitLinkTitle(node.title, marker, titleSep));
    }

    exit();
    return value;
  },

  thematicBreak(node) {
    return node.data?.sourceRaw ?? '---';
  },

  break(node, _parent, state) {
    const raw = node.data?.sourceRaw;
    if (typeof raw === 'string' && raw.length > 0) return raw;
    if (state.stack.includes('tableCell') || state.stack.includes('okAtxHeading')) {
      return '<br />';
    }
    if (node.data?.sourceStyle === 'backslash') return '\\\n';
    return '  \n';
  },

  code(node, parent) {
    const value = node.value ?? '';
    if (node.data?.sourceStyle === 'indented') {
      const lines = value.split('\n');
      const indents = node.data.sourceIndents;
      if (Array.isArray(indents) && indents.length === lines.length) {
        return lines
          .map((line, i) => `${indents[i] ?? (line.length > 0 ? '    ' : '')}${line}`)
          .join('\n');
      }
      const indented = lines.map((line) => (line.length > 0 ? `    ${line}` : line)).join('\n');
      return indented;
    }
    const fenceChar = node.data?.sourceFenceChar;
    const char = fenceChar === '~' ? '~' : '`';
    const len = widenFenceLength(char, value, node.data?.sourceFenceLength ?? 3);
    const closingCaptured = node.data?.sourceClosingFenceLength;
    const closeLen =
      typeof closingCaptured === 'number' && closingCaptured > len ? closingCaptured : len;
    const indentCount = node.data?.sourceFenceIndent;
    const indent =
      typeof indentCount === 'number' && indentCount >= 1 && indentCount <= 3
        ? ' '.repeat(indentCount)
        : '';
    const infoGap = node.data?.sourceInfoPadding;
    const fence = char.repeat(len);
    const lang = node.lang ?? '';
    const langGap = lang && typeof infoGap === 'number' && infoGap >= 1 ? ' '.repeat(infoGap) : '';
    const meta = node.meta ? ` ${node.meta}` : '';
    if (
      node.data?.sourceUnclosedFence === true &&
      parent?.type === 'root' &&
      parent.children[parent.children.length - 1] === node
    ) {
      const open = `${fence}${langGap}${lang}${meta}${value.length > 0 ? `\n${value}` : ''}`;
      if (!indent) return open;
      return open
        .split('\n')
        .map((l) => (l.length > 0 ? `${indent}${l}` : l))
        .join('\n');
    }
    const body = `${fence}${langGap}${lang}${meta}\n${value}\n${char.repeat(closeLen)}`;
    if (!indent) return body;
    return body
      .split('\n')
      .map((l) => (l.length > 0 ? `${indent}${l}` : l))
      .join('\n');
  },

  inlineCode(node, _parent, state) {
    let value = node.value ?? '';
    const requestedChar = node.data?.sourceFenceChar;
    const fenceChar = requestedChar === '~' ? '~' : '`';
    const requestedLen =
      typeof node.data?.sourceFenceLength === 'number' && node.data.sourceFenceLength > 0
        ? node.data.sourceFenceLength
        : 1;

    const escaped = fenceChar === '`' ? '`' : '~';
    let length = requestedLen;
    while (new RegExp(`(^|[^${escaped}])${escaped.repeat(length)}([^${escaped}]|$)`).test(value)) {
      length += 1;
    }
    const fence = fenceChar.repeat(length);

    if (
      /[^ \r\n]/.test(value) &&
      (node.data?.sourcePadded === true ||
        (/^[ \r\n]/.test(value) && /[ \r\n]$/.test(value)) ||
        value.startsWith(fenceChar) ||
        value.endsWith(fenceChar))
    ) {
      value = ` ${value} `;
    }

    const span = `${fence}${value}${fence}`;
    return state.stack.includes('tableCell') ? escapeDecodedTableCellPipes(span) : span;
  },

  inlineMath: inlineMathHandler,

  delete: deleteHandler,

  heading(node, _parent, state, info) {
    const style = node.data?.sourceStyle ?? 'atx';
    const depth = node.depth;
    if (style === 'setext' && (depth === 1 || depth === 2)) {
      const content = state.containerPhrasing(node, { ...info, before: '\n', after: '\n' });
      const captured = node.data?.sourceUnderlineLength;
      const underlineLength =
        typeof captured === 'number' && captured >= 1 ? captured : Math.max(content.length, 3);
      const underline = (depth === 1 ? '=' : '-').repeat(underlineLength);
      return `${content}\n${underline}`;
    }
    const indentCount = node.data?.sourceLeadingIndent;
    const indent =
      typeof indentCount === 'number' && indentCount >= 1 && indentCount <= 3
        ? ' '.repeat(indentCount)
        : '';
    const interiorCount = node.data?.sourceInteriorSpacing;
    const interior =
      typeof interiorCount === 'number' && interiorCount >= 2 ? ' '.repeat(interiorCount) : ' ';
    const hashes = '#'.repeat(depth);
    const atxExit = state.enter('okAtxHeading');
    const content = state.containerPhrasing(node, {
      ...info,
      before: `${hashes} `,
      after: '\n',
    });
    atxExit();
    const trailingCount = node.data?.sourceTrailingHashes;
    if (typeof trailingCount === 'number' && trailingCount > 0) {
      const trailing = '#'.repeat(trailingCount);
      if (!content) return `${indent}${hashes} ${trailing}`;
      return `${indent}${hashes}${interior}${content} ${trailing}`;
    }
    if (!content) return `${indent}${hashes}`;
    return `${indent}${hashes}${interior}${content}`;
  },

  list(node, _parent, state, info) {
    const bullet = state.options.bullet || '-';
    const ordered = !!node.ordered;
    const savedBullet = state.bulletCurrent;
    const savedBulletLast = state.bulletLastUsed;

    if (!ordered) {
      const m = node.data?.bulletMarker;
      if (m === '-' || m === '*' || m === '+') {
        state.bulletCurrent = m;
      }
    }

    const children = node.children || [];
    const out: string[] = [];
    const delim = ordered ? (node.data?.listMarkerDelimiter ?? '.') : null;
    const counter = node.start ?? 1;

    for (let i = 0; i < children.length; i++) {
      const child = children[i];
      const capturedOrdinal = child.data?.sourceOrdinal;
      const ordinal =
        typeof capturedOrdinal === 'number' && capturedOrdinal >= 0 ? capturedOrdinal : counter + i;
      const baseMarker = ordered ? `${ordinal}${delim}` : (node.data?.bulletMarker ?? bullet);
      const capturedSpacing = child.data?.sourceMarkerSpacing;
      const spacing =
        typeof capturedSpacing === 'number' && capturedSpacing >= 2 && capturedSpacing <= 4
          ? capturedSpacing
          : 1;
      const markerGap = ' '.repeat(spacing);
      let marker = baseMarker;
      if (child.checked === true) {
        marker += `${markerGap}[${child.data?.sourceCheckboxChar === 'X' ? 'X' : 'x'}]`;
      } else if (child.checked === false) {
        marker += `${markerGap}[ ]`;
      }
      const capturedIndent = child.data?.sourceContinuationIndent;
      const contentCol = baseMarker.length + spacing;
      const padWidth =
        typeof capturedIndent === 'number' &&
        capturedIndent >= contentCol &&
        capturedIndent <= contentCol + 3
          ? capturedIndent
          : contentCol;
      const pad = ' '.repeat(padWidth);
      const firstGap = child.checked === null || child.checked === undefined ? markerGap : ' ';
      const itemChildren = child.children ?? [];
      const firstBlockIsList = itemChildren[0]?.type === 'list';
      let indented: string;
      if (firstBlockIsList) {
        const isTask = child.checked !== null && child.checked !== undefined;
        const nestedMd = state.containerFlow({ ...child, children: [itemChildren[0]] }, info);
        const trailing = itemChildren.slice(1);
        const trailingMd = trailing.length
          ? state.containerFlow({ ...child, children: trailing }, info)
          : '';
        const nestedIndented = nestedMd
          .split('\n')
          .map((l, idx) =>
            idx === 0 ? (isTask ? `${pad}${l}` : `${marker}${firstGap}${l}`) : l ? `${pad}${l}` : l,
          )
          .join('\n');
        const parts: string[] = [];
        if (isTask) {
          parts.push(marker, '', nestedIndented);
        } else {
          parts.push(nestedIndented);
        }
        if (trailingMd) {
          const trailingIndented = trailingMd
            .split('\n')
            .map((l) => (l ? `${pad}${l}` : l))
            .join('\n');
          parts.push('', trailingIndented);
        }
        indented = parts.join('\n');
      } else {
        const itemContent = state.containerFlow(child, info);
        indented = itemContent
          .split('\n')
          .map((l, idx) => (idx === 0 ? `${marker}${firstGap}${l}` : l ? `${pad}${l}` : l))
          .join('\n');
      }
      out.push(indented);
    }

    state.bulletCurrent = savedBullet;
    state.bulletLastUsed = savedBulletLast;

    const sep = node.spread ? '\n\n' : '\n';
    return out.join(sep);
  },

  table(node, _parent, state, info) {
    const around = ' ';
    const tableExit = state.enter('table');

    const matrix: string[][] = [];
    const paddingMatrix: Array<Array<{ left: number; right: number } | null>> = [];
    const rows = node.children ?? [];
    for (const row of rows) {
      const cellNodes = row.children ?? [];
      const cells: string[] = [];
      const cellPaddings: Array<{ left: number; right: number } | null> = [];
      for (const cell of cellNodes) {
        const cellExit = state.enter('tableCell');
        const phrasingExit = state.enter('phrasing');
        const value = state.containerPhrasing(cell, {
          ...info,
          before: around,
          after: around,
        });
        phrasingExit();
        cellExit();
        cells.push(value);
        const pad = cell.data?.sourcePadding;
        cellPaddings.push(
          pad &&
            typeof (pad as { left?: unknown }).left === 'number' &&
            typeof (pad as { right?: unknown }).right === 'number'
            ? { left: (pad as { left: number }).left, right: (pad as { right: number }).right }
            : null,
        );
      }
      matrix.push(cells);
      paddingMatrix.push(cellPaddings);
    }
    tableExit();

    const alignArr = node.align ?? [];
    const dashCounts = node.data?.sourceDashCounts;
    const headerWidth = matrix[0]?.length ?? 0;
    const bodyWidth = matrix.slice(1).reduce((m, r) => Math.max(m, r.length), 0);
    const mostCellsPerRow = Math.max(headerWidth, bodyWidth, alignArr.length);

    if (mostCellsPerRow === 0) {
      console.warn(JSON.stringify({ event: 'table-serialize-dropped-empty', rows: rows.length }));
      return '';
    }

    const alignmentCells: string[] = [];
    for (let col = 0; col < mostCellsPerRow; col++) {
      const align = alignArr[col];
      let before = '';
      let after = '';
      if (align === 'center') {
        before = ':';
        after = ':';
      } else if (align === 'left') {
        before = ':';
      } else if (align === 'right') {
        after = ':';
      }
      const userDashCount = dashCounts?.[col];
      const dashCount = typeof userDashCount === 'number' && userDashCount >= 1 ? userDashCount : 1;
      alignmentCells.push(before + '-'.repeat(dashCount) + after);
    }

    const formatRow = (
      cells: string[],
      paddings: Array<{ left: number; right: number } | null>,
    ): string => {
      const out: string[] = [];
      for (let i = 0; i < mostCellsPerRow; i++) {
        const content = cells[i] ?? '';
        const pad = paddings[i] ?? { left: 1, right: 1 };
        out.push(' '.repeat(pad.left) + content + ' '.repeat(pad.right));
      }
      const leading = outerPipesSafe && !outerPipesSafe.leading ? '' : '|';
      const trailing = outerPipesSafe && !outerPipesSafe.trailing ? '' : '|';
      return `${leading}${out.join('|')}${trailing}`;
    };

    const capturedAlignPadding = node.data?.sourceAlignmentPadding;
    const alignmentPaddings: Array<{ left: number; right: number } | null> = Array.from(
      { length: mostCellsPerRow },
      (_, col) => {
        const pad = capturedAlignPadding?.[col];
        return pad && typeof pad.left === 'number' && typeof pad.right === 'number' ? pad : null;
      },
    );

    const outerPipes = node.data?.sourceOuterPipes;
    const outerPipesSafe =
      outerPipes &&
      mostCellsPerRow >= 2 &&
      matrix.every((cells) => {
        const first = (cells[0] ?? '').trim();
        const last = (cells[mostCellsPerRow - 1] ?? '').trim();
        return (
          (outerPipes.leading || first.length > 0) &&
          (outerPipes.trailing || (last.length > 0 && !last.endsWith('\\')))
        );
      })
        ? outerPipes
        : null;

    if (matrix.length === 0) {
      return formatRow(alignmentCells, alignmentPaddings);
    }

    const lines: string[] = [];
    lines.push(formatRow(matrix[0], paddingMatrix[0] ?? []));
    lines.push(formatRow(alignmentCells, alignmentPaddings));
    for (let i = 1; i < matrix.length; i++) {
      lines.push(formatRow(matrix[i], paddingMatrix[i] ?? []));
    }
    return lines.join('\n');
  },

  mdxJsxFlowElement(node, parent, state, info) {
    const mdxNode = node as unknown as MdxJsxFlowElement;
    const raw = mdxNode.data?.sourceRaw;
    if (typeof raw === 'string') return raw;

    const boundary = mdxNode.data?.htmlBoundary;
    if (boundary && typeof boundary.opener === 'string' && typeof boundary.closer === 'string') {
      const childContent = state.containerFlow(
        // biome-ignore lint/suspicious/noExplicitAny: safe cast for synthetic root
        { type: 'root', children: mdxNode.children ?? [] } as any,
        info,
      );
      return `${boundary.opener}\n\n${childContent}\n\n${boundary.closer}`;
    }

    const name = mdxNode.name ?? '';
    const attrs = serializeMdxJsxAttrs(mdxNode.attributes ?? []);

    const authoredBody = mdxNode.data?.sourceBody;
    if (authoredBody && name && !attrs.includes('\n')) {
      return `${authoredBody.leading}<${name}${attrs ? ` ${attrs}` : ''}>${authoredBody.afterOpenTag}`;
    }

    if (!mdxNode.children || mdxNode.children.length === 0) {
      if (!name) return '';
      return attrs ? `<${name} ${attrs} />` : `<${name} />`;
    }

    const delegated: MdxJsxFlowElement = {
      ...mdxNode,
      attributes: (mdxNode.attributes ?? []).map(normalizeAttrForUpstream),
      children: (mdxNode.children ?? []).map(keepVerbatimChildUnindented),
    };
    return upstreamMdxJsxFlowHandler(delegated, parent, state, info);
  },

  mark(node, _parent, state, info) {
    const tracker = state.createTracker(info);
    const exit = state.enter('mark');
    let value = tracker.move('==');
    value += encodeAttentionBoundaries(
      state.containerPhrasing(node as Parents, {
        before: value,
        after: '==',
        ...tracker.current(),
      }),
      info,
      '==',
    );
    value += tracker.move('==');
    exit();
    return value;
  },

  underline(node, _parent, state, info) {
    const open = node.data?.sourceForm === 'ins' ? '<ins>' : '<u>';
    const close = node.data?.sourceForm === 'ins' ? '</ins>' : '</u>';
    const tracker = state.createTracker(info);
    const exit = state.enter('underline');
    let value = tracker.move(open);
    value += state.containerPhrasing(node as Parents, {
      before: value,
      after: close,
      ...tracker.current(),
    });
    value += tracker.move(close);
    exit();
    return value;
  },

  comment(node, _parent, state, info) {
    const sourceForm = node.data?.sourceForm;
    const open = sourceForm === 'html' ? '<!-- ' : '%%';
    const close = sourceForm === 'html' ? ' -->' : '%%';
    const tracker = state.createTracker(info);
    const exit = state.enter('comment');
    let value = tracker.move(open);
    value += state.containerPhrasing(node as Parents, {
      before: value,
      after: close,
      ...tracker.current(),
    });
    value += tracker.move(close);
    exit();
    return value;
  },

  commentBlock(node, _parent, state, info) {
    const tracker = state.createTracker(info);
    const exit = state.enter('commentBlock');

    const children = node.children ?? [];
    const sourceForm = node.data?.sourceForm;
    const sourceLayout = node.data?.sourceLayout;
    const isSingleParagraph = children.length === 1 && children[0]?.type === 'paragraph';

    if (sourceForm === 'html' && isSingleParagraph) {
      const para = children[0] as Parents;
      const inner = state.containerPhrasing(para, {
        before: '<!-- ',
        after: ' -->',
        ...tracker.current(),
      });
      exit();
      return `<!-- ${inner} -->`;
    }

    if (sourceLayout === 'inline' && isSingleParagraph) {
      const para = children[0] as Parents;
      const inner = state.containerPhrasing(para, {
        before: '%% ',
        after: ' %%',
        ...tracker.current(),
      });
      exit();
      return `%% ${inner} %%`;
    }

    // biome-ignore lint/suspicious/noExplicitAny: containerFlow's FlowParents type narrows to a closed set; commentBlock is a custom block-level promoted type that holds flow children, but its augmented mdast type isn't in the FlowParents union. The runtime call is correct.
    const inner = state.containerFlow(node as any, tracker.current());
    exit();
    return `%%\n\n${inner}\n\n%%`;
  },

  mdxJsxTextElement(node) {
    const raw = node.data?.sourceRaw;
    if (typeof raw === 'string') return raw;
    const name = node.name ?? '';
    const attrs = serializeMdxJsxAttrs(node.attributes ?? []);
    const body = (node.children ?? [])
      .map((c) => (c && typeof c === 'object' && 'value' in c ? String(c.value ?? '') : ''))
      .join('');
    if (body) {
      return attrs ? `<${name} ${attrs}>${body}</${name}>` : `<${name}>${body}</${name}>`;
    }
    return attrs ? `<${name} ${attrs} />` : `<${name}/>`;
  },

  rawMdxFallback(node) {
    return (node.value ?? '') as string;
  },

  blockquote(node, _parent, state, info) {
    const exit = state.enter('blockquote');
    const tracker = state.createTracker(info);
    tracker.move('> ');
    tracker.shift(2);
    const inner = state.containerFlow(node, tracker.current());
    exit();

    const spacings = node.data?.sourceMarkerSpacings;
    let nonBlankIdx = 0;

    return state.indentLines(inner, (line, _lineNumber, blank) => {
      if (blank) return '>';
      const lineIdx = nonBlankIdx++;
      const spacing = spacings?.[lineIdx];
      if (spacing === 'lazy' && lineIdx > 0 && !LAZY_UNSAFE_LINE_RE.test(line)) return line;
      if (spacing === 'none' || spacing === 0) return `>${line}`;
      if (typeof spacing === 'number' && spacing >= 2 && !line.startsWith(' ')) {
        return `>${' '.repeat(spacing)}${line}`;
      }
      return `> ${line}`;
    });
  },
} satisfies Partial<MdastToMarkdownHandlers>;

function serializeMdxJsxAttrs(attrs: Array<MdxJsxAttribute | MdxJsxExpressionAttribute>): string {
  const parts: string[] = [];
  for (const attr of attrs) {
    if (attr.type === 'mdxJsxExpressionAttribute') {
      parts.push(`{${attr.value}}`);
      continue;
    }
    const name = attr.name;
    if (attr.value === null || attr.value === undefined) {
      parts.push(name);
      continue;
    }
    if (typeof attr.value === 'string') {
      if (attr.value.includes('"')) {
        parts.push(`${name}={${quotedAttrExpressionValue(attr.value)}}`);
      } else {
        parts.push(`${name}="${attr.value}"`);
      }
      continue;
    }
    parts.push(`${name}={${attr.value.value}}`);
  }
  return parts.join(' ');
}

function quotedAttrExpressionValue(value: string): string {
  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
}

function normalizeAttrForUpstream(
  attr: MdxJsxAttribute | MdxJsxExpressionAttribute,
): MdxJsxAttribute | MdxJsxExpressionAttribute {
  if (
    attr.type === 'mdxJsxAttribute' &&
    typeof attr.value === 'string' &&
    attr.value.includes('"')
  ) {
    return {
      type: 'mdxJsxAttribute',
      name: attr.name,
      value: {
        type: 'mdxJsxAttributeValueExpression',
        value: quotedAttrExpressionValue(attr.value),
      },
    };
  }
  return attr;
}

const GFM_PROTOCOL_LITERAL_RE = /^https?:\/\//i;

const GFM_WWW_LITERAL_RE = /^www\./i;

const ANGLE_AUTOLINK_PLAIN_URL_RE = /^https?:\/\/[A-Za-z0-9./:?#@+,;()!'-]*$/i;

const WWW_LABEL_RE = /www\./i;

type GfmLiteralForm = 'protocol' | 'www' | 'email';

function gfmLiteralForm(text: string, href: string): GfmLiteralForm | undefined {
  if (text === href && GFM_PROTOCOL_LITERAL_RE.test(text)) return 'protocol';
  if (href === `http://${text}` && GFM_WWW_LITERAL_RE.test(text)) return 'www';
  if (href === `mailto:${text}`) return 'email';
  return undefined;
}

function linkTextIsUrl(node: Link): boolean {
  let text = '';
  for (const child of node.children) {
    if (child.type !== 'text') return false;
    text += child.value;
  }
  return text === node.url;
}

function isAsciiAlpha(code: number): boolean {
  return (code >= 0x41 && code <= 0x5a) || (code >= 0x61 && code <= 0x7a);
}

function isAsciiAlphanumeric(code: number): boolean {
  return isAsciiAlpha(code) || (code >= 0x30 && code <= 0x39);
}

function isEmailDomainCode(code: number): boolean {
  return code === 0x2d || code === 0x5f || isAsciiAlphanumeric(code);
}

function isEmailAtextCode(code: number): boolean {
  return code === 0x2b || code === 0x2e || isEmailDomainCode(code);
}

function emailLiteralOpensAfter(code: number): boolean {
  return code !== 0x2f && !isEmailAtextCode(code);
}

interface NeighborCodes {
  readonly before: number;
  readonly after: number;
  readonly afterNext: number;
}

function literalNeighborCodes(
  literal: string,
  node: Link,
  parent: Parents | undefined,
  state: State,
  info: Info,
): NeighborCodes {
  const siblings: readonly Nodes[] = parent?.children ?? [];
  const index = siblings.indexOf(node);
  const previous = index > 0 ? siblings[index - 1] : undefined;
  const next = index >= 0 ? siblings[index + 1] : undefined;
  const beforeText = previous?.type === 'text' ? previous.value : info.before;
  const afterText =
    next === undefined
      ? info.after
      : state.handle(next, parent, state, {
          ...state.createTracker(info).current(),
          before: literal,
          after: '',
        });
  return {
    before: beforeText.charCodeAt(beforeText.length - 1),
    after: afterText.charCodeAt(0),
    afterNext: afterText.charCodeAt(1),
  };
}

function emailDomainContinuesAt(after: number, afterNext: number): boolean {
  return isEmailDomainCode(after) || (after === 0x2e && isAsciiAlphanumeric(afterNext));
}

function bareGfmLiteralReadsBack(
  form: GfmLiteralForm,
  { before, after, afterNext }: NeighborCodes,
): boolean {
  if (form === 'email') {
    return emailLiteralOpensAfter(before) && !emailDomainContinuesAt(after, afterNext);
  }
  const opens = form === 'protocol' ? !isAsciiAlpha(before) : classifyFlank(before) !== 'other';
  return opens && classifyFlank(after) !== 'other';
}

function readsBackAsAngleAutolink(url: string): boolean {
  return ANGLE_AUTOLINK_PLAIN_URL_RE.test(url) && !WWW_LABEL_RE.test(url);
}

function emitLinkTitle(
  title: string,
  marker: 'single' | 'double' | 'paren',
  separator: string = ' ',
): string {
  if (marker === 'single') {
    return `${separator}'${title.replace(/'/g, "\\'")}'`;
  }
  if (marker === 'paren') {
    return `${separator}(${title.replace(/[()]/g, '\\$&')})`;
  }
  return `${separator}"${title.replace(/"/g, '\\"')}"`;
}

function emitDestination(
  state: State,
  tracker: ReturnType<State['createTracker']>,
  node: Link | Image | Definition,
  forceAngles = false,
): string {
  const urlRaw = String(node.url ?? '');
  const alreadyAngled = urlRaw.startsWith('<') && urlRaw.endsWith('>');
  const wantAngles = node.data?.sourceUrlForm === 'angle-bracketed' && !alreadyAngled;
  if (wantAngles || forceAngles) {
    const destExit = state.enter('destinationLiteral');
    const out = tracker.move(formatAngleDestination(urlRaw, state.stack.includes('tableCell')));
    destExit();
    return out;
  }
  const destExit = state.enter('destinationRaw');
  const out = tracker.move(formatLinkUrl(urlRaw));
  destExit();
  return out;
}

export function formatAngleDestination(url: string, escapePipes = false): string {
  let out = '<';
  for (let i = 0; i < url.length; i++) {
    const ch = url[i];
    if (angleDestinationEscapesBracket(ch) || (escapePipes && ch === '|')) {
      out += `\\${ch}`;
    } else if (ch === '\n') {
      out += '&#xA;';
    } else if (ch === '\r') {
      out += '&#xD;';
    } else if (ch === '\\') {
      out += angleDestinationEscapesBackslashBefore(url[i + 1]) ? '\\\\' : '\\';
    } else {
      out += ch;
    }
  }
  return `${out}>`;
}

export function formatLinkUrl(url: string): string {
  if (!url) return '';

  let depth = 0;
  let parensBalanced = true;
  for (const ch of url) {
    if (ch === '(') depth++;
    else if (ch === ')') {
      depth--;
      if (depth < 0) parensBalanced = false;
    }
  }
  if (depth !== 0) parensBalanced = false;

  if (parensBalanced) return url;

  return url.replace(/[\\()]/g, '\\$&');
}

function escapeEntityAmpersands(s: string): string {
  return s.replace(
    /(?<!\\)&(?=(#[0-9]+|#[xX][0-9A-Fa-f]+|[A-Za-z][A-Za-z0-9]*);)/g,
    (match, body: string) => (isWhitespaceNumericCharRef(body) ? match : `\\${match}`),
  );
}

function isWhitespaceNumericCharRef(body: string): boolean {
  if (body.charCodeAt(0) !== 0x23) return false;
  const code =
    body[1] === 'x' || body[1] === 'X'
      ? Number.parseInt(body.slice(2), 16)
      : Number.parseInt(body.slice(1), 10);
  return (
    code === 0x09 ||
    code === 0x0a ||
    code === 0x0b ||
    code === 0x0c ||
    code === 0x0d ||
    code === 0x20 ||
    code === 0xa0
  );
}

export const TYPED_WS_REF_PUA = '';

const NUMERIC_CHAR_REF_TOKEN_RE = /&#(?:x[0-9A-Fa-f]+|X[0-9A-Fa-f]+|[0-9]+);/g;

function markTypedInlineWhitespaceRefs(value: string): string {
  return value.replace(NUMERIC_CHAR_REF_TOKEN_RE, (ref) =>
    isInlineWhitespaceNumericCharRef(ref) ? TYPED_WS_REF_PUA + ref.slice(1) : ref,
  );
}

function emitsAtLineStart(emittedPrefix: string): boolean {
  return /[\r\n][\t ]*$/.test(emittedPrefix);
}

function safeText(
  state: State,
  value: string,
  info: Info,
  suppressGfmAutolinkLiteral: boolean = false,
): string {
  const { matched } = scanBraceSpans(value, { escapeAware: false });
  if (matched.length === 0) {
    return safeTextSegment(state, value, info, suppressGfmAutolinkLiteral);
  }

  let result = '';
  let pending = 0;

  const flushNormal = (end: number): void => {
    if (end > pending) {
      result += safeTextSegment(
        state,
        value.slice(pending, end),
        {
          ...info,
          before: info.before + result,
          after: value.slice(end, end + 1) || info.after,
        },
        suppressGfmAutolinkLiteral,
      );
    }
    pending = end;
  };

  for (const span of matched) {
    flushNormal(span.start);
    if (emitsAtLineStart(info.before + result)) continue;
    result += value.slice(span.start, span.end);
    pending = span.end;
  }
  flushNormal(value.length);
  return result;
}

function safeTextSegment(
  state: State,
  value: string,
  info: Info,
  suppressGfmAutolinkLiteral: boolean = false,
): string {
  const originalUnsafe = state.unsafe;
  state.unsafe = originalUnsafe.filter((u) => {
    if (u.character === '&' && u.after === '[#A-Za-z]') return false;
    if (u.character === '<') return false;
    if (u.character === '[') return false;
    if (u.character === '(') return false;
    if (u.character === '!' && u.after === '\\[' && u.inConstruct === 'phrasing') return false;
    if (u.character === '@' && u.before === '[+\\-.\\w]') return false;
    if (
      suppressGfmAutolinkLiteral &&
      u.character === ':' &&
      u.before === '[ps]' &&
      u.after === '\\/'
    ) {
      return false;
    }
    if (u.character === '{' && Array.isArray(u.inConstruct) && u.inConstruct.includes('phrasing')) {
      return false;
    }
    if (u.character === '`') return false;
    if (
      (u.character === '*' || u.character === '_' || u.character === '~') &&
      u.inConstruct === 'phrasing'
    ) {
      return false;
    }
    if (u.character === '=' && u.atBreak === true) return false;
    if (u.character === ' ' && u.inConstruct === 'phrasing' && u.after === '[\\r\\n]') {
      return false;
    }
    if (u.character === '\t' && u.inConstruct === 'phrasing' && u.after === '[\\r\\n]') {
      return false;
    }
    return true;
  });
  state.unsafe = state.unsafe.map((u) => {
    if (u.character !== ')' || u.atBreak !== true || u.before !== '\\d+' || u.after !== undefined) {
      return u;
    }
    const narrowed: typeof u & { _compiled?: RegExp | null } = {
      ...u,
      after: '(?:[ \t\r\n]|$)',
    };
    delete narrowed._compiled;
    return narrowed;
  });
  let result: string;
  try {
    result = state.safe(markTypedInlineWhitespaceRefs(value), info);
  } finally {
    state.unsafe = originalUnsafe;
  }
  result = result.replaceAll(TYPED_WS_REF_PUA, '\\&');
  return escapeEntityAmpersands(escapeActiveDelimiterRuns(result, info));
}

const CHARACTER_GROUP_WHITESPACE = 1;

const CHARACTER_GROUP_PUNCTUATION = 2;

type FlankClass = 'ws' | 'punct' | 'other';

function classifyFlank(code: number): FlankClass {
  if (Number.isNaN(code)) return 'ws';
  const group = classifyCharacter(code);
  if (group === CHARACTER_GROUP_WHITESPACE) return 'ws';
  if (group === CHARACTER_GROUP_PUNCTUATION) return 'punct';
  return 'other';
}

function isActiveDelimiterRun(
  marker: '*' | '_' | '~',
  beforeCode: number,
  afterCode: number,
): boolean {
  const before = classifyFlank(beforeCode);
  const after = classifyFlank(afterCode);
  const leftFlanking = after !== 'ws' && (after === 'other' || before !== 'other');
  const rightFlanking = before !== 'ws' && (before === 'other' || after !== 'other');
  if (marker === '_') {
    const canOpen = leftFlanking && (!rightFlanking || before === 'punct');
    const canClose = rightFlanking && (!leftFlanking || after === 'punct');
    return canOpen || canClose;
  }
  return leftFlanking || rightFlanking;
}

function isSetextUnderlineShape(value: string, runEnd: number, info: Info): boolean {
  let k = runEnd;
  while (k < value.length && (value[k] === ' ' || value[k] === '\t')) k++;
  if (k < value.length) return value[k] === '\n' || value[k] === '\r';
  const next = info.after.charCodeAt(0);
  return Number.isNaN(next) || next === 0x0a || next === 0x0d;
}

function escapeActiveDelimiterRuns(value: string, info: Info): string {
  let result = '';
  let i = 0;
  while (i < value.length) {
    const ch = value.charAt(i);
    if (ch === '\\') {
      result += value.slice(i, i + 2);
      i += 2;
      continue;
    }
    if (ch === '*' || ch === '_' || ch === '~' || ch === '=') {
      let j = i + 1;
      while (j < value.length && value.charAt(j) === ch) j++;
      const beforeCode =
        i === 0 ? info.before.charCodeAt(info.before.length - 1) : value.charCodeAt(i - 1);
      if (ch === '=') {
        const atLineStart = Number.isNaN(beforeCode) || beforeCode === 0x0a || beforeCode === 0x0d;
        result +=
          atLineStart && isSetextUnderlineShape(value, j, info)
            ? `\\${value.slice(i, j)}`
            : value.slice(i, j);
      } else {
        const afterCode = j < value.length ? value.charCodeAt(j) : info.after.charCodeAt(0);
        result += isActiveDelimiterRun(ch, beforeCode, afterCode)
          ? `\\${ch}`.repeat(j - i)
          : value.slice(i, j);
      }
      i = j;
      continue;
    }
    result += ch;
    i += 1;
  }
  return result;
}

function encodeAttentionBoundaries(between: string, info: Info, delim: string): string {
  const marker: '*' | '_' = delim.startsWith('_') ? '_' : '*';
  const before = info.before ?? '';
  const after = info.after ?? '';
  let result = between;
  const head = result.charCodeAt(0);
  if (shouldEncodeAttentionBoundary(before.charCodeAt(before.length - 1), head, marker)) {
    result = encodeCharacterReference(head) + result.slice(1);
  }
  const tail = result.charCodeAt(result.length - 1);
  if (shouldEncodeAttentionBoundary(after.charCodeAt(0), tail, marker)) {
    result = result.slice(0, -1) + encodeCharacterReference(tail);
  }
  return result;
}

function shouldEncodeAttentionBoundary(
  outside: number,
  inside: number,
  marker: '*' | '_',
): boolean {
  if (classifyCharacter(inside) !== CHARACTER_GROUP_WHITESPACE) return false;
  if (marker === '_' && classifyCharacter(outside) === undefined) return false;
  return true;
}

function encodeCharacterReference(code: number): string {
  return `&#x${code.toString(16).toUpperCase()};`;
}

function serializeInlineMath(
  node: Extract<Nodes, { type: 'inlineMath' }>,
  _parent: Parents | undefined,
  state: State,
  info: Info,
): string {
  let value = node.value ?? '';
  const captured = node.data?.sourceDelimiter;
  let size = typeof captured === 'string' && /^\$+$/.test(captured) ? captured.length : 2;
  if (size === 1 && !singleDollarMathReparses(value, info)) {
    size = 2;
  }
  while (new RegExp(`(^|[^$])${'\\$'.repeat(size)}([^$]|$)`).test(value)) {
    size++;
  }
  const sequence = '$'.repeat(size);
  if (
    /[^ \r\n]/.test(value) &&
    ((/^[ \r\n]/.test(value) && /[ \r\n]$/.test(value)) || /^\$|\$$/.test(value))
  ) {
    value = ` ${value} `;
  }
  let index = -1;
  while (++index < state.unsafe.length) {
    const pattern = state.unsafe[index];
    if (!pattern.atBreak) continue;
    const expression = state.compilePattern(pattern);
    let match: RegExpExecArray | null;
    // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex iteration
    while ((match = expression.exec(value)) !== null) {
      let position = match.index;
      if (value.codePointAt(position) === 10 && value.codePointAt(position - 1) === 13) {
        position--;
      }
      value = `${value.slice(0, position)} ${value.slice(match.index + 1)}`;
    }
  }
  return sequence + value + sequence;
}

function serializeDelete(
  node: Extract<Nodes, { type: 'delete' }>,
  _parent: Parents | undefined,
  state: State,
  info: Info,
): string {
  const delim = node.data?.sourceDelimiter === '~' ? '~' : '~~';
  const tracker = state.createTracker(info);
  const exit = state.enter('strikethrough');
  let value = tracker.move(delim);
  value += encodeAttentionBoundaries(
    state.containerPhrasing(node, {
      ...tracker.current(),
      before: value,
      after: '~',
    }),
    info,
    delim,
  );
  value += tracker.move(delim);
  exit();
  return value;
}

function singleDollarMathReparses(value: string, info: Info): boolean {
  if (value.length === 0) return false;
  if (!/^\S/.test(value) || !/\S$/.test(value)) return false;
  if (/[$\r\n]/.test(value)) return false;
  if (value.endsWith('\\') || /\\[!-/:-@[-`{-~]/.test(value)) return false;
  if (/^\d/.test(info.after)) return false;
  if (info.before.endsWith('\\')) return false;
  return true;
}