@astryxdesign/core 0.6.2 → 0.6.3-canary.0788c49

package/src/Markdown/Markdown.tsx

@@ -4,12 +4,12 @@
 
 /**
  * @file Markdown.tsx
- * @input Markdown string, parser AST types, optional custom renderers
+ * @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,26 +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 {IncrementalState, MathParseOptions, ParseOptions} from './parser';
+import {getMarkdownAstLegacyCodeLanguage, markdownAstText} from './ast';
 import type {
-  BlockNodeWithMath,
-  InlineNodeWithMath,
-  IncrementalState,
-  MathParseOptions,
-  ParseOptions,
-} from './parser';
+  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 {sanitizeMarkdownLinkUrl, 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
@@ -140,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;
   /**
@@ -201,6 +220,11 @@ export interface MarkdownProps extends BaseProps<HTMLElement> {
    * 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.
@@ -487,25 +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: InlineNodeWithMath[]): 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 'math':
+      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;
@@ -515,6 +539,9 @@ function countInlineTextLength(nodes: InlineNodeWithMath[]): number {
       case 'citation':
         len += 1;
         break;
+      case 'extension':
+        len += node.source?.length ?? 0;
+        break;
     }
   }
   return len;
@@ -523,7 +550,7 @@ function countInlineTextLength(nodes: InlineNodeWithMath[]): number {
 /**
  * Count total text characters in a block node tree.
  */
-function countBlockTextLength(nodes: BlockNodeWithMath[]): number {
+function countBlockTextLength(nodes: ReadonlyArray<RenderBlockNode>): number {
   let len = 0;
   for (const node of nodes) {
     switch (node.type) {
@@ -531,8 +558,8 @@ function countBlockTextLength(nodes: BlockNodeWithMath[]): 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;
@@ -541,21 +568,21 @@ function countBlockTextLength(nodes: BlockNodeWithMath[]): number {
         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;
@@ -575,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
 // ---------------------------------------------------------------------------
@@ -701,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
 // ---------------------------------------------------------------------------
@@ -768,7 +849,7 @@ function getCitationNumber(ctx: CitationContext, sourceId: string): number {
 }
 
 function renderInline(
-  node: InlineNodeWithMath,
+  node: RenderInlineNode,
   index: number,
   onLinkClick: MarkdownProps['onLinkClick'] | undefined,
   cursor: StreamingCursor,
@@ -776,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.
@@ -803,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) =>
@@ -818,11 +900,12 @@ function renderInline(
               linkComponent,
               inlinePlugins,
               components,
+              preparedPlugins,
             ),
           )}
         </strong>
       );
-    case 'italic':
+    case 'emphasis':
       return (
         <em key={index}>
           {node.children.map((c, i) =>
@@ -835,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) =>
@@ -852,22 +936,23 @@ 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 'math': {
+    case 'inlineMath': {
       const MathComp = components?.math;
       if (MathComp == null) {
         return wrapTextWithFade(`$${node.value}$`, cursor, index);
@@ -876,7 +961,7 @@ function renderInline(
       return <MathComp key={index} value={node.value} display="inline" />;
     }
     case 'link': {
-      const safeHref = sanitizeUrl(node.href);
+      const safeHref = sanitizeMarkdownLinkUrl(node.url);
       if (safeHref == null) {
         // Unsafe URL — render as plain text
         return (
@@ -891,6 +976,7 @@ function renderInline(
                 linkComponent,
                 inlinePlugins,
                 components,
+                preparedPlugins,
               ),
             )}
           </span>
@@ -910,6 +996,7 @@ function renderInline(
                 linkComponent,
                 inlinePlugins,
                 components,
+                preparedPlugins,
               ),
             )}
           </LinkComp>
@@ -948,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>;
       }
@@ -971,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} />;
@@ -1012,13 +1128,13 @@ function renderInline(
 // ---------------------------------------------------------------------------
 
 function getElementSpacing(
-  node: BlockNodeWithMath,
+  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
@@ -1029,7 +1145,7 @@ function getElementSpacing(
       return compact
         ? styles.spacingParagraphCompact
         : styles.spacingParagraphDefault;
-    case 'codeblock':
+    case 'code':
     case 'math':
       return compact
         ? styles.spacingCodeblockCompact
@@ -1042,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;
@@ -1057,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: InlineNodeWithMath[]}[];
-  rows: {children: InlineNodeWithMath[]}[][];
-}): 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;
         }
@@ -1076,7 +1198,7 @@ function computeTableColumnMinWidths(node: {
 }
 
 function renderBlock(
-  node: BlockNodeWithMath,
+  node: RenderBlockNode,
   index: number,
   blockCount: number,
   density: 'default' | 'compact',
@@ -1089,8 +1211,9 @@ function renderBlock(
   linkComponent: LinkComponentType = 'a',
   inlinePlugins: MarkdownInlinePlugin[] | undefined,
   components: Partial<MarkdownComponents> | undefined,
+  preparedPlugins: PreparedMarkdownPlugins | undefined,
   t: TranslatorFn,
-  headingIdMap?: ReadonlyMap<BlockNodeWithMath, string>,
+  headingIdMap?: ReadonlyMap<RenderBlockNode, string>,
 ): SyncReactNode {
   const blockAlignMargin = BLOCK_ALIGN_MARGIN[contentAlign];
   const blockAlignStyle =
@@ -1103,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(
@@ -1115,6 +1238,7 @@ function renderBlock(
           linkComponent,
           inlinePlugins,
           components,
+          preparedPlugins,
         ),
       );
       // Only top-level headings get an id: the map is built from the same
@@ -1166,6 +1290,7 @@ function renderBlock(
           linkComponent,
           inlinePlugins,
           components,
+          preparedPlugins,
         ),
       );
       const ParagraphComp = components?.paragraph;
@@ -1203,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(
@@ -1229,8 +1351,8 @@ function renderBlock(
             ),
           )}>
           <CodeBlock
-            code={node.content}
-            language={node.language}
+            code={node.value}
+            language={language}
             isCollapsible
             xstyle={[
               contentWidthValue != null
@@ -1241,6 +1363,36 @@ 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;
@@ -1272,6 +1424,7 @@ function renderBlock(
             linkComponent,
             inlinePlugins,
             components,
+            preparedPlugins,
             t,
           ),
         );
@@ -1307,6 +1460,7 @@ function renderBlock(
               linkComponent,
               inlinePlugins,
               components,
+              preparedPlugins,
               t,
             ),
           )}
@@ -1316,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);
@@ -1343,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 &&
@@ -1361,6 +1516,7 @@ function renderBlock(
                         linkComponent,
                         inlinePlugins,
                         components,
+                        preparedPlugins,
                       ),
                     )}
                   </>
