@astryxdesign/core 0.6.1 → 0.6.2

package/src/Markdown/Markdown.tsx

@@ -4,8 +4,8 @@
 
 /**
  * @file Markdown.tsx
- * @input Markdown string, parser AST types
- * @output Exports Markdown component and MarkdownProps
+ * @input Markdown string, parser AST types, optional custom renderers
+ * @output Exports Markdown component, MarkdownProps, and renderer contracts
  * @position Core implementation; renders markdown as Astryx components
  */
 
@@ -57,7 +57,13 @@ import {
   slugify,
   uniqueSlug,
 } from './parser';
-import type {BlockNode, InlineNode, IncrementalState} from './parser';
+import type {
+  BlockNodeWithMath,
+  InlineNodeWithMath,
+  IncrementalState,
+  MathParseOptions,
+  ParseOptions,
+} from './parser';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator, type TranslatorFn} from '../i18n';
 
@@ -70,7 +76,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 +108,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;
@@ -183,7 +197,7 @@ 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.
    */
@@ -473,7 +487,7 @@ 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: InlineNodeWithMath[]): number {
   let len = 0;
   for (const node of nodes) {
     switch (node.type) {
@@ -483,6 +497,9 @@ function countInlineTextLength(nodes: InlineNode[]): number {
       case 'code':
         len += node.content.length;
         break;
+      case 'math':
+        len += node.value.length;
+        break;
       case 'image':
         len += node.alt.length;
         break;
@@ -506,7 +523,7 @@ function countInlineTextLength(nodes: InlineNode[]): number {
 /**
  * Count total text characters in a block node tree.
  */
-function countBlockTextLength(nodes: BlockNode[]): number {
+function countBlockTextLength(nodes: BlockNodeWithMath[]): number {
   let len = 0;
   for (const node of nodes) {
     switch (node.type) {
@@ -517,6 +534,9 @@ function countBlockTextLength(nodes: BlockNode[]): number {
       case 'codeblock':
         len += node.content.length;
         break;
+      case 'math':
+        len += node.value.length;
+        break;
       case 'blockquote':
         len += countBlockTextLength(node.children);
         break;
@@ -748,7 +768,7 @@ function getCitationNumber(ctx: CitationContext, sourceId: string): number {
 }
 
 function renderInline(
-  node: InlineNode,
+  node: InlineNodeWithMath,
   index: number,
   onLinkClick: MarkdownProps['onLinkClick'] | undefined,
   cursor: StreamingCursor,
@@ -847,6 +867,14 @@ function renderInline(
       );
       return codeEl;
     }
+    case 'math': {
+      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);
       if (safeHref == null) {
@@ -984,7 +1012,7 @@ function renderInline(
 // ---------------------------------------------------------------------------
 
 function getElementSpacing(
-  node: BlockNode,
+  node: BlockNodeWithMath,
   density: 'default' | 'compact',
 ): StyleXStyles {
   const compact = density === 'compact';
@@ -1002,6 +1030,7 @@ function getElementSpacing(
         ? styles.spacingParagraphCompact
         : styles.spacingParagraphDefault;
     case 'codeblock':
+    case 'math':
       return compact
         ? styles.spacingCodeblockCompact
         : styles.spacingCodeblockDefault;
@@ -1029,8 +1058,8 @@ function getElementSpacing(
  * Buckets: ≤6 chars → 60px, 7–15 → 80px, >15 → 120px.
  */
 function computeTableColumnMinWidths(node: {
-  headers: {children: InlineNode[]}[];
-  rows: {children: InlineNode[]}[][];
+  headers: {children: InlineNodeWithMath[]}[];
+  rows: {children: InlineNodeWithMath[]}[][];
 }): number[] {
   return node.headers.map((h, colIdx) => {
     let maxLen = countInlineTextLength(h.children);
@@ -1047,7 +1076,7 @@ function computeTableColumnMinWidths(node: {
 }
 
 function renderBlock(
-  node: BlockNode,
+  node: BlockNodeWithMath,
   index: number,
   blockCount: number,
   density: 'default' | 'compact',
@@ -1061,7 +1090,7 @@ function renderBlock(
   inlinePlugins: MarkdownInlinePlugin[] | undefined,
   components: Partial<MarkdownComponents> | undefined,
   t: TranslatorFn,
-  headingIdMap?: ReadonlyMap<BlockNode, string>,
+  headingIdMap?: ReadonlyMap<BlockNodeWithMath, string>,
 ): SyncReactNode {
   const blockAlignMargin = BLOCK_ALIGN_MARGIN[contentAlign];
   const blockAlignStyle =
@@ -1213,6 +1242,18 @@ function renderBlock(
         </div>
       );
     }
+    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;
       if (BlockquoteComp) {
@@ -1637,24 +1678,34 @@ export function Markdown({
     [sources],
   );
 
-  const parseOptions = useMemo(
+  const hasMathRenderer = components?.math != null;
+  const legacyParseOptions = useMemo<ParseOptions>(
     () => ({sourceIds, autolink}),
     [sourceIds, autolink],
   );
+  const mathParseOptions = useMemo<MathParseOptions>(
+    () => ({sourceIds, autolink, math: true}),
+    [sourceIds, autolink],
+  );
 
   // 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(() => {
@@ -1663,18 +1714,35 @@ export function Markdown({
     }
     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
+        ? parseMarkdownIncremental(
+            input,
+            incrementalStateRef.current as IncrementalState<true>,
+            mathParseOptions,
+          )
+        : parseMarkdownIncremental(
+            input,
+            incrementalStateRef.current as IncrementalState<false>,
+            legacyParseOptions,
+          );
     }
-    return parseMarkdown(children, parseOptions);
-  }, [display, smoothedText, children, isStreaming, parseOptions]);
+    return hasMathRenderer
+      ? parseMarkdown(children, mathParseOptions)
+      : parseMarkdown(children, legacyParseOptions);
+  }, [
+    display,
+    smoothedText,
+    children,
+    isStreaming,
+    hasMathRenderer,
+    mathParseOptions,
+    legacyParseOptions,
+  ]);
 
   // Assign each top-level heading the slug that parseOutlineFromMarkdown
   // would derive for it, so Outline hash links built from the same source
@@ -1686,7 +1754,7 @@ export function Markdown({
     if (display === 'inline' || blocks.length === 0) {
       return undefined;
     }
-    const map = new Map<BlockNode, string>();
+    const map = new Map<BlockNodeWithMath, string>();
     const counts = new Map<string, number>();
     for (const block of blocks) {
       if (block.type === 'heading') {
@@ -1701,9 +1769,22 @@ export function Markdown({
     if (display !== 'inline') {
       return [];
     }
-    const input = isStreaming ? trimStreamingArtifacts(smoothedText) : children;
-    return parseInline(input, parseOptions);
-  }, [display, smoothedText, children, isStreaming, parseOptions]);
+    const options = hasMathRenderer ? mathParseOptions : legacyParseOptions;
+    const input = isStreaming
+      ? trimStreamingArtifacts(smoothedText, options)
+      : children;
+    return hasMathRenderer
+      ? parseInline(input, mathParseOptions)
+      : parseInline(input, legacyParseOptions);
+  }, [
+    display,
+    smoothedText,
+    children,
+    isStreaming,
+    hasMathRenderer,
+    mathParseOptions,
+    legacyParseOptions,
+  ]);
 
   // Track recent boundaries for stacked fade-in animation.
   // The number of spans needed = ceil(animationDuration / tickInterval).
@@ -1719,8 +1800,8 @@ export function Markdown({
     return Math.min(Math.ceil(duration / tickMs), 12);
   }, [token]);
 
-  const prevBlocksRef = useRef<BlockNode[]>([]);
-  const prevInlineNodesRef = useRef<InlineNode[]>([]);
+  const prevBlocksRef = useRef<BlockNodeWithMath[]>([]);
+  const prevInlineNodesRef = useRef<InlineNodeWithMath[]>([]);
   const boundariesRef = useRef<number[]>([]);
   const smoothedLen = smoothedText.length;
   const boundaries = useMemo(() => {

package/src/Markdown/incremental.test.ts

@@ -8,7 +8,12 @@ import {
   getIncrementalParseWork,
   trimStreamingArtifacts,
 } from './parser';
-import type {BlockNode, InlineNode} from './parser';
+import type {
+  BlockNode,
+  BlockNodeWithMath,
+  InlineNode,
+  InlineNodeWithMath,
+} from './parser';
 
 function simulateStreaming(fullText: string, chunkSize = 10) {
   const state = createIncrementalState();
@@ -90,6 +95,150 @@ describe('parseMarkdownIncremental', () => {
     expect(final).toEqual(full);
   });
 
+  it('matches the full parse when math delimiters arrive across chunks', () => {
+    const text = 'Before $x_1 + *y*$ after.\n\n$$\n\\sum_i x_i\n$$\n\nDone.';
+    const state = createIncrementalState<true>();
+    let final: BlockNodeWithMath[] = [];
+    for (let end = 1; end <= text.length; end++) {
+      final = parseMarkdownIncremental(text.slice(0, end), state, {math: true});
+    }
+    expect(final).toEqual(parseMarkdown(text, {math: true}));
+  });
+
+  describe.each([
+    ['list', '- $$\n  x + y\n  $$'],
+    ['task list', '- [ ] $$\n  x + y\n  $$'],
+    ['blockquote', '> $$\n> x + y\n> $$'],
+    ['blockquote in a list', '- > $$\n  > x + y\n  > $$'],
+    ['CRLF list', '- $$\r\n  x + y\r\n  $$\r\n'],
+  ] as const)('nested display math in a %s', (_label, text) => {
+    it.each([false, true])(
+      'withholds the incomplete container (sourceRanges=%s)',
+      sourceRanges => {
+        const closingDelimiter = text.lastIndexOf('$$');
+        const state = createIncrementalState<true>();
+        expect(
+          parseMarkdownIncremental(text.slice(0, closingDelimiter), state, {
+            math: true,
+            sourceRanges,
+          }),
+        ).toEqual([]);
+      },
+    );
+
+    it.each([false, true])(
+      'matches the full parse at every stream split (sourceRanges=%s)',
+      sourceRanges => {
+        const options = {math: true as const, sourceRanges};
+        const full = parseMarkdown(text, options);
+
+        // One long-lived state sees every character boundary in order.
+        const characterState = createIncrementalState<true>();
+        let characterResult = parseMarkdownIncremental(
+          '',
+          characterState,
+          options,
+        );
+        for (let end = 1; end <= text.length; end++) {
+          characterResult = parseMarkdownIncremental(
+            text.slice(0, end),
+            characterState,
+            options,
+          );
+        }
+        expect(characterResult).toEqual(full);
+
+        // Markdown's production streaming path trims partial syntax before it
+        // reaches the incremental parser. A terminal nested closer must survive
+        // that pass rather than being mistaken for a fresh opener.
+        const productionState = createIncrementalState<true>();
+        let productionResult = parseMarkdownIncremental(
+          '',
+          productionState,
+          options,
+        );
+        for (let end = 1; end <= text.length; end++) {
+          const prefix = trimStreamingArtifacts(text.slice(0, end), options);
+          productionResult = parseMarkdownIncremental(
+            prefix,
+            productionState,
+            options,
+          );
+        }
+        expect(productionResult).toEqual(full);
+
+        // Every possible two-chunk split converges to the same complete tree,
+        // both directly and through Markdown's production trimming pass.
+        for (let split = 0; split <= text.length; split++) {
+          const state = createIncrementalState<true>();
+          parseMarkdownIncremental(text.slice(0, split), state, options);
+          expect(parseMarkdownIncremental(text, state, options)).toEqual(full);
+
+          const trimmedState = createIncrementalState<true>();
+          parseMarkdownIncremental(
+            trimStreamingArtifacts(text.slice(0, split), options),
+            trimmedState,
+            options,
+          );
+          expect(
+            parseMarkdownIncremental(
+              trimStreamingArtifacts(text, options),
+              trimmedState,
+              options,
+            ),
+          ).toEqual(full);
+        }
+      },
+    );
+  });
+
+  describe.each([
+    ['list', '- $$\n  x\n- next\n\nAfter'],
+    ['blockquote', '> $$\n> x\n\nAfter'],
+    ['deeper blockquote', '> $$\n> > x\n> > $$'],
+    ['deeper blockquote in a list', '- > $$\n  > > x\n  > > $$'],
+    ['deeper inner quote in a quoted list', '> - $$\n>   > x\n>   > $$'],
+  ] as const)('unmatched display math after a %s ends', (_label, text) => {
+    it.each([false, true])(
+      'returns to literal parsing (sourceRanges=%s)',
+      sourceRanges => {
+        const options = {math: true as const, sourceRanges};
+        const full = parseMarkdown(text, options);
+        for (const trimsStreamingArtifacts of [false, true]) {
+          const state = createIncrementalState<true>();
+          let result = parseMarkdownIncremental('', state, options);
+          for (let end = 1; end <= text.length; end++) {
+            const prefix = text.slice(0, end);
+            result = parseMarkdownIncremental(
+              trimsStreamingArtifacts
+                ? trimStreamingArtifacts(prefix, options)
+                : prefix,
+              state,
+              options,
+            );
+          }
+          expect(result).toEqual(full);
+        }
+      },
+    );
+  });
+
+  it('withholds an incomplete display-math block while streaming', () => {
+    const state = createIncrementalState<true>();
+    const blocks = parseMarkdownIncremental('Intro\n\n$$\nx + y', state, {
+      math: true,
+    });
+    expect(blocks).toEqual(parseMarkdown('Intro'));
+  });
+
+  it('stores math nodes only in a math-enabled incremental state', () => {
+    const text = 'Intro.\n\nInline $x$.';
+    const state = createIncrementalState<true>();
+    const blocks = parseMarkdownIncremental(text, state, {math: true});
+    expect(blocks).toEqual(parseMarkdown(text, {math: true}));
+    expect(state.settledBlocks).toEqual(parseMarkdown('Intro.', {math: true}));
+  });
+
   it('handles table streaming', () => {
     const text = '| Col1 | Col2 |\n| --- | --- |\n| a | b |\n| c | d |';
     const {final} = simulateStreaming(text, 5);
@@ -333,6 +482,15 @@ describe('trimStreamingArtifacts', () => {
     expect(trimStreamingArtifacts('Hello `code`')).toBe('Hello `code`');
   });
 
+  it('withholds incomplete inline math only when math parsing is enabled', () => {
+    expect(trimStreamingArtifacts('Value $', {math: true})).toBe('Value ');
+    expect(trimStreamingArtifacts('Value $x + 1', {math: true})).toBe('Value ');
+    expect(trimStreamingArtifacts('Value $x + 1')).toBe('Value $x + 1');
+    expect(trimStreamingArtifacts('Value $x + 1$', {math: true})).toBe(
+      'Value $x + 1$',
+    );
+  });
+
   it('trims trailing unclosed strikethrough', () => {
     expect(trimStreamingArtifacts('Hello ~~')).toBe('Hello ');
     expect(trimStreamingArtifacts('Hello ~')).toBe('Hello ');
@@ -456,14 +614,16 @@ describe('streaming structural suppression', () => {
     });
 
     /** The text a reader would see for one block. */
-    function visibleText(block: BlockNode): string {
-      const fromInline = (nodes: InlineNode[]): string =>
+    function visibleText(block: BlockNodeWithMath): string {
+      const fromInline = (nodes: InlineNodeWithMath[]): string =>
         nodes
           .map(node => {
             switch (node.type) {
               case 'text':
               case 'code':
                 return node.content;
+              case 'math':
+                return node.value;
               case 'bold':
               case 'italic':
               case 'strikethrough':
@@ -484,6 +644,8 @@ describe('streaming structural suppression', () => {
           return fromInline(block.children);
         case 'codeblock':
           return block.content;
+        case 'math':
+          return block.value;
         case 'blockquote':
           return block.children.map(visibleText).join('\n');
         case 'list':
@@ -637,7 +799,7 @@ describe('streaming end-to-end: no raw syntax visible', () => {
    * Helper: extract all visible text from a block tree.
    * Returns the text that would be rendered to the user, without markdown syntax.
    */
-  function extractVisibleText(blocks: BlockNode[]): string {
+  function extractVisibleText(blocks: BlockNodeWithMath[]): string {
     let text = '';
     for (const block of blocks) {
       switch (block.type) {
@@ -648,6 +810,9 @@ describe('streaming end-to-end: no raw syntax visible', () => {
         case 'codeblock':
           text += block.content;
           break;
+        case 'math':
+          text += block.value;
+          break;
         case 'blockquote':
           text += extractVisibleText(block.children);
           break;
@@ -676,7 +841,7 @@ describe('streaming end-to-end: no raw syntax visible', () => {
     return text;
   }
 
-  function extractInlineText(nodes: InlineNode[]): string {
+  function extractInlineText(nodes: InlineNodeWithMath[]): string {
     let text = '';
     for (const node of nodes) {
       switch (node.type) {
@@ -686,6 +851,9 @@ describe('streaming end-to-end: no raw syntax visible', () => {
         case 'code':
           text += node.content;
           break;
+        case 'math':
+          text += node.value;
+          break;
         case 'bold':
         case 'italic':
         case 'strikethrough':
@@ -707,11 +875,11 @@ describe('streaming end-to-end: no raw syntax visible', () => {
   }
 
   function streamCharByChar(fullText: string): {
-    snapshots: BlockNode[][];
+    snapshots: BlockNodeWithMath[][];
     visibleTexts: string[];
   } {
     const state = createIncrementalState();
-    const snapshots: BlockNode[][] = [];
+    const snapshots: BlockNodeWithMath[][] = [];
     const visibleTexts: string[] = [];
     for (let i = 1; i <= fullText.length; i++) {
       const trimmed = trimStreamingArtifacts(fullText.slice(0, i));

package/src/Markdown/index.ts

@@ -24,10 +24,16 @@ export {
 } from './parser';
 export type {
   BlockNode,
+  BlockNodeWithMath,
+  MathBlockNode,
   InlineNode,
+  InlineNodeWithMath,
+  MathInlineNode,
   SourceRange,
   ListItemNode,
   TableCellNode,
   TableAlignment,
+  ParseOptions,
+  MathParseOptions,
   IncrementalState as IncrementalParseState,
 } from './parser';

package/src/Markdown/parser.perf.test.ts

@@ -9,6 +9,8 @@ import {
 } from './parser';
 import type {BlockNode, ParseOptions} from './parser';
 
+type PerfParseOptions = ParseOptions;
+
 function generateAIResponse(paragraphs: number): string {
   const sections: string[] = [];
   for (let i = 0; i < paragraphs; i++) {
@@ -81,7 +83,7 @@ function simulateStreamingIncremental(
 function blocksBuiltPerChunk(
   fullText: string,
   chunkSize: number,
-  options?: ParseOptions,
+  options?: PerfParseOptions,
 ): number[] {
   const state = createIncrementalState();
   let previous: ReadonlySet<BlockNode> = new Set();