@astryxdesign/core 0.6.1 → 0.6.2-canary.023c3e4

package/src/Markdown/Markdown.tsx

@@ -4,12 +4,12 @@
 
 /**
  * @file Markdown.tsx
- * @input Markdown string, parser AST types
- * @output Exports Markdown component and MarkdownProps
+ * @input Markdown string, canonical AST, optional plugins and custom renderers
+ * @output Exports Markdown component, MarkdownProps, and renderer contracts
  * @position Core implementation; renders markdown as Astryx components
  */
 
-import {useMemo, useRef} from 'react';
+import {Component, Suspense, useMemo, useRef} from 'react';
 import type React from 'react';
 import {Fragment} from 'react';
 import * as stylex from '@stylexjs/stylex';
@@ -48,20 +48,43 @@ import type {CitationSource} from '../Citation/Citation';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {
-  parseInline,
-  parseMarkdown,
-  parseMarkdownIncremental,
+  parseInlineAst,
+  parseMarkdownAst,
+  parseMarkdownAstIncremental,
   createIncrementalState,
   trimStreamingArtifacts,
-  inlineText,
   slugify,
   uniqueSlug,
 } from './parser';
-import type {BlockNode, InlineNode, IncrementalState} from './parser';
+import type {IncrementalState, MathParseOptions, ParseOptions} from './parser';
+import {getMarkdownAstLegacyCodeLanguage, markdownAstText} from './ast';
+import type {
+  MarkdownAstBlockContent,
+  MarkdownAstPhrasingContent,
+  MarkdownAstTable,
+} from './ast';
+import {
+  applyMarkdownTransforms,
+  getMarkdownExtensionRenderer,
+  markdownExtensionText,
+  prepareMarkdownPlugins,
+  reportMarkdownPluginFailure,
+} from './plugins/protocol';
+import {getMarkdownFenceProposal} from './plugins/semanticFence';
+import type {
+  MarkdownExtensionNode,
+  MarkdownPluginEntry,
+  PreparedMarkdownPlugins,
+} from './plugins/protocol';
+import {sanitizeMarkdownUrl} from './url';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator, type TranslatorFn} from '../i18n';
 
 type SyncReactNode = Exclude<React.ReactNode, Promise<unknown>>;
+type RenderExtensionNode = MarkdownExtensionNode;
+type RenderInlineNode = MarkdownAstPhrasingContent<RenderExtensionNode>;
+type RenderBlockNode = MarkdownAstBlockContent<RenderExtensionNode>;
+type RenderTable = MarkdownAstTable<RenderExtensionNode>;
 
 // ---------------------------------------------------------------------------
 // Props