@@ -1381,6 +1537,7 @@ function renderBlock(
                         linkComponent,
                         inlinePlugins,
                         components,
+                        preparedPlugins,
                         t,
                       ),
                     )}
@@ -1423,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';
@@ -1443,6 +1600,7 @@ function renderBlock(
                       linkComponent,
                       inlinePlugins,
                       components,
+                      preparedPlugins,
                     ),
                   )}
                 </>
@@ -1463,6 +1621,7 @@ function renderBlock(
                       linkComponent,
                       inlinePlugins,
                       components,
+                      preparedPlugins,
                       t,
                     ),
                   )}
@@ -1483,6 +1642,7 @@ function renderBlock(
     }
     case 'table': {
       const colMinWidths = computeTableColumnMinWidths(node);
+      const [header, ...rows] = node.children;
 
       return (
         <div
@@ -1512,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(
@@ -1531,6 +1691,7 @@ function renderBlock(
                         linkComponent,
                         inlinePlugins,
                         components,
+                        preparedPlugins,
                       ),
                     )}
                   </TableHeaderCell>
@@ -1538,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(
@@ -1557,6 +1718,7 @@ function renderBlock(
                         linkComponent,
                         inlinePlugins,
                         components,
+                        preparedPlugins,
                       ),
                     )}
                   </TableCell>
