@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.0b5b49f

package/dist/Markdown/parser.js

@@ -0,0 +1,1291 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file parser.ts
+ * @input Markdown string
+ * @output Array of MarkdownNode AST nodes
+ * @position Core parser; consumed by Markdown.tsx
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Parse options
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for the markdown parser entry points.
+ *
+ * Backward-compatible: the public `parseMarkdown` / `parseInline` /
+ * `parseMarkdownIncremental` functions also accept the legacy
+ * `ReadonlySet<string>` shape as the second argument.
+ */
+
+const EMPTY_OPTS = {
+  sourceIds: undefined,
+  autolink: undefined
+};
+function resolveOptions(arg) {
+  if (arg == null) {
+    return EMPTY_OPTS;
+  }
+  // Duck-type the legacy `ReadonlySet<string>` form: any object whose
+  // `.has` is callable is treated as the legacy sourceIds set. This is
+  // safer than `instanceof Set`, which would misclassify cross-realm
+  // or polyfilled `ReadonlySet` implementations as a `ParseOptions` bag
+  // and silently lose citation resolution.
+  if (typeof arg.has === 'function') {
+    return {
+      sourceIds: arg,
+      autolink: undefined
+    };
+  }
+  const opts = arg;
+  return {
+    sourceIds: opts.sourceIds,
+    autolink: opts.autolink
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Inline parser helpers
+// ---------------------------------------------------------------------------
+
+/** Find closing ')' that balances nested parentheses. */
+function findClosingParen(text, start) {
+  let depth = 1;
+  for (let index = start; index < text.length; index++) {
+    if (text[index] === '(') {
+      depth++;
+    } else if (text[index] === ')') {
+      depth--;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return -1;
+}
+function isWordChar(ch) {
+  if (ch == null) {
+    return false;
+  }
+  return /\w/.test(ch);
+}
+
+// ---------------------------------------------------------------------------
+// Inline parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Match a fullwidth bracket citation 【id】 at position `i`.
+ * Returns the sourceId and end index, or null if no match.
+ */
+function matchFullwidthCitation(text, i, opts) {
+  if (!opts.sourceIds || text[i] !== '\u3010') {
+    return null;
+  }
+  const closeIndex = text.indexOf('\u3011', i + 1);
+  if (closeIndex === -1) {
+    return null;
+  }
+  const id = text.slice(i + 1, closeIndex);
+  if (id.length === 0 || !opts.sourceIds.has(id)) {
+    return null;
+  }
+  return {
+    sourceId: id,
+    end: closeIndex + 1
+  };
+}
+
+/**
+ * Match a bracket citation [id] at position `i`.
+ * Only matches if the id exists in sourceIds and is NOT followed by `(` (link).
+ */
+function matchBracketCitation(text, i, opts) {
+  if (!opts.sourceIds || text[i] !== '[') {
+    return null;
+  }
+  const closeIndex = text.indexOf(']', i + 1);
+  if (closeIndex === -1) {
+    return null;
+  }
+  if (text[closeIndex + 1] === '(') {
+    return null;
+  }
+  const id = text.slice(i + 1, closeIndex);
+  if (id.length === 0 || !opts.sourceIds.has(id)) {
+    return null;
+  }
+  return {
+    sourceId: id,
+    end: closeIndex + 1
+  };
+}
+export function parseInline(text, arg) {
+  return parseInlineEntry(text, resolveOptions(arg));
+}
+
+/**
+ * Internal block-level inline entry point: parses, then applies the GFM
+ * autolink transform when enabled. Recursive calls inside `parseInlineImpl`
+ * (link labels, bold/italic/strikethrough bodies) intentionally bypass this
+ * wrapper and call `parseInlineImpl` directly so the transform runs only on
+ * the outermost block's inline tree — letting `transformAutolinks` decide
+ * which subtrees to descend into (text, bold, italic, strikethrough) and
+ * which to skip (link, code, image, citation, break).
+ */
+function parseInlineEntry(text, opts) {
+  const nodes = parseInlineImpl(text, opts);
+  return opts.autolink === 'gfm' ? transformAutolinks(nodes) : nodes;
+}
+function parseInlineImpl(text, opts) {
+  const nodes = [];
+  let i = 0;
+  while (i < text.length) {
+    // --- Escape ---
+    if (text[i] === '\\' && i + 1 < text.length) {
+      nodes.push({
+        type: 'text',
+        content: text[i + 1]
+      });
+      i += 2;
+      continue;
+    }
+
+    // --- Inline code ---
+    if (text[i] === '`') {
+      const tickCount = text[i + 1] === '`' ? text[i + 2] === '`' ? 3 : 2 : 1;
+      const openIndex = i + tickCount;
+      const closeIndex = text.indexOf('`'.repeat(tickCount), openIndex);
+      if (closeIndex !== -1) {
+        nodes.push({
+          type: 'code',
+          content: text.slice(openIndex, closeIndex)
+        });
+        i = closeIndex + tickCount;
+        continue;
+      }
+    }
+
+    // --- Citation: fullwidth 【id】 ---
+    {
+      const citation = matchFullwidthCitation(text, i, opts);
+      if (citation) {
+        nodes.push({
+          type: 'citation',
+          sourceId: citation.sourceId
+        });
+        i = citation.end;
+        continue;
+      }
+    }
+
+    // --- Image ![alt](src) ---
+    if (text[i] === '!' && text[i + 1] === '[') {
+      const altClose = text.indexOf(']', i + 2);
+      if (altClose !== -1 && text[altClose + 1] === '(') {
+        const srcClose = findClosingParen(text, altClose + 2);
+        if (srcClose !== -1) {
+          nodes.push({
+            type: 'image',
+            src: text.slice(altClose + 2, srcClose),
+            alt: text.slice(i + 2, altClose)
+          });
+          i = srcClose + 1;
+          continue;
+        }
+      }
+    }
+
+    // --- Citation: bracket [id] (before link — link requires `(` after `]`) ---
+    {
+      const citation = matchBracketCitation(text, i, opts);
+      if (citation) {
+        nodes.push({
+          type: 'citation',
+          sourceId: citation.sourceId
+        });
+        i = citation.end;
+        continue;
+      }
+    }
+
+    // --- Link [text](url) ---
+    if (text[i] === '[') {
+      const textClose = text.indexOf(']', i + 1);
+      if (textClose !== -1 && text[textClose + 1] === '(') {
+        const urlClose = findClosingParen(text, textClose + 2);
+        if (urlClose !== -1) {
+          nodes.push({
+            type: 'link',
+            href: text.slice(textClose + 2, urlClose),
+            children: parseInlineImpl(text.slice(i + 1, textClose), opts)
+          });
+          i = urlClose + 1;
+          continue;
+        }
+      }
+    }
+
+    // --- Bold-italic: *** or ___ ---
+    if (text[i] === '*' && text[i + 1] === '*' && text[i + 2] === '*' || text[i] === '_' && text[i + 1] === '_' && text[i + 2] === '_') {
+      const marker = text.slice(i, i + 3);
+      const isUnderscore = text[i] === '_';
+      if (isUnderscore && isWordChar(text[i - 1])) {
+        // mid-word underscore — fall through
+      } else {
+        const closeIndex = text.indexOf(marker, i + 3);
+        if (closeIndex !== -1 && (!isUnderscore || !isWordChar(text[closeIndex + 3]))) {
+          nodes.push({
+            type: 'bold',
+            children: [{
+              type: 'italic',
+              children: parseInlineImpl(text.slice(i + 3, closeIndex), opts)
+            }]
+          });
+          i = closeIndex + 3;
+          continue;
+        }
+      }
+    }
+
+    // --- Bold: ** or __ ---
+    if (text[i] === '*' && text[i + 1] === '*' || text[i] === '_' && text[i + 1] === '_') {
+      const marker = text.slice(i, i + 2);
+      const isUnderscore = text[i] === '_';
+      if (isUnderscore && isWordChar(text[i - 1])) {
+        // mid-word underscore — fall through
+      } else {
+        const closeIndex = text.indexOf(marker, i + 2);
+        if (closeIndex !== -1 && (!isUnderscore || !isWordChar(text[closeIndex + 2]))) {
+          nodes.push({
+            type: 'bold',
+            children: parseInlineImpl(text.slice(i + 2, closeIndex), opts)
+          });
+          i = closeIndex + 2;
+          continue;
+        }
+      }
+    }
+
+    // --- Strikethrough: ~~ ---
+    if (text[i] === '~' && text[i + 1] === '~') {
+      const closeIndex = text.indexOf('~~', i + 2);
+      if (closeIndex !== -1) {
+        nodes.push({
+          type: 'strikethrough',
+          children: parseInlineImpl(text.slice(i + 2, closeIndex), opts)
+        });
+        i = closeIndex + 2;
+        continue;
+      }
+    }
+
+    // --- Italic: * or _ ---
+    if (text[i] === '*' || text[i] === '_') {
+      const isUnderscore = text[i] === '_';
+      if (isUnderscore && isWordChar(text[i - 1])) {
+        // mid-word underscore — fall through
+      } else {
+        const closeIndex = text.indexOf(text[i], i + 1);
+        if (closeIndex !== -1 && closeIndex > i + 1 && (!isUnderscore || !isWordChar(text[closeIndex + 1]))) {
+          nodes.push({
+            type: 'italic',
+            children: parseInlineImpl(text.slice(i + 1, closeIndex), opts)
+          });
+          i = closeIndex + 1;
+          continue;
+        }
+      }
+    }
+
+    // --- Plain text (with line-break detection) ---
+    let end = i + 1;
+    while (end < text.length && !'*_~`[!\\\n\u3010'.includes(text[end])) {
+      end++;
+    }
+    const content = text.slice(i, end);
+
+    // Detect trailing-space line break: 2+ spaces immediately before \n
+    if (end < text.length && text[end] === '\n') {
+      const trimmed = content.replace(/ +$/, '');
+      if (content.length - trimmed.length >= 2) {
+        if (trimmed.length > 0) {
+          const last = nodes[nodes.length - 1];
+          if (last?.type === 'text') {
+            last.content += trimmed;
+          } else {
+            nodes.push({
+              type: 'text',
+              content: trimmed
+            });
+          }
+        }
+        nodes.push({
+          type: 'break'
+        });
+        i = end + 1;
+        continue;
+      }
+    }
+    const last = nodes[nodes.length - 1];
+    if (last?.type === 'text') {
+      last.content += content;
+    } else {
+      nodes.push({
+        type: 'text',
+        content
+      });
+    }
+    i = end;
+  }
+  return nodes;
+}
+
+// ---------------------------------------------------------------------------
+// GFM autolink post-pass (opt-in via ParseOptions.autolink === 'gfm')
+// ---------------------------------------------------------------------------
+
+// Character classes used in autolink patterns.
+const ANY_NON_WHITESPACE_OR_ANGLE = '[^\\s<]+';
+const SCHEME = 'https?:\\/\\/';
+const EMAIL_LOCAL_PART = '[A-Za-z0-9._%+-]+';
+const DOMAIN_LABEL = '[A-Za-z0-9-]+';
+const DOMAIN_WITH_DOT = `${DOMAIN_LABEL}(?:\\.${DOMAIN_LABEL})+`;
+const ANGLE_SCHEME = '[a-zA-Z][a-zA-Z0-9+.-]*';
+const ANGLE_URL_BODY = '[^<>\\s]*';
+
+/** Bare http(s) URL up to whitespace or `<`. Trailing punctuation is peeled afterwards. */
+const URL_LITERAL_RE = new RegExp(`${SCHEME}${ANY_NON_WHITESPACE_OR_ANGLE}`, 'g');
+
+/** Bare www. URL. Resulting href gets `http://` prepended. */
+const WWW_LITERAL_RE = new RegExp(`www\\.${ANY_NON_WHITESPACE_OR_ANGLE}`, 'g');
+
+/** Bare email: local-part@domain (at least one dot in domain). */
+const EMAIL_LITERAL_RE = new RegExp(`${EMAIL_LOCAL_PART}@${DOMAIN_WITH_DOT}`, 'g');
+
+/** Angle-bracket autolink: `<scheme:url>` (CommonMark §6.5). */
+const ANGLE_URL_RE = new RegExp(`<(${ANGLE_SCHEME}:${ANGLE_URL_BODY})>`, 'g');
+
+/** Angle-bracket email: `<user@host.tld>`. */
+const ANGLE_EMAIL_RE = new RegExp(`<(${EMAIL_LOCAL_PART}@${DOMAIN_WITH_DOT})>`, 'g');
+
+/** Characters treated as trailing sentence punctuation per GFM §6.9. */
+const TRAILING_PUNCT_CHARS = new Set('?!.,:*_~');
+
+/** Characters valid in an email local part (used for boundary detection). */
+const EMAIL_LOCAL_CHARS = new Set('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._%+-@');
+/**
+ * Peel trailing sentence-end punctuation and unbalanced trailing `)` off a
+ * bare URL. Mirrors GFM §6.9: `?!.,:*_~` immediately after the URL aren't
+ * part of it; a trailing `)` is excluded if there are more `)` than `(` in
+ * the candidate (so `(https://example.com)` ends at the second `)` but
+ * `https://example.com/Foo_(bar)` keeps the inner pair).
+ */
+function peelTrailingPunctAndParens(url) {
+  let s = url;
+  while (s.length > 0) {
+    // Peel trailing punctuation characters in one pass.
+    if (TRAILING_PUNCT_CHARS.has(s[s.length - 1])) {
+      let end = s.length - 1;
+      while (end > 0 && TRAILING_PUNCT_CHARS.has(s[end - 1])) {
+        end--;
+      }
+      s = s.slice(0, end);
+      continue;
+    }
+    if (s.endsWith(')')) {
+      let open = 0;
+      let close = 0;
+      for (let idx = 0; idx < s.length; idx++) {
+        if (s[idx] === '(') {
+          open++;
+        } else if (s[idx] === ')') {
+          close++;
+        }
+      }
+      if (close > open) {
+        s = s.slice(0, -1);
+        continue;
+      }
+    }
+    break;
+  }
+  return s;
+}
+
+/** Characters that, when preceding a URL, indicate it's part of a larger token. */
+const URL_CONTINUATION_CHARS = new Set('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789/=');
+
+/**
+ * The character immediately before a bare-URL or bare-www match must not
+ * make the URL look like the tail of a larger token (`xhttps`, `=https://`,
+ * `/https://`). null means start-of-text — always allowed.
+ */
+function isUrlBoundaryChar(ch) {
+  if (ch == null) {
+    return true;
+  }
+  return !URL_CONTINUATION_CHARS.has(ch);
+}
+function scanAutolinksInText(text) {
+  const matches = [];
+
+  // <scheme:url> angle-bracket form
+  {
+    const re = new RegExp(ANGLE_URL_RE.source, 'g');
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      const url = m[1];
+      matches.push({
+        start: m.index,
+        end: m.index + m[0].length,
+        href: url,
+        display: url
+      });
+    }
+  }
+
+  // <email> angle-bracket form
+  {
+    const re = new RegExp(ANGLE_EMAIL_RE.source, 'g');
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      const email = m[1];
+      matches.push({
+        start: m.index,
+        end: m.index + m[0].length,
+        href: `mailto:${email}`,
+        display: email
+      });
+    }
+  }
+
+  // bare https?:// URL
+  {
+    const re = new RegExp(URL_LITERAL_RE.source, 'g');
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      const prev = text[m.index - 1];
+      if (!isUrlBoundaryChar(prev)) {
+        continue;
+      }
+      if (text.slice(m.index - 2, m.index) === '](') {
+        continue;
+      }
+      const cleaned = peelTrailingPunctAndParens(m[0]);
+      if (cleaned.length === 0) {
+        continue;
+      }
+      matches.push({
+        start: m.index,
+        end: m.index + cleaned.length,
+        href: cleaned,
+        display: cleaned
+      });
+    }
+  }
+
+  // bare www. URL
+  {
+    const re = new RegExp(WWW_LITERAL_RE.source, 'g');
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      const prev = text[m.index - 1];
+      if (!isUrlBoundaryChar(prev)) {
+        continue;
+      }
+      // Don't match inside an https://www… capture from the previous pattern
+      if (text.slice(m.index - 3, m.index) === '://') {
+        continue;
+      }
+      const cleaned = peelTrailingPunctAndParens(m[0]);
+      if (cleaned.length === 0) {
+        continue;
+      }
+      matches.push({
+        start: m.index,
+        end: m.index + cleaned.length,
+        href: `http://${cleaned}`,
+        display: cleaned
+      });
+    }
+  }
+
+  // bare email
+  {
+    const re = new RegExp(EMAIL_LITERAL_RE.source, 'g');
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      const prev = text[m.index - 1];
+      // Reject if previous char could be part of the local part or sits in
+      // a position that would make this match continuation of something
+      // bigger (`name@x.y@host`, `foo+bar@x`, `mailto:user@host`).
+      if (prev != null && EMAIL_LOCAL_CHARS.has(prev)) {
+        continue;
+      }
+      if (text.slice(Math.max(0, m.index - 7), m.index) === 'mailto:') {
+        continue;
+      }
+      matches.push({
+        start: m.index,
+        end: m.index + m[0].length,
+        href: `mailto:${m[0]}`,
+        display: m[0]
+      });
+    }
+  }
+
+  // Sort by start; first-match-wins on overlaps so e.g. an angle-bracket
+  // <https://x> outranks the bare https://x inside it.
+  matches.sort((a, b) => a.start - b.start);
+  const resolved = [];
+  let lastEnd = 0;
+  for (const m of matches) {
+    if (m.start >= lastEnd) {
+      resolved.push(m);
+      lastEnd = m.end;
+    }
+  }
+  return resolved;
+}
+
+/**
+ * Split a text-node `content` string into a sequence of text + link nodes
+ * based on autolink matches.
+ */
+function splitTextOnAutolinks(content) {
+  const matches = scanAutolinksInText(content);
+  if (matches.length === 0) {
+    return [{
+      type: 'text',
+      content
+    }];
+  }
+  const out = [];
+  let cursor = 0;
+  for (const m of matches) {
+    if (m.start > cursor) {
+      out.push({
+        type: 'text',
+        content: content.slice(cursor, m.start)
+      });
+    }
+    out.push({
+      type: 'link',
+      href: m.href,
+      children: [{
+        type: 'text',
+        content: m.display
+      }]
+    });
+    cursor = m.end;
+  }
+  if (cursor < content.length) {
+    out.push({
+      type: 'text',
+      content: content.slice(cursor)
+    });
+  }
+  return out;
+}
+
+/**
+ * Walk an inline-node tree and replace bare URLs / emails inside `text`
+ * nodes with `link` nodes. Recurses into emphasis containers
+ * (`bold`/`italic`/`strikethrough`) so wrapped URLs link too, but never
+ * descends into existing `link` children (no nested links), `code` content,
+ * `image` alt text, `citation`, or `break`. Runs only on the outermost
+ * block's inline tree (see `parseInlineEntry`).
+ */
+function transformAutolinks(nodes) {
+  const out = [];
+  for (const node of nodes) {
+    if (node.type === 'text') {
+      const split = splitTextOnAutolinks(node.content);
+      for (const seg of split) {
+        const last = out[out.length - 1];
+        if (seg.type === 'text' && last?.type === 'text') {
+          last.content += seg.content;
+        } else {
+          out.push(seg);
+        }
+      }
+    } else if (node.type === 'bold' || node.type === 'italic' || node.type === 'strikethrough') {
+      out.push({
+        ...node,
+        children: transformAutolinks(node.children)
+      });
+    } else {
+      out.push(node);
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Block parser helpers
+// ---------------------------------------------------------------------------
+
+function getIndent(line) {
+  let count = 0;
+  while (count < line.length && line[count] === ' ') {
+    count++;
+  }
+  return count;
+}
+
+/** HR: 3+ identical markers (-, *, _) optionally separated by spaces. */
+function isHorizontalRule(line) {
+  const trimmed = line.trim();
+  if (trimmed.length < 3) {
+    return false;
+  }
+  const stripped = trimmed.replace(/ /g, '');
+  if (stripped.length < 3) {
+    return false;
+  }
+  const ch = stripped[0];
+  if (ch !== '-' && ch !== '*' && ch !== '_') {
+    return false;
+  }
+  for (let idx = 1; idx < stripped.length; idx++) {
+    if (stripped[idx] !== ch) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** GFM separator row: cells contain only dashes/colons. */
+function isTableSeparator(line) {
+  if (!line.includes('|')) {
+    return false;
+  }
+  const cells = line.split('|').map(cell => cell.trim());
+  const nonEmpty = cells.filter(cell => cell.length > 0);
+  return nonEmpty.length > 0 && nonEmpty.every(cell => /^:?-+:?$/.test(cell));
+}
+
+/**
+ * Returns true when a line could start a new block — used to stop paragraph
+ * continuation.  Every regex here uses bounded or single-class quantifiers
+ * to avoid ReDoS.
+ */
+function isBlockStart(line) {
+  if (/^#{1,6} /.test(line)) {
+    return true;
+  }
+  if (/^(`{3,}|~{3,})/.test(line)) {
+    return true;
+  }
+  if (isHorizontalRule(line)) {
+    return true;
+  }
+  if (line.startsWith('> ') || line === '>') {
+    return true;
+  }
+  if (/^ {0,9}[-*+] /.test(line)) {
+    return true;
+  }
+  if (/^ {0,9}0*1[.)] /.test(line)) {
+    return true;
+  }
+  if (line.includes('|')) {
+    return true;
+  }
+  return false;
+}
+function splitTableRow(line) {
+  let start = 0;
+  let end = line.length;
+  if (line.startsWith('|')) {
+    start = 1;
+    while (start < end && line[start] === ' ') {
+      start++;
+    }
+  }
+  while (end > start && line[end - 1] === ' ') {
+    end--;
+  }
+  if (end > start && line[end - 1] === '|') {
+    end--;
+  }
+  // Split on unescaped pipes (not preceded by backslash)
+  const content = line.slice(start, end);
+  const cells = [];
+  let current = '';
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === '\\' && i + 1 < content.length && content[i + 1] === '|') {
+      // Escaped pipe — keep the backslash-pipe literal for parseInline to handle
+      current += '\\|';
+      i++;
+    } else if (content[i] === '|') {
+      cells.push(current.trim());
+      current = '';
+    } else {
+      current += content[i];
+    }
+  }
+  cells.push(current.trim());
+  return cells;
+}
+function parseTable(lines, lineIndex, opts) {
+  const headers = splitTableRow(lines[lineIndex]).map(cell => ({
+    children: parseInlineEntry(cell, opts)
+  }));
+  const alignments = splitTableRow(lines[lineIndex + 1]).map(cell => {
+    const trimmed = cell.trim();
+    const leftAligned = trimmed.startsWith(':');
+    const rightAligned = trimmed.endsWith(':');
+    return leftAligned && rightAligned ? 'center' : rightAligned ? 'right' : leftAligned ? 'left' : null;
+  });
+  const rows = [];
+  let rowIndex = lineIndex + 2;
+  while (rowIndex < lines.length && lines[rowIndex].includes('|') && lines[rowIndex].trim() !== '') {
+    rows.push(splitTableRow(lines[rowIndex]).map(cell => ({
+      children: parseInlineEntry(cell, opts)
+    })));
+    rowIndex++;
+  }
+  return {
+    node: {
+      type: 'table',
+      headers,
+      alignments,
+      rows
+    },
+    nextIndex: rowIndex
+  };
+}
+function parseList(lines, startIndex, ordered, opts) {
+  const items = [];
+  const baseIndent = getIndent(lines[startIndex]);
+  // Ordered lists may use either '.' or ')' as the marker delimiter
+  // (CommonMark 5.2). Capture which one this list starts with so its items
+  // must all share it — a change of delimiter starts a new list.
+  const orderedStart = ordered ? lines[startIndex].match(/^ *(\d+)([.)]) /) : null;
+  const delim = orderedStart ? orderedStart[2] : '.';
+  const escDelim = `\\${delim}`;
+  const itemPattern = ordered ? new RegExp(`^ {${baseIndent}}\\d+${escDelim} `) : new RegExp(`^ {${baseIndent}}[-*+] `);
+  const start = orderedStart ? parseInt(orderedStart[1], 10) : undefined;
+  let loose = false;
+  let index = startIndex;
+  while (index < lines.length && itemPattern.test(lines[index])) {
+    const content = ordered ? lines[index].replace(new RegExp(`^ *\\d+${escDelim} `), '') : lines[index].replace(/^ *[-*+] /, '');
+    const taskMatch = content.match(/^\[([ xX])\] (.*)/);
+    let checked;
+    let itemText;
+    if (taskMatch) {
+      checked = taskMatch[1].toLowerCase() === 'x';
+      itemText = taskMatch[2];
+    } else {
+      itemText = content;
+    }
+    index++;
+
+    // Collect sub-content (nested items or continuation lines)
+    const subLines = [];
+    while (index < lines.length && lines[index].trim() !== '' && getIndent(lines[index]) > baseIndent) {
+      subLines.push(lines[index]);
+      index++;
+    }
+    if (subLines.length > 0) {
+      const minSubIndent = Math.min(...subLines.map(subLine => getIndent(subLine)));
+      const deindented = subLines.map(subLine => subLine.slice(minSubIndent));
+      itemText += '\n' + deindented.join('\n');
+    }
+    items.push({
+      checked,
+      children: parseMarkdownImpl(itemText, opts)
+    });
+
+    // CommonMark loose list: blank line(s) between items of the same style
+    // and indent still form one list. Skip the blanks and continue if the
+    // next non-blank line matches the same item pattern.
+    let lookahead = index;
+    while (lookahead < lines.length && lines[lookahead].trim() === '') {
+      lookahead++;
+    }
+    if (lookahead > index && lookahead < lines.length && itemPattern.test(lines[lookahead])) {
+      loose = true;
+      index = lookahead;
+    }
+  }
+  return {
+    node: {
+      type: 'list',
+      ordered,
+      start,
+      delimiter: ordered ? delim : undefined,
+      loose: loose || undefined,
+      items
+    },
+    nextIndex: index
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main block parser
+// ---------------------------------------------------------------------------
+
+export function parseMarkdown(input, arg) {
+  return parseMarkdownImpl(input, resolveOptions(arg));
+}
+function parseMarkdownImpl(input, opts) {
+  const lines = input.split('\n');
+  const blocks = [];
+  let index = 0;
+  while (index < lines.length) {
+    const line = lines[index];
+    if (line.trim() === '') {
+      index++;
+      continue;
+    }
+
+    // --- Fenced code block ---
+    const fenceMatch = line.match(/^(`{3,}|~{3,})(\w*)/);
+    if (fenceMatch) {
+      const fence = fenceMatch[1];
+      const language = fenceMatch[2] || 'plaintext';
+      const codeLines = [];
+      index++;
+      while (index < lines.length && !lines[index].startsWith(fence)) {
+        codeLines.push(lines[index]);
+        index++;
+      }
+      index++; // skip closing fence
+      blocks.push({
+        type: 'codeblock',
+        language,
+        content: codeLines.join('\n')
+      });
+      continue;
+    }
+
+    // --- Heading ---
+    const headingMatch = line.match(/^(#{1,6}) +(.*)/);
+    if (headingMatch) {
+      blocks.push({
+        type: 'heading',
+        level: headingMatch[1].length,
+        children: parseInlineEntry(headingMatch[2], opts)
+      });
+      index++;
+      continue;
+    }
+
+    // --- HR (must precede list check to handle `- - -`, `* * *`, `_ _ _`) ---
+    if (isHorizontalRule(line)) {
+      blocks.push({
+        type: 'hr'
+      });
+      index++;
+      continue;
+    }
+
+    // --- Standalone image ---
+    const imageMatch = line.match(/^!\[([^\]]*)\]\(([^)]+)\)/);
+    if (imageMatch && line.trim() === imageMatch[0]) {
+      blocks.push({
+        type: 'image',
+        alt: imageMatch[1],
+        src: imageMatch[2]
+      });
+      index++;
+      continue;
+    }
+
+    // --- Table (with or without leading pipe) ---
+    if (index + 1 < lines.length && line.includes('|') && isTableSeparator(lines[index + 1])) {
+      const tableResult = parseTable(lines, index, opts);
+      blocks.push(tableResult.node);
+      index = tableResult.nextIndex;
+      continue;
+    }
+
+    // --- Blockquote ---
+    if (line.startsWith('> ') || line === '>') {
+      const quoteLines = [];
+      while (index < lines.length && (lines[index].startsWith('> ') || lines[index] === '>')) {
+        quoteLines.push(lines[index].replace(/^> ?/, ''));
+        index++;
+      }
+      blocks.push({
+        type: 'blockquote',
+        children: parseMarkdownImpl(quoteLines.join('\n'), opts)
+      });
+      continue;
+    }
+
+    // --- Unordered list ---
+    if (/^ {0,9}[-*+] /.test(line)) {
+      const listResult = parseList(lines, index, false, opts);
+      blocks.push(listResult.node);
+      index = listResult.nextIndex;
+      continue;
+    }
+
+    // --- Ordered list ---
+    if (/^ {0,9}\d+[.)] /.test(line)) {
+      const listResult = parseList(lines, index, true, opts);
+      blocks.push(listResult.node);
+      index = listResult.nextIndex;
+      continue;
+    }
+
+    // --- Paragraph ---
+    const paraLines = [line];
+    index++;
+    while (index < lines.length && !isBlockStart(lines[index]) && lines[index].trim() !== '') {
+      paraLines.push(lines[index]);
+      index++;
+    }
+    blocks.push({
+      type: 'paragraph',
+      children: parseInlineEntry(paraLines.join('\n'), opts)
+    });
+  }
+  return blocks;
+}
+
+// ---------------------------------------------------------------------------
+// Incremental parsing
+// ---------------------------------------------------------------------------
+
+export function createIncrementalState() {
+  return {
+    prevInput: '',
+    settledText: '',
+    settledBlocks: [],
+    settledUpTo: 0
+  };
+}
+
+/**
+ * Find the line-index of the last blank line that is NOT inside a fenced code
+ * block.  Returns -1 when nothing is settled (unclosed fence or no blank line).
+ */
+function findSettledBoundary(lines) {
+  let inFence = false;
+  let fenceMarker = '';
+  let lastBoundary = -1;
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+    const line = lines[lineIndex];
+
+    // Fence open / close — match the specific marker character and length
+    const fenceMatch = line.match(/^(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      if (!inFence) {
+        inFence = true;
+        fenceMarker = fenceMatch[1];
+      } else if (fenceMatch[1].startsWith(fenceMarker[0]) && fenceMatch[1].length >= fenceMarker.length) {
+        inFence = false;
+        fenceMarker = '';
+      }
+    }
+    if (!inFence && line.trim() === '' && lineIndex > 0) {
+      lastBoundary = lineIndex;
+    }
+  }
+  return inFence ? -1 : lastBoundary;
+}
+
+/**
+ * Strip trailing incomplete inline syntax that appears during streaming.
+ * Only affects the tail of the last line — safe to apply to the full string.
+ */
+export function trimStreamingArtifacts(input) {
+  const lastNL = input.lastIndexOf('\n');
+  const prefix = lastNL === -1 ? '' : input.slice(0, lastNL + 1);
+  let tail = lastNL === -1 ? input : input.slice(lastNL + 1);
+
+  // Scan backwards for unclosed syntax markers — no regex to avoid ReDoS
+  // Find the last unclosed [ or ![ (link/image start)
+  const lastBracket = tail.lastIndexOf('[');
+  if (lastBracket !== -1) {
+    const afterBracket = tail.slice(lastBracket);
+    // A closed link/image has ](...)  somewhere after the [
+    const hasClose = afterBracket.includes('](') && afterBracket.includes(')');
+    if (!hasClose) {
+      // Also trim a preceding `!` for images
+      const trimTo = lastBracket > 0 && tail[lastBracket - 1] === '!' ? lastBracket - 1 : lastBracket;
+      tail = tail.slice(0, trimTo);
+    }
+  }
+
+  // Find trailing unclosed backticks
+  let end = tail.length;
+  while (end > 0 && tail[end - 1] === '`') {
+    end--;
+  }
+  if (end < tail.length && end > 0) {
+    // There are trailing backticks — check if they opened inline code
+    const ticks = tail.length - end;
+    const opener = tail.lastIndexOf('`'.repeat(ticks), end - 1);
+    if (opener === -1) {
+      // Unclosed — trim from the backticks
+      tail = tail.slice(0, end);
+    }
+  }
+
+  // Find trailing unclosed bold/italic markers (*)
+  // First check trailing stars (no content after them yet):
+  end = tail.length;
+  while (end > 0 && tail[end - 1] === '*') {
+    end--;
+  }
+  if (end < tail.length && end > 0) {
+    const stars = tail.length - end;
+    if (stars <= 3) {
+      const opener = tail.lastIndexOf('*'.repeat(stars), end - 1);
+      if (opener === -1) {
+        tail = tail.slice(0, end);
+      }
+    }
+  }
+
+  // Check for unclosed bold/italic mid-line: e.g. "Hello **bold" or "Hello *ital"
+  // Instead of trimming (hiding content), auto-close the markers so the text
+  // renders with formatting immediately as it streams in.
+  {
+    let searchFrom = 0;
+    const markers = [];
+    while (searchFrom < tail.length) {
+      const idx = tail.indexOf('*', searchFrom);
+      if (idx === -1) {
+        break;
+      }
+      // Determine marker length (* or ** or ***)
+      let markerLen = 1;
+      while (idx + markerLen < tail.length && tail[idx + markerLen] === '*') {
+        markerLen++;
+      }
+      if (markerLen > 3) {
+        // 4+ stars — not standard markdown emphasis, skip
+        searchFrom = idx + markerLen;
+        continue;
+      }
+      markers.push({
+        pos: idx,
+        len: markerLen
+      });
+      searchFrom = idx + markerLen;
+    }
+    // Pair markers greedily. Unpaired openers get auto-closed.
+    const paired = new Set();
+    for (let i = 0; i < markers.length; i++) {
+      if (paired.has(i)) {
+        continue;
+      }
+      for (let j = i + 1; j < markers.length; j++) {
+        if (paired.has(j)) {
+          continue;
+        }
+        if (markers[j].len === markers[i].len) {
+          paired.add(i);
+          paired.add(j);
+          break;
+        }
+      }
+    }
+    // Append closing markers for each unpaired opener (in reverse order)
+    for (let i = markers.length - 1; i >= 0; i--) {
+      if (!paired.has(i)) {
+        const marker = markers[i];
+        // Only close if there's actual content after the opener
+        if (marker.pos + marker.len < tail.length) {
+          tail = tail + '*'.repeat(marker.len);
+        } else {
+          // Trailing marker with no content — trim it
+          tail = tail.slice(0, marker.pos);
+        }
+      }
+    }
+  }
+
+  // Find trailing unclosed strikethrough (~~)
+  if (tail.length >= 2 && tail.endsWith('~~')) {
+    // Check if there's an opener before these closing ~~
+    const opener = tail.lastIndexOf('~~', tail.length - 3);
+    if (opener === -1) {
+      tail = tail.slice(0, -2);
+    }
+  } else if (tail.endsWith('~')) {
+    // Single trailing ~ after content — might be start of ~~
+    const secondLast = tail.length - 2;
+    if (secondLast >= 0 && tail[secondLast] !== '~') {
+      tail = tail.slice(0, -1);
+    }
+  }
+
+  // Check for unclosed ~~ mid-line: e.g. "Hello ~~struck"
+  // Count ~~ occurrences — if odd, the last one is unclosed.
+  {
+    let count = 0;
+    let searchFrom = 0;
+    const positions = [];
+    while (true) {
+      const idx = tail.indexOf('~~', searchFrom);
+      if (idx === -1) {
+        break;
+      }
+      positions.push(idx);
+      count++;
+      searchFrom = idx + 2;
+    }
+    if (count % 2 === 1) {
+      // Odd number of ~~ — the last one is unclosed, trim from it
+      tail = tail.slice(0, positions[positions.length - 1]);
+    }
+  }
+  return prefix + tail;
+}
+
+/**
+ * Trim trailing lines from the unsettled zone that look like the start of
+ * a structural block but aren't complete yet. This prevents flashes of
+ * partial syntax like bare `-` bullets or incomplete table headers.
+ *
+ * Only trims the minimal set of clearly-incomplete patterns:
+ * 1. Bare list markers (`- `, `1. `) with no content after them
+ * 2. A lone table header line without its separator row
+ * 3. Empty trailing lines
+ *
+ * Once a table is established (header + separator exist), new data rows
+ * render immediately — no suppression.
+ */
+function trimUnsettledStructural(text) {
+  const lines = text.split('\n');
+
+  // Walk backwards, but only trim clearly-incomplete trailing lines
+  while (lines.length > 0) {
+    const last = lines[lines.length - 1];
+    const trimmed = last.trim();
+
+    // Empty trailing lines — safe to drop
+    if (trimmed === '') {
+      lines.pop();
+      continue;
+    }
+
+    // Bare list marker with no content: "- " or "1. " (just whitespace after marker)
+    if (/^ {0,9}[-*+] $/.test(last) || /^ {0,9}\d+[.)] $/.test(last)) {
+      lines.pop();
+      continue;
+    }
+
+    // Table: only suppress if this is a lone header without a separator.
+    // If the line has `|` and the line before it is NOT a separator,
+    // and THIS line is not a separator, and there's no established table
+    // above (header + separator pair), hold it back.
+    if (trimmed.includes('|') && !isTableSeparator(last)) {
+      // Is there a separator anywhere above that would make this part of
+      // an established table? Walk up to find header+separator pair.
+      let tableEstablished = false;
+      for (let i = lines.length - 2; i >= 1; i--) {
+        if (isTableSeparator(lines[i]) && lines[i - 1].includes('|')) {
+          tableEstablished = true;
+          break;
+        }
+      }
+      if (!tableEstablished) {
+        // Lone pipe line — could be a table header waiting for separator
+        lines.pop();
+        continue;
+      }
+    }
+
+    // Separator line without a header above it
+    if (isTableSeparator(last)) {
+      if (lines.length < 2 || !lines[lines.length - 2].includes('|')) {
+        lines.pop();
+        continue;
+      }
+    }
+
+    // This line looks complete — stop trimming
+    break;
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Concatenate freshly-parsed delta blocks with previously-settled blocks,
+ * merging adjacent same-style lists into a single loose list. The boundary
+ * detector settles each pre-blank segment independently, so without this
+ * merge an incrementally-streamed `1.\n\n1.\n\n1.` would land as N separate
+ * lists even though the full-text parser joins them per CommonMark §5.3.
+ */
+function mergeSettledBlocks(prev, delta) {
+  if (prev.length === 0 || delta.length === 0) {
+    return [...prev, ...delta];
+  }
+  const prevLast = prev[prev.length - 1];
+  const deltaFirst = delta[0];
+  if (prevLast.type === 'list' && deltaFirst.type === 'list' && prevLast.ordered === deltaFirst.ordered && prevLast.delimiter === deltaFirst.delimiter) {
+    const merged = {
+      type: 'list',
+      ordered: prevLast.ordered,
+      start: prevLast.start,
+      delimiter: prevLast.delimiter,
+      loose: true,
+      items: [...prevLast.items, ...deltaFirst.items]
+    };
+    return [...prev.slice(0, -1), merged, ...delta.slice(1)];
+  }
+  return [...prev, ...delta];
+}
+export function parseMarkdownIncremental(input, state, arg) {
+  const opts = resolveOptions(arg);
+  // Invalidate cache when the autolink option flips — cached settled blocks
+  // were parsed with the previous setting and would otherwise be reused
+  // unchanged.
+  if (state.autolink !== opts.autolink) {
+    state.prevInput = '';
+    state.settledText = '';
+    state.settledBlocks = [];
+    state.settledUpTo = 0;
+    state.autolink = opts.autolink;
+  }
+  if (input === '') {
+    state.prevInput = '';
+    state.settledText = '';
+    state.settledBlocks = [];
+    state.settledUpTo = 0;
+    return [];
+  }
+  const lines = input.split('\n');
+  const boundary = findSettledBoundary(lines);
+  if (boundary < 0) {
+    // Inside an unclosed fence or no blank-line boundary — full re-parse
+    state.prevInput = input;
+    return parseMarkdownImpl(input, opts);
+  }
+  const settledText = lines.slice(0, boundary).join('\n');
+  const unsettledRaw = lines.slice(boundary).join('\n').trim();
+  const unsettledText = trimUnsettledStructural(unsettledRaw);
+  let settledBlocks;
+  if (settledText === state.settledText) {
+    // Settled portion unchanged — reuse cached blocks
+    settledBlocks = state.settledBlocks;
+  } else if (state.settledText.length > 0 && settledText.startsWith(state.settledText)) {
+    // Settled portion grew — parse only the new delta
+    const delta = settledText.slice(state.settledText.length);
+    const deltaBlocks = parseMarkdownImpl(delta, opts);
+    settledBlocks = mergeSettledBlocks(state.settledBlocks, deltaBlocks);
+  } else {
+    // Content before the boundary changed — full re-parse of settled portion
+    settledBlocks = parseMarkdownImpl(settledText, opts);
+  }
+  const unsettledBlocks = unsettledText ? parseMarkdownImpl(unsettledText, opts) : [];
+  state.settledText = settledText;
+  state.settledBlocks = settledBlocks;
+  state.settledUpTo = boundary;
+  state.prevInput = input;
+  return mergeSettledBlocks(settledBlocks, unsettledBlocks);
+}