@@ -70,7 +93,7 @@ type SyncReactNode = Exclude<React.ReactNode, Promise<unknown>>;
 /**
  * A plugin that transforms text patterns into custom React elements
  * inside Markdown. Applied to parsed text nodes only — code blocks,
- * inline code, and other non-prose contexts are unaffected.
+ * inline code, math, and other non-prose contexts are unaffected.
  *
  * Follows Lexical's TextMatchTransformer architecture:
  * - `pattern` for initial regex matching
@@ -102,6 +125,14 @@ export type MarkdownSource = CitationSource;
 export interface MarkdownComponents {
   code?: React.ComponentType<{code: string; language?: string}>;
   inlineCode?: React.ComponentType<{children: string}>;
+  /**
+   * Renders opt-in `$…$` and `$$…$$` math. Supplying this renderer enables
+   * math parsing; Astryx passes the raw expression and does not execute it.
+   */
+  math?: React.ComponentType<{
+    value: string;
+    display: 'inline' | 'block';
+  }>;
   citation?: React.ComponentType<{
     source: CitationSource;
     number: number;
@@ -126,7 +157,9 @@ export interface MarkdownComponents {
   hr?: React.ComponentType<object>;
 }
 
-export interface MarkdownProps extends BaseProps<HTMLElement> {
+export interface MarkdownProps<
+  Plugins extends ReadonlyArray<MarkdownPluginEntry> = readonly [],
+> extends BaseProps<HTMLElement> {
   ref?: React.Ref<HTMLDivElement> | React.Ref<HTMLSpanElement>;
   children: string;
   /**
@@ -183,10 +216,15 @@ export interface MarkdownProps extends BaseProps<HTMLElement> {
   components?: Partial<MarkdownComponents>;
   /**
    * Plugins that transform text patterns into custom React elements.
-   * Applied to text nodes after parsing — code blocks and inline code
+   * Applied to text nodes after parsing — code blocks, inline code, and math
    * are unaffected. Patterns are matched in order; first match wins
    * for overlapping ranges.
    */
+  /** Ordered syntax, immutable transforms, and typed extension renderers. */
+  plugins?: Plugins;
+  /**
+   * Legacy text-match renderers. Unchanged and independent from `plugins`.
+   */
   inlinePlugins?: MarkdownInlinePlugin[];
   /**
    * Opt-in autolinking of bare URLs and emails inside text.
@@ -473,22 +511,25 @@ interface StreamingCursor {
  * Count the total text characters in inline nodes without rendering.
  * Used to advance the cursor past a block that will be faded as a whole unit.
  */
-function countInlineTextLength(nodes: InlineNode[]): number {
+function countInlineTextLength(nodes: ReadonlyArray<RenderInlineNode>): number {
   let len = 0;
   for (const node of nodes) {
     switch (node.type) {
       case 'text':
-        len += node.content.length;
+        len += node.value.length;
         break;
-      case 'code':
-        len += node.content.length;
+      case 'inlineCode':
+        len += node.value.length;
+        break;
+      case 'inlineMath':
+        len += node.value.length;
         break;
       case 'image':
         len += node.alt.length;
         break;
-      case 'bold':
-      case 'italic':
-      case 'strikethrough':
+      case 'strong':
+      case 'emphasis':
+      case 'delete':
       case 'link':
         len += countInlineTextLength(node.children);
         break;
@@ -498,6 +539,9 @@ function countInlineTextLength(nodes: InlineNode[]): number {
       case 'citation':
         len += 1;
         break;
+      case 'extension':
+        len += node.source?.length ?? 0;
+        break;
     }
   }
   return len;
@@ -506,7 +550,7 @@ function countInlineTextLength(nodes: InlineNode[]): number {
 /**
  * Count total text characters in a block node tree.
  */
-function countBlockTextLength(nodes: BlockNode[]): number {
+function countBlockTextLength(nodes: ReadonlyArray<RenderBlockNode>): number {
   let len = 0;
   for (const node of nodes) {
     switch (node.type) {
@@ -514,28 +558,31 @@ function countBlockTextLength(nodes: BlockNode[]): number {
       case 'paragraph':
         len += countInlineTextLength(node.children);
         break;
-      case 'codeblock':
-        len += node.content.length;
+      case 'code':
+        len += node.value.length;
+        break;
+      case 'math':
+        len += node.value.length;
         break;
       case 'blockquote':
         len += countBlockTextLength(node.children);
         break;
       case 'list':
-        for (const item of node.items) {
+        for (const item of node.children) {
           len += countBlockTextLength(item.children);
         }
         break;
       case 'table':
-        for (const h of node.headers) {
-          len += countInlineTextLength(h.children);
-        }
-        for (const row of node.rows) {
-          for (const cell of row) {
+        for (const row of node.children) {
+          for (const cell of row.children) {
             len += countInlineTextLength(cell.children);
           }
         }
         break;
-      case 'hr':
+      case 'extension':
+        len += node.source?.length ?? 0;
+        break;
+      case 'thematicBreak':
         break;
       case 'image':
         len += node.alt.length;
@@ -555,27 +602,6 @@ const headingStyles = {
 } as const;
 
 // ---------------------------------------------------------------------------
-// URL sanitization — block dangerous protocols
-// ---------------------------------------------------------------------------
-
-const DANGEROUS_URL_PATTERN = /^(javascript|data|vbscript):/i;
-
-function sanitizeUrl(url: string): string | null {
-  // Strip control characters before testing, the same normalization the
-  // parser's isSafeUrl applies — the anchored pattern must see the URL the
-  // way a browser will. Return the normalized value so the stripped
-  // characters don't ride along into an attribute or component override.
-  // eslint-disable-next-line no-control-regex -- control chars are the bypass
-  const normalized = url.replace(/[\x00-\x1f\x7f]/g, '').trim();
-  if (normalized.length === 0) {
-    return null;
-  }
-  if (DANGEROUS_URL_PATTERN.test(normalized)) {
-    return null;
-  }
-  return normalized;
-}
-
 // ---------------------------------------------------------------------------
 // Inline plugin matching
 // ---------------------------------------------------------------------------
@@ -681,6 +707,81 @@ function applyInlinePlugins(
   return segments;
 }
 
+interface MarkdownPluginBoundaryProps {
+  children: React.ReactNode;
+  fallback: React.ReactNode;
+  pluginName: string;
+  resetKey: unknown;
+  resetRenderer: unknown;
+}
+
+interface MarkdownPluginBoundaryState {
+  failed: boolean;
+  resetKey: unknown;
+  resetRenderer: unknown;
+}
+
+class MarkdownPluginBoundary extends Component<
+  MarkdownPluginBoundaryProps,
+  MarkdownPluginBoundaryState
+> {
+  state: MarkdownPluginBoundaryState = {
+    failed: false,
+    resetKey: this.props.resetKey,
+    resetRenderer: this.props.resetRenderer,
+  };
+
+  static getDerivedStateFromError(): Partial<MarkdownPluginBoundaryState> {
+    return {failed: true};
+  }
+
+  static getDerivedStateFromProps(
+    props: MarkdownPluginBoundaryProps,
+    state: MarkdownPluginBoundaryState,
+  ): Partial<MarkdownPluginBoundaryState> | null {
+    return props.resetKey === state.resetKey &&
+      props.resetRenderer === state.resetRenderer
+      ? null
+      : {
+          failed: false,
+          resetKey: props.resetKey,
+          resetRenderer: props.resetRenderer,
+        };
+  }
+
+  componentDidCatch(error: unknown): void {
+    reportMarkdownPluginFailure(this.props.pluginName, 'render', error);
+  }
+
+  render(): React.ReactNode {
+    return this.state.failed ? this.props.fallback : this.props.children;
+  }
+}
+
+function useStableMarkdownSyntaxEntries(
+  plugins: PreparedMarkdownPlugins | undefined,
+): ReadonlyArray<MarkdownPluginEntry> | undefined {
+  const identity = plugins?.syntaxIdentity ?? '';
+  const syntaxEntriesRef = useRef<
+    | {
+        identity: string;
+        entries: ReadonlyArray<MarkdownPluginEntry> | undefined;
+      }
+    | undefined
+  >(undefined);
+  if (
+    syntaxEntriesRef.current == null ||
+    syntaxEntriesRef.current.identity !== identity
+  ) {
+    syntaxEntriesRef.current = {
+      identity,
+      entries:
+        plugins == null || identity === '' ? undefined : plugins.syntaxEntries,
+    };
+  }
+  return syntaxEntriesRef.current.entries;
+}
+
 // ---------------------------------------------------------------------------
 // Inline renderer
 // ---------------------------------------------------------------------------
@@ -748,7 +849,7 @@ function getCitationNumber(ctx: CitationContext, sourceId: string): number {
 }
 
 function renderInline(
-  node: InlineNode,
+  node: RenderInlineNode,
   index: number,
   onLinkClick: MarkdownProps['onLinkClick'] | undefined,
   cursor: StreamingCursor,
@@ -756,11 +857,12 @@ function renderInline(
   linkComponent: LinkComponentType = 'a',
   inlinePlugins?: MarkdownInlinePlugin[],
   components?: Partial<MarkdownComponents>,
+  preparedPlugins?: PreparedMarkdownPlugins,
 ): SyncReactNode {
   switch (node.type) {
     case 'text': {
       if (inlinePlugins && inlinePlugins.length > 0) {
-        const segments = applyInlinePlugins(node.content, inlinePlugins);
+        const segments = applyInlinePlugins(node.value, inlinePlugins);
         // If no plugin matched, fall through to the normal path
         // O(1) guard: applyInlinePlugins returns a single text segment when
         // nothing matched — skip the plugin path entirely in that case.
@@ -783,9 +885,9 @@ function renderInline(
           return <Fragment key={index}>{result}</Fragment>;
         }
       }
-      return wrapTextWithFade(node.content, cursor, index);
+      return wrapTextWithFade(node.value, cursor, index);
     }
-    case 'bold':
+    case 'strong':
       return (
         <strong key={index} {...stylex.props(styles.bold)}>
           {node.children.map((c, i) =>
@@ -798,11 +900,12 @@ function renderInline(
               linkComponent,
               inlinePlugins,
               components,
+              preparedPlugins,
             ),
           )}
         </strong>
       );
-    case 'italic':
+    case 'emphasis':
       return (
         <em key={index}>
           {node.children.map((c, i) =>
@@ -815,11 +918,12 @@ function renderInline(
               linkComponent,
               inlinePlugins,
               components,
+              preparedPlugins,
             ),
           )}
         </em>
       );
-    case 'strikethrough':
+    case 'delete':
       return (
         <del key={index} {...stylex.props(styles.strikethrough)}>
           {node.children.map((c, i) =>
@@ -832,23 +936,32 @@ function renderInline(
               linkComponent,
               inlinePlugins,
               components,
+              preparedPlugins,
             ),
           )}
         </del>
       );
-    case 'code': {
+    case 'inlineCode': {
       // Track code content length for cursor but don't split inside code
-      cursor.offset += node.content.length;
+      cursor.offset += node.value.length;
       const InlineCodeComp = components?.inlineCode;
       const codeEl = InlineCodeComp ? (
-        <InlineCodeComp key={index}>{node.content}</InlineCodeComp>
+        <InlineCodeComp key={index}>{node.value}</InlineCodeComp>
       ) : (
-        <Code key={index}>{node.content}</Code>
+        <Code key={index}>{node.value}</Code>
       );
       return codeEl;
     }
+    case 'inlineMath': {
+      const MathComp = components?.math;
+      if (MathComp == null) {
+        return wrapTextWithFade(`$${node.value}$`, cursor, index);
+      }
+      cursor.offset += node.value.length;
+      return <MathComp key={index} value={node.value} display="inline" />;
+    }
     case 'link': {
-      const safeHref = sanitizeUrl(node.href);
+      const safeHref = sanitizeMarkdownUrl(node.url);
       if (safeHref == null) {
         // Unsafe URL — render as plain text
         return (
@@ -863,6 +976,7 @@ function renderInline(
                 linkComponent,
                 inlinePlugins,
                 components,
+                preparedPlugins,
               ),
             )}
           </span>
@@ -882,6 +996,7 @@ function renderInline(
                 linkComponent,
                 inlinePlugins,
                 components,
+                preparedPlugins,
               ),
             )}
           </LinkComp>
@@ -920,13 +1035,14 @@ function renderInline(
               linkComponent,
               inlinePlugins,
               components,
+              preparedPlugins,
             ),
           )}
         </LinkTag>
       );
     }
     case 'image': {
-      const safeSrc = sanitizeUrl(node.src);
+      const safeSrc = sanitizeMarkdownUrl(node.url);
       if (safeSrc == null) {
         return <span key={index}>[{node.alt}]</span>;
       }
@@ -943,6 +1059,34 @@ function renderInline(
         />
       );
     }
+    case 'extension': {
+      const renderer = getMarkdownExtensionRenderer(preparedPlugins, node);
+      const fallback = wrapTextWithFade(
+        node.source ?? markdownExtensionText(preparedPlugins, node),
+        cursor,
+        index,
+      );
+      if (renderer == null) {
+        return fallback;
+      }
+      let rendered: React.ReactNode;
+      try {
+        rendered = renderer.render({node});
+      } catch (error) {
+        reportMarkdownPluginFailure(node.plugin, 'render', error);
+        return fallback;
+      }
+      return (
+        <MarkdownPluginBoundary
+          key={index}
+          pluginName={node.plugin}
+          resetKey={node}
+          resetRenderer={renderer.render}
+          fallback={fallback}>
+          <Suspense fallback={fallback}>{rendered}</Suspense>
+        </MarkdownPluginBoundary>
+      );
+    }
     case 'break':
       cursor.offset += 1;
       return <br key={index} />;
@@ -984,13 +1128,13 @@ function renderInline(
 // ---------------------------------------------------------------------------
 
 function getElementSpacing(
-  node: BlockNode,
+  node: RenderBlockNode,
   density: 'default' | 'compact',
 ): StyleXStyles {
   const compact = density === 'compact';
   switch (node.type) {
     case 'heading':
-      return node.level <= 3
+      return node.depth <= 3
         ? compact
           ? styles.spacingHeadingMajorCompact
           : styles.spacingHeadingMajorDefault
@@ -1001,7 +1145,8 @@ function getElementSpacing(
       return compact
         ? styles.spacingParagraphCompact
         : styles.spacingParagraphDefault;
-    case 'codeblock':
+    case 'code':
+    case 'math':
       return compact
         ? styles.spacingCodeblockCompact
         : styles.spacingCodeblockDefault;
@@ -1013,7 +1158,11 @@ function getElementSpacing(
       return compact ? styles.spacingListCompact : styles.spacingListDefault;
     case 'table':
       return compact ? styles.spacingTableCompact : styles.spacingTableDefault;
-    case 'hr':
+    case 'extension':
+      return compact
+        ? styles.spacingParagraphCompact
+        : styles.spacingParagraphDefault;
+    case 'thematicBreak':
       return compact ? styles.spacingHrCompact : styles.spacingHrDefault;
     case 'image':
       return compact ? styles.spacingImageCompact : styles.spacingImageDefault;
@@ -1028,15 +1177,17 @@ function getElementSpacing(
  * Compute per-column min-widths from table AST content.
  * Buckets: ≤6 chars → 60px, 7–15 → 80px, >15 → 120px.
  */
-function computeTableColumnMinWidths(node: {
-  headers: {children: InlineNode[]}[];
-  rows: {children: InlineNode[]}[][];
-}): number[] {
-  return node.headers.map((h, colIdx) => {
-    let maxLen = countInlineTextLength(h.children);
-    for (const row of node.rows) {
-      if (row[colIdx]) {
-        const len = countInlineTextLength(row[colIdx].children);
+function computeTableColumnMinWidths(node: RenderTable): number[] {
+  const [header, ...rows] = node.children;
+  if (header == null) {
+    return [];
+  }
+  return header.children.map((cell, colIdx) => {
+    let maxLen = countInlineTextLength(cell.children);
+    for (const row of rows) {
+      const rowCell = row.children[colIdx];
+      if (rowCell != null) {
+        const len = countInlineTextLength(rowCell.children);
         if (len > maxLen) {
           maxLen = len;
         }
@@ -1047,7 +1198,7 @@ function computeTableColumnMinWidths(node: {
 }
 
 function renderBlock(
-  node: BlockNode,
+  node: RenderBlockNode,
   index: number,
   blockCount: number,
   density: 'default' | 'compact',
@@ -1060,8 +1211,9 @@ function renderBlock(
   linkComponent: LinkComponentType = 'a',
   inlinePlugins: MarkdownInlinePlugin[] | undefined,
   components: Partial<MarkdownComponents> | undefined,
+  preparedPlugins: PreparedMarkdownPlugins | undefined,
   t: TranslatorFn,
-  headingIdMap?: ReadonlyMap<BlockNode, string>,
+  headingIdMap?: ReadonlyMap<RenderBlockNode, string>,
 ): SyncReactNode {
   const blockAlignMargin = BLOCK_ALIGN_MARGIN[contentAlign];
   const blockAlignStyle =
@@ -1074,7 +1226,7 @@ function renderBlock(
 
   switch (node.type) {
     case 'heading': {
-      const level = Math.min(node.level + headingLevelStart - 1, 6) as
+      const level = Math.min(node.depth + headingLevelStart - 1, 6) as
         1 | 2 | 3 | 4 | 5 | 6;
       const headingChildren = node.children.map((c, i) =>
         renderInline(
@@ -1086,6 +1238,7 @@ function renderBlock(
           linkComponent,
           inlinePlugins,
           components,
+          preparedPlugins,
         ),
       );
       // Only top-level headings get an id: the map is built from the same
@@ -1137,6 +1290,7 @@ function renderBlock(
           linkComponent,
           inlinePlugins,
           components,
+          preparedPlugins,
         ),
       );
       const ParagraphComp = components?.paragraph;
@@ -1174,20 +1328,17 @@ function renderBlock(
         </div>
       );
     }
-    case 'codeblock': {
+    case 'code': {
       // Track codeblock content in cursor for accurate character counting
-      cursor.offset += node.content.length;
+      cursor.offset += node.value.length;
+      const language = getMarkdownAstLegacyCodeLanguage(node) ?? 'plaintext';
       const CodeBlockComp = components?.code;
       if (CodeBlockComp) {
         return (
-          <CodeBlockComp
-            key={index}
-            code={node.content}
-            language={node.language}
-          />
+          <CodeBlockComp key={index} code={node.value} language={language} />
         );
       }
-      return (
+      const fallback = (
         <div
           key={index}
           {...mergeProps(
@@ -1200,8 +1351,8 @@ function renderBlock(
             ),
           )}>
           <CodeBlock
-            code={node.content}
-            language={node.language}
+            code={node.value}
+            language={language}
             isCollapsible
             xstyle={[
               contentWidthValue != null
@@ -1212,6 +1363,48 @@ function renderBlock(
           />
         </div>
       );
+      const proposal = getMarkdownFenceProposal(node);
+      if (proposal == null) {
+        return fallback;
+      }
+      const renderer = getMarkdownExtensionRenderer(
+        preparedPlugins,
+        proposal.node,
+      );
+      if (renderer == null) {
+        return fallback;
+      }
+      try {
+        const rendered = renderer.render({node: proposal.node});
+        if (rendered == null || typeof rendered === 'boolean') {
+          return fallback;
+        }
+        return (
+          <MarkdownPluginBoundary
+            key={index}
+            pluginName={proposal.node.plugin}
+            resetKey={proposal.node}
+            resetRenderer={renderer.render}
+            fallback={fallback}>
+            <Suspense fallback={fallback}>{rendered}</Suspense>
+          </MarkdownPluginBoundary>
+        );
+      } catch (error) {
+        reportMarkdownPluginFailure(proposal.node.plugin, 'render', error);
+        return fallback;
+      }
+    }
+    case 'math': {
+      cursor.offset += node.value.length;
+      const MathComp = components?.math;
+      if (MathComp == null) {
+        return (
+          <div key={index} role="paragraph">
+            {`$$${node.value}$$`}
+          </div>
+        );
+      }
+      return <MathComp key={index} value={node.value} display="block" />;
     }
     case 'blockquote': {
       const BlockquoteComp = components?.blockquote;
@@ -1231,6 +1424,7 @@ function renderBlock(
             linkComponent,
             inlinePlugins,
             components,
+            preparedPlugins,
             t,
           ),
         );
@@ -1266,6 +1460,7 @@ function renderBlock(
               linkComponent,
               inlinePlugins,
               components,
+              preparedPlugins,
               t,
             ),
           )}
@@ -1275,11 +1470,12 @@ function renderBlock(
     case 'list': {
       // Detect task lists: all items have a checked state
       const isTaskList =
-        node.items.length > 0 && node.items.every(item => item.checked != null);
+        node.children.length > 0 &&
+        node.children.every(item => item.checked != null);
 
       if (isTaskList) {
         // Extract labels from task items — render as rich inline content
-        const checkedValues = node.items
+        const checkedValues = node.children
           .map((item, i) => ({item, key: `task-${i}`}))
           .filter(({item}) => item.checked)
           .map(({key}) => key);
@@ -1302,7 +1498,7 @@ function renderBlock(
               xstyle={styles.blockIndent}
               isReadOnly
               density="compact">
-              {node.items.map((item, i) => {
+              {node.children.map((item, i) => {
                 const firstChild = item.children[0];
                 const isInline =
                   item.children.length === 1 &&
@@ -1320,6 +1516,7 @@ function renderBlock(
                         linkComponent,
                         inlinePlugins,
                         components,
+                        preparedPlugins,
                       ),
                     )}
                   </>
@@ -1340,6 +1537,7 @@ function renderBlock(
                         linkComponent,
                         inlinePlugins,
                         components,
+                        preparedPlugins,
                         t,
                       ),
                     )}
@@ -1382,7 +1580,7 @@ function renderBlock(
             density="compact"
             start={node.ordered ? node.start : undefined}
             xstyle={styles.blockIndent}>
-            {node.items.map((item, i) => {
+            {node.children.map((item, i) => {
               const firstChild = item.children[0];
               const isInline =
                 item.children.length === 1 && firstChild?.type === 'paragraph';
@@ -1402,6 +1600,7 @@ function renderBlock(
                       linkComponent,
                       inlinePlugins,
                       components,
+                      preparedPlugins,
                     ),
                   )}
                 </>
@@ -1422,6 +1621,7 @@ function renderBlock(
                       linkComponent,
                       inlinePlugins,
                       components,
+                      preparedPlugins,
                       t,
                     ),
                   )}
@@ -1442,6 +1642,7 @@ function renderBlock(
     }
     case 'table': {
       const colMinWidths = computeTableColumnMinWidths(node);
+      const [header, ...rows] = node.children;
 
       return (
         <div
@@ -1471,14 +1672,14 @@ function renderBlock(
           <Table dividers="rows" textOverflow="wrap">
             <TableHeader>
               <TableRow>
-                {node.headers.map((h, i) => (
+                {header?.children.map((h, i) => (
                   <TableHeaderCell
                     // eslint-disable-next-line @eslint-react/no-array-index-key -- markdown table columns are positional by definition
                     key={i}
                     xstyle={[
                       dynamicStyles.cellMinWidth(`${colMinWidths[i]}px`),
-                      node.alignments[i] === 'center' && cellAlignStyles.center,
-                      node.alignments[i] === 'right' && cellAlignStyles.end,
+                      node.align[i] === 'center' && cellAlignStyles.center,
+                      node.align[i] === 'right' && cellAlignStyles.end,
                     ]}>
                     {h.children.map((c, j) =>
                       renderInline(
@@ -1490,6 +1691,7 @@ function renderBlock(
                         linkComponent,
                         inlinePlugins,
                         components,
+                        preparedPlugins,
                       ),
                     )}
                   </TableHeaderCell>
@@ -1497,14 +1699,14 @@ function renderBlock(
               </TableRow>
             </TableHeader>
             <TableBody>
-              {node.rows.map((row, i) => {
-                const cells = row.map((cell, j) => (
+              {rows.map((row, i) => {
+                const cells = row.children.map((cell, j) => (
                   <TableCell
                     // eslint-disable-next-line @eslint-react/no-array-index-key -- markdown table cells are positional by row and column
                     key={j}
                     xstyle={[
-                      node.alignments[j] === 'center' && cellAlignStyles.center,
-                      node.alignments[j] === 'right' && cellAlignStyles.end,
+                      node.align[j] === 'center' && cellAlignStyles.center,
+                      node.align[j] === 'right' && cellAlignStyles.end,
                     ]}>
                     {cell.children.map((c, k) =>
                       renderInline(
@@ -1516,6 +1718,7 @@ function renderBlock(
                         linkComponent,
                         inlinePlugins,
                         components,
+                        preparedPlugins,
                       ),
                     )}
                   </TableCell>
@@ -1533,7 +1736,47 @@ function renderBlock(
         </div>
       );
     }
-    case 'hr': {
+    case 'extension': {
+      const renderer = getMarkdownExtensionRenderer(preparedPlugins, node);
+      const fallbackText =
+        node.source ?? markdownExtensionText(preparedPlugins, node);
+      const fallback = wrapTextWithFade(fallbackText, cursor, index);
+      let content: React.ReactNode = fallback;
+      if (renderer != null) {
+        try {
+          const rendered = renderer.render({node});
+          content = (
+            <MarkdownPluginBoundary
+              pluginName={node.plugin}
+              resetKey={node}
+              resetRenderer={renderer.render}
+              fallback={fallback}>
+              <Suspense fallback={fallback}>{rendered}</Suspense>
+            </MarkdownPluginBoundary>
+          );
+        } catch (error) {
+          reportMarkdownPluginFailure(node.plugin, 'render', error);
+        }
+      }
+      return (
+        <div
+          key={index}
+          {...stylex.props(
+            spacing,
+            contentWidthValue != null
+              ? dynamicStyles.proseWidth(contentWidthValue)
+              : null,
+            contentAlign !== 'start'
+              ? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
+              : null,
+            isFirst && styles.noMarginBlockStart,
+            isLast && styles.noMarginBlockEnd,
+          )}>
+          {content}
+        </div>
+      );
+    }
+    case 'thematicBreak': {
       const HrComp = components?.hr;
       if (HrComp) {
         return <HrComp key={index} />;
@@ -1554,7 +1797,7 @@ function renderBlock(
       );
     }
     case 'image': {
-      const safeSrc = sanitizeUrl(node.src);
+      const safeSrc = sanitizeMarkdownUrl(node.url);
       if (safeSrc == null) {
         return (
           <div
@@ -1608,7 +1851,9 @@ function renderBlock(
  * </Markdown>
  * ```
  */
-export function Markdown({
+export function Markdown<
+  const Plugins extends ReadonlyArray<MarkdownPluginEntry> = readonly [],
+>({
   ref,
   children,
   display = 'block',
@@ -1621,6 +1866,7 @@ export function Markdown({
   contentWidth = 680,
   contentAlign = 'start',
   components,
+  plugins,
   inlinePlugins,
   autolink,
   xstyle,
@@ -1628,7 +1874,7 @@ export function Markdown({
   style,
   'data-testid': testId,
   ...props
-}: MarkdownProps): React.ReactElement {
+}: MarkdownProps<Plugins>): React.ReactElement {
   const t = useTranslator();
   const LinkComponent = useLinkComponent();
   // Derive the set of source IDs for the parser (stable across renders when sources don't change)
@@ -1637,44 +1883,109 @@ export function Markdown({
     [sources],
   );
 
-  const parseOptions = useMemo(
-    () => ({sourceIds, autolink}),
-    [sourceIds, autolink],
+  const preparedPlugins = useMemo(() => {
+    if (plugins == null) {
+      return undefined;
+    }
+    try {
+      return prepareMarkdownPlugins(plugins);
+    } catch (error) {
+      reportMarkdownPluginFailure('configuration', 'transform', error);
+      return undefined;
+    }
+  }, [plugins]);
+  const syntaxPlugins = useStableMarkdownSyntaxEntries(preparedPlugins);
+  const hasMathRenderer = components?.math != null;
+  const legacyParseOptions = useMemo<
+    ParseOptions<ReadonlyArray<MarkdownPluginEntry>>
+  >(
+    () => ({sourceIds, autolink, plugins: syntaxPlugins}),
+    [sourceIds, autolink, syntaxPlugins],
+  );
+  const mathParseOptions = useMemo<
+    MathParseOptions<ReadonlyArray<MarkdownPluginEntry>>
+  >(
+    () => ({sourceIds, autolink, math: true, plugins: syntaxPlugins}),
+    [sourceIds, autolink, syntaxPlugins],
   );
 
   // Smooth bursty streamed chunks into a steady character-by-character reveal.
   // When not streaming, the hook returns children unchanged (no-op).
   const smoothedText = useStreamingText(children, isStreaming);
 
-  const incrementalStateRef = useRef<IncrementalState>(
-    createIncrementalState(),
+  const incrementalStateRef = useRef<IncrementalState<boolean>>(
+    createIncrementalState<boolean>(),
   );
-  // Reset incremental cache when the autolink option toggles — cached
-  // settled blocks were parsed with the previous setting.
+  // Reset incremental cache when parser-affecting component options toggle —
+  // cached settled blocks were parsed with the previous setting.
   const prevAutolinkRef = useRef(autolink);
-  if (prevAutolinkRef.current !== autolink) {
-    incrementalStateRef.current = createIncrementalState();
+  const prevMathRef = useRef(hasMathRenderer);
+  if (
+    prevAutolinkRef.current !== autolink ||
+    prevMathRef.current !== hasMathRenderer
+  ) {
+    incrementalStateRef.current = createIncrementalState<boolean>();
     prevAutolinkRef.current = autolink;
+    prevMathRef.current = hasMathRenderer;
   }
 
-  const blocks = useMemo(() => {
+  const parsedBlocks = useMemo(() => {
     if (display === 'inline') {
       return [];
     }
     if (isStreaming) {
       if (smoothedText === '') {
-        incrementalStateRef.current = createIncrementalState();
+        incrementalStateRef.current = createIncrementalState<boolean>();
         return [];
       }
-      const input = trimStreamingArtifacts(smoothedText);
-      return parseMarkdownIncremental(
-        input,
-        incrementalStateRef.current,
-        parseOptions,
-      );
+      const options = hasMathRenderer ? mathParseOptions : legacyParseOptions;
+      const input = trimStreamingArtifacts(smoothedText, options);
+      return (
+        hasMathRenderer
+          ? parseMarkdownAstIncremental(
+              input,
+              incrementalStateRef.current,
+              mathParseOptions,
+            )
+          : parseMarkdownAstIncremental(
+              input,
+              incrementalStateRef.current,
+              legacyParseOptions,
+            )
+      ).children;
     }
-    return parseMarkdown(children, parseOptions);
-  }, [display, smoothedText, children, isStreaming, parseOptions]);
+    return (
+      hasMathRenderer
+        ? parseMarkdownAst(children, mathParseOptions)
+        : parseMarkdownAst(children, legacyParseOptions)
+    ).children;
+  }, [
+    display,
+    smoothedText,
+    children,
+    isStreaming,
+    hasMathRenderer,
+    mathParseOptions,
+    legacyParseOptions,
+  ]);
+
+  const transformSource = isStreaming
+    ? trimStreamingArtifacts(
+        smoothedText,
+        hasMathRenderer ? mathParseOptions : legacyParseOptions,
+      )
+    : children;
+  const blocks = useMemo(
+    () =>
+      applyMarkdownTransforms(
+        {type: 'root', children: parsedBlocks},
+        preparedPlugins,
+        transformSource,
+        !isStreaming,
+        'block',
+      ).children,
+    [parsedBlocks, preparedPlugins, transformSource, isStreaming],
+  );
 
   // Assign each top-level heading the slug that parseOutlineFromMarkdown
   // would derive for it, so Outline hash links built from the same source
@@ -1686,24 +1997,71 @@ export function Markdown({
     if (display === 'inline' || blocks.length === 0) {
       return undefined;
     }
-    const map = new Map<BlockNode, string>();
+    const map = new Map<RenderBlockNode, string>();
     const counts = new Map<string, number>();
     for (const block of blocks) {
       if (block.type === 'heading') {
-        const label = inlineText(block.children).trim();
+        const label = markdownAstText(block.children, node =>
+          markdownExtensionText(preparedPlugins, node),
+        ).trim();
         map.set(block, uniqueSlug(slugify(label), counts));
       }
     }
     return map;
-  }, [display, blocks]);
+  }, [display, blocks, preparedPlugins]);
 
+  const parsedInlineNodes = useMemo(() => {
+    if (display !== 'inline') {
+      return [];
+    }
+    const options = hasMathRenderer ? mathParseOptions : legacyParseOptions;
+    const input = isStreaming
+      ? trimStreamingArtifacts(smoothedText, options)
+      : children;
+    return hasMathRenderer
+      ? parseInlineAst(input, mathParseOptions)
+      : parseInlineAst(input, legacyParseOptions);
+  }, [
+    display,
+    smoothedText,
+    children,
+    isStreaming,
+    hasMathRenderer,
+    mathParseOptions,
+    legacyParseOptions,
+  ]);
+
+  const inlineTransformSource = isStreaming
+    ? trimStreamingArtifacts(
+        smoothedText,
+        hasMathRenderer ? mathParseOptions : legacyParseOptions,
+      )
+    : children;
   const inlineNodes = useMemo(() => {
     if (display !== 'inline') {
       return [];
     }
-    const input = isStreaming ? trimStreamingArtifacts(smoothedText) : children;
-    return parseInline(input, parseOptions);
-  }, [display, smoothedText, children, isStreaming, parseOptions]);
+    const transformed = applyMarkdownTransforms(
+      {
+        type: 'root',
+        children: [{type: 'paragraph', children: parsedInlineNodes}],
+      },
+      preparedPlugins,
+      inlineTransformSource,
+      !isStreaming,
+      'inline',
+    );
+    const paragraph = transformed.children[0];
+    return paragraph?.type === 'paragraph'
+      ? [...paragraph.children]
+      : parsedInlineNodes;
+  }, [
+    display,
+    parsedInlineNodes,
+    preparedPlugins,
+    inlineTransformSource,
+    isStreaming,
+  ]);
 
   // Track recent boundaries for stacked fade-in animation.
   // The number of spans needed = ceil(animationDuration / tickInterval).
@@ -1719,8 +2077,8 @@ export function Markdown({
     return Math.min(Math.ceil(duration / tickMs), 12);
   }, [token]);
 
-  const prevBlocksRef = useRef<BlockNode[]>([]);
-  const prevInlineNodesRef = useRef<InlineNode[]>([]);
+  const prevBlocksRef = useRef<ReadonlyArray<RenderBlockNode>>([]);
+  const prevInlineNodesRef = useRef<ReadonlyArray<RenderInlineNode>>([]);
   const boundariesRef = useRef<number[]>([]);
   const smoothedLen = smoothedText.length;
   const boundaries = useMemo(() => {
@@ -1769,6 +2127,7 @@ export function Markdown({
             LinkComponent,
             inlinePlugins,
             components,
+            preparedPlugins,
           ),
         )}
       </span>
@@ -1814,6 +2173,7 @@ export function Markdown({
           LinkComponent,
           inlinePlugins,
           components,
+          preparedPlugins,
           t,
           headingIdMap,
         ),