@@ -1574,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} />;
@@ -1595,7 +1797,7 @@ function renderBlock(
       );
     }
     case 'image': {
-      const safeSrc = sanitizeUrl(node.src);
+      const safeSrc = sanitizeMarkdownUrl(node.url);
       if (safeSrc == null) {
         return (
           <div
@@ -1649,7 +1851,9 @@ function renderBlock(
  * </Markdown>
  * ```
  */
-export function Markdown({
+export function Markdown<
+  const Plugins extends ReadonlyArray<MarkdownPluginEntry> = readonly [],
+>({
   ref,
   children,
   display = 'block',
@@ -1662,6 +1866,7 @@ export function Markdown({
   contentWidth = 680,
   contentAlign = 'start',
   components,
+  plugins,
   inlinePlugins,
   autolink,
   xstyle,
@@ -1669,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)
@@ -1678,14 +1883,30 @@ export function Markdown({
     [sources],
   );
 
+  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>(
-    () => ({sourceIds, autolink}),
-    [sourceIds, autolink],
+  const legacyParseOptions = useMemo<
+    ParseOptions<ReadonlyArray<MarkdownPluginEntry>>
+  >(
+    () => ({sourceIds, autolink, plugins: syntaxPlugins}),
+    [sourceIds, autolink, syntaxPlugins],
   );
-  const mathParseOptions = useMemo<MathParseOptions>(
-    () => ({sourceIds, autolink, math: true}),
-    [sourceIds, autolink],
+  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.
@@ -1708,7 +1929,7 @@ export function Markdown({
     prevMathRef.current = hasMathRenderer;
   }
 
-  const blocks = useMemo(() => {
+  const parsedBlocks = useMemo(() => {
     if (display === 'inline') {
       return [];
     }
@@ -1719,21 +1940,25 @@ export function Markdown({
       }
       const options = hasMathRenderer ? mathParseOptions : legacyParseOptions;
       const input = trimStreamingArtifacts(smoothedText, options);
-      return hasMathRenderer
-        ? parseMarkdownIncremental(
-            input,
-            incrementalStateRef.current as IncrementalState<true>,
-            mathParseOptions,
-          )
-        : parseMarkdownIncremental(
-            input,
-            incrementalStateRef.current as IncrementalState<false>,
-            legacyParseOptions,
-          );
+      return (
+        hasMathRenderer
+          ? parseMarkdownAstIncremental(
+              input,
+              incrementalStateRef.current,
+              mathParseOptions,
+            )
+          : parseMarkdownAstIncremental(
+              input,
+              incrementalStateRef.current,
+              legacyParseOptions,
+            )
+      ).children;
     }
-    return hasMathRenderer
-      ? parseMarkdown(children, mathParseOptions)
-      : parseMarkdown(children, legacyParseOptions);
+    return (
+      hasMathRenderer
+        ? parseMarkdownAst(children, mathParseOptions)
+        : parseMarkdownAst(children, legacyParseOptions)
+    ).children;
   }, [
     display,
     smoothedText,
@@ -1744,6 +1969,24 @@ export function Markdown({
     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
   // always find a matching DOM id. Mirrors that function's traversal exactly:
@@ -1754,18 +1997,20 @@ export function Markdown({
     if (display === 'inline' || blocks.length === 0) {
       return undefined;
     }
-    const map = new Map<BlockNodeWithMath, 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 inlineNodes = useMemo(() => {
+  const parsedInlineNodes = useMemo(() => {
     if (display !== 'inline') {
       return [];
     }
@@ -1774,8 +2019,8 @@ export function Markdown({
       ? trimStreamingArtifacts(smoothedText, options)
       : children;
     return hasMathRenderer
-      ? parseInline(input, mathParseOptions)
-      : parseInline(input, legacyParseOptions);
+      ? parseInlineAst(input, mathParseOptions)
+      : parseInlineAst(input, legacyParseOptions);
   }, [
     display,
     smoothedText,
@@ -1786,6 +2031,38 @@ export function Markdown({
     legacyParseOptions,
   ]);
 
+  const inlineTransformSource = isStreaming
+    ? trimStreamingArtifacts(
+        smoothedText,
+        hasMathRenderer ? mathParseOptions : legacyParseOptions,
+      )
+    : children;
+  const inlineNodes = useMemo(() => {
+    if (display !== 'inline') {
+      return [];
+    }
+    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).
   // useStreamingText ticks every ~tickMs, and the fade runs for
@@ -1800,8 +2077,8 @@ export function Markdown({
     return Math.min(Math.ceil(duration / tickMs), 12);
   }, [token]);
 
-  const prevBlocksRef = useRef<BlockNodeWithMath[]>([]);
-  const prevInlineNodesRef = useRef<InlineNodeWithMath[]>([]);
+  const prevBlocksRef = useRef<ReadonlyArray<RenderBlockNode>>([]);
+  const prevInlineNodesRef = useRef<ReadonlyArray<RenderInlineNode>>([]);
   const boundariesRef = useRef<number[]>([]);
   const smoothedLen = smoothedText.length;
   const boundaries = useMemo(() => {
@@ -1850,6 +2127,7 @@ export function Markdown({
             LinkComponent,
             inlinePlugins,
             components,
+            preparedPlugins,
           ),
         )}
       </span>
@@ -1895,6 +2173,7 @@ export function Markdown({
           LinkComponent,
           inlinePlugins,
           components,
+          preparedPlugins,
           t,
           headingIdMap,
         ),