An open source design system that's fully customizable and agent ready
TypeScript
feat(markdown): add opt-in math renderer (#6312)
Cindy Zhang20102eabf857
diff --git a/.changeset/curly-math-renderer.md b/.changeset/curly-math-renderer.mdnew file mode 100644index 0000000000..54535f2973--- /dev/null+++ b/.changeset/curly-math-renderer.md@@ -0,0 +1,24 @@+---+'@astryxdesign/core': patch+---++[feat] Markdown: add an opt-in math renderer++Supply `components.math` to parse `$…$` inline math and `$$…$$` display math.+The renderer receives the delimiter-free expression as `value` and its placement+as `display: 'inline' | 'block'`, so applications can connect their preferred+math typesetter without preprocessing Markdown or accepting raw HTML.++Math is off unless the renderer is present. Direct parser callers can opt in+with `MathParseOptions` (`{math: true}`) and incremental callers create+`IncrementalParseState<true>` via `createIncrementalState<true>()`. Those overloads return `InlineNodeWithMath` or+`BlockNodeWithMath`; default, legacy-set, `math: false`, and `ParseOptions`-+annotated calls retain the existing `InlineNode` and `BlockNode` unions, so+exhaustive consumers do not gain a case unless they opt in. Existing Markdown+parsing and rendering stay unchanged by default; code stays opaque, escaped and+unmatched delimiters stay literal, and inline plugins skip math. Incremental+parsing preserves full-parse results when display math is nested in ordinary or+task lists and blockquotes, including quote-depth transitions, with LF or CRLF+and with source ranges enabled.++@cixzhangdiff --git a/apps/storybook/stories/Markdown.stories.tsx b/apps/storybook/stories/Markdown.stories.tsxindex f69d05b759..f47dc31cc4 100644--- a/apps/storybook/stories/Markdown.stories.tsx+++ b/apps/storybook/stories/Markdown.stories.tsx@@ -3,6 +3,7 @@import {useState, useEffect, useCallback} from 'react';import type {Meta, StoryObj} from '@storybook/react';import {Markdown} from '@astryxdesign/core/Markdown';+import type {MarkdownComponents} from '@astryxdesign/core/Markdown';import {Button} from '@astryxdesign/core/Button';import {Link} from '@astryxdesign/core/Link';import {Text} from '@astryxdesign/core/Text';@@ -445,3 +446,40 @@ export const InlinePlugins: Story = {);},};++const StoryMath: NonNullable<MarkdownComponents['math']> = ({+ value,+ display,+}) => {+ const Tag = display === 'block' ? 'div' : 'span';+ return (+ <Tag+ role="math"+ aria-label={`Formula: ${value}`}+ style={{+ display: display === 'block' ? 'block' : 'inline',+ padding: display === 'block' ? '12px 16px' : '1px 4px',+ marginBlock: display === 'block' ? 12 : undefined,+ border: '1px solid var(--color-border)',+ borderRadius: 6,+ fontFamily: 'serif',+ fontStyle: 'italic',+ textAlign: display === 'block' ? 'center' : undefined,+ }}>+ {value}+ </Tag>+ );+};++export const CustomMath: Story = {+ name: 'Custom Math Renderer',+ render: () => (+ <div style={{maxWidth: 680}}>+ <Markdown components={{math: StoryMath}}>+ {+ 'A renderer can typeset inline math such as $E = mc^2$ without preprocessing the source.\n\n$$\n\\sum_{i=1}^{n} i = \\frac{n(n+1)}{2}\n$$\n\nCode remains opaque: `$not_math$`.'+ }+ </Markdown>+ </div>+ ),+};diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjsindex d8cebae79a..e4ac69f784 100644--- a/packages/core/src/Markdown/Markdown.doc.mjs+++ b/packages/core/src/Markdown/Markdown.doc.mjs@@ -5,8 +5,7 @@ const anatomy = [{name: 'Document',required: true,- description:- 'Root container for block or inline Markdown content.',+ description: 'Root container for block or inline Markdown content.',},{name: 'Heading',@@ -41,7 +40,8 @@ const anatomy = [{name: 'Table',required: false,- description: 'Scrollable table block rendered from Markdown rows and columns.',+ description:+ 'Scrollable table block rendered from Markdown rows and columns.',},{name: 'Divider',@@ -138,14 +138,14 @@ export const docs = {name: 'contentAlign',type: "'start' | 'center'",description:- "Alignment of prose content within the container when contentWidth is narrower than the available space.",+ 'Alignment of prose content within the container when contentWidth is narrower than the available space.',default: "'start'",},{name: 'inlinePlugins',type: 'MarkdownInlinePlugin[]',description:- 'Transforms regex matches in parsed text nodes into custom inline React elements. Use for issue refs, diff refs, mentions, and other shorthand patterns. Inline code and fenced code blocks are unaffected.',+ 'Transforms regex matches in parsed text nodes into custom inline React elements. Use for prefixed identifiers, mentions, and other shorthand patterns. Inline code, fenced code blocks, and math are unaffected.',},{name: 'autolink',@@ -156,7 +156,8 @@ export const docs = {{name: 'components',type: 'MarkdownComponents',- description: 'Custom React component overrides for rendered Markdown elements (code, inlineCode, link, heading, paragraph, image, blockquote, hr, citation).',+ description:+ 'Custom React component overrides for rendered Markdown elements (code, inlineCode, math, link, heading, paragraph, image, blockquote, hr, citation). Providing math enables `$…$` inline and `$$…$$` display parsing and receives `{value, display}`; omit it when dollar text should stay literal.',},{name: 'xstyle',@@ -184,7 +185,8 @@ export const docs = {],playground: {defaults: {- children: '## Getting Started\n\nInstall the package:\n\n```bash\nnpm install @astryxdesign/core\n```\n\nThen import and use any component:\n\n```tsx\nimport {Button} from \'@astryxdesign/core/Button\';\n```\n\n**Bold**, *italic*, and `inline code` all work.',+ children:+ "## Getting Started\n\nInstall the package:\n\n```bash\nnpm install @astryxdesign/core\n```\n\nThen import and use any component:\n\n```tsx\nimport {Button} from '@astryxdesign/core/Button';\n```\n\n**Bold**, *italic*, and `inline code` all work.",},},theming: {@@ -229,11 +231,41 @@ export const docs = {description:'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',bestPractices: [- { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },- { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },- { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns like issue refs, diff refs, and mentions instead of preprocessing the markdown string.' },- { guidance: true, description: 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.' },- { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },+ {+ guidance: true,+ description:+ 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.',+ },+ {+ guidance: true,+ description:+ 'Use contentWidth to keep prose at a readable line length in wide layouts.',+ },+ {+ guidance: true,+ description:+ 'Use inlinePlugins for prefixed identifiers, mentions, and other prose-only shorthand instead of preprocessing the markdown string.',+ },+ {+ guidance: true,+ description:+ 'Provide components.math only for documents that use dollar-delimited math. The renderer owns typesetting and accessible output; Astryx passes the expression as text and never executes raw HTML.',+ },+ {+ guidance: true,+ description:+ 'For direct parsing, use MathParseOptions and handle InlineNodeWithMath or BlockNodeWithMath. Incremental math parsing also uses createIncrementalState<true>() and IncrementalParseState<true>; default calls and ParseOptions annotations keep the legacy unions.',+ },+ {+ guidance: true,+ description:+ 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.',+ },+ {+ guidance: false,+ description:+ 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.',+ },],},examples: [@@ -259,23 +291,38 @@ import {Text} from '@astryxdesign/core/Text';`,},{- label: 'Inline Plugins',+ label: 'Entity links',code: `import {Link} from '@astryxdesign/core/Link';-const issuePlugins = [+const entityPlugins = [{pattern: /\\b([A-Z][A-Z0-9]+-\\d+)\\b/g,render: (match, key) => (- <Link key={key} href={\`/issues/\${match[1]}\`}>+ <Link key={key} href={\`/entities/\${match[1]}\`}>{match[0]}</Link>),},];-<Markdown inlinePlugins={issuePlugins}>- {'Fixed PROJ-123. Inline code stays plain: \`PROJ-999\`.'}+<Markdown inlinePlugins={entityPlugins}>+ {'See DOC-2048. Inline code stays plain: \`DOC-9999\`.'}+</Markdown>;+`,+ },+ {+ label: 'Math renderer',+ code: `+import {BlockMath, InlineMath} from 'react-katex';++function MathExpression({value, display}) {+ const Component = display === 'block' ? BlockMath : InlineMath;+ return <Component math={value} />;+}++<Markdown components={{math: MathExpression}}>+ {'Inline $x_1 + y$ and display math:\\n\\n$$\\n\\\\sum_i x_i\\n$$'}</Markdown>;`,},@@ -315,8 +362,7 @@ export const docsZh = {{name: 'isStreaming',type: 'boolean',- description:- '启用流式模式,使用增量解析和淡入动画处理分块文本。',+ description: '启用流式模式,使用增量解析和淡入动画处理分块文本。',default: 'false',},{@@ -348,14 +394,14 @@ export const docsZh = {name: 'contentAlign',type: "'start' | 'center'",description:- "当 contentWidth 小于可用空间时,正文内容在容器内的对齐方式。",+ '当 contentWidth 小于可用空间时,正文内容在容器内的对齐方式。',default: "'start'",},{name: 'inlinePlugins',type: 'MarkdownInlinePlugin[]',description:- '将已解析文本节点中的正则匹配转换为自定义内联 React 元素。适用于 issue 引用、diff 引用、用户提及等简写模式。内联代码和围栏代码块不受影响。',+ '将已解析文本节点中的正则匹配转换为自定义内联 React 元素。适用于带前缀的标识符、用户提及等简写模式。内联代码、围栏代码块和数学表达式不受影响。',},{name: 'autolink',@@ -363,6 +409,12 @@ export const docsZh = {description:"可选的裸 URL 和电子邮箱自动链接。设为 'gfm' 启用 GitHub Flavored Markdown 自动链接规则:裸 https?://、www.、<scheme:url>、<email> 以及 user@host 都会变成链接。末尾句末标点和不平衡的末尾右括号会被排除;代码块、现有链接和图片替代文本内部的匹配会被跳过。默认为关闭。",},+ {+ name: 'components',+ type: 'MarkdownComponents',+ description:+ '用于覆盖 Markdown 渲染元素的自定义 React 组件(code、inlineCode、math、link、heading、paragraph、image、blockquote、hr、citation)。提供 math 会启用 `$…$` 行内数学和 `$$…$$` 块级数学解析,并接收 `{value, display}`;不提供时美元符号保持原样。',+ },{name: 'xstyle',type: 'StyleXStyles',@@ -372,12 +424,14 @@ export const docsZh = {{name: 'className',type: 'string',- description: '根元素的 CSS 类名。建议使用 xstyle,className 适用于非 StyleX 系统集成。',+ description:+ '根元素的 CSS 类名。建议使用 xstyle,className 适用于非 StyleX 系统集成。',},{name: 'style',type: 'CSSProperties',- description: '根元素的内联样式。建议使用 xstyle,内联样式会绕过 StyleX 优化。',+ description:+ '根元素的内联样式。建议使用 xstyle,内联样式会绕过 StyleX 优化。',},{name: 'data-testid',@@ -443,11 +497,41 @@ export const docsZh = {description:'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',bestPractices: [- { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },- { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },- { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns like issue refs, diff refs, and mentions instead of preprocessing the markdown string.' },- { guidance: true, description: 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.' },- { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },+ {+ guidance: true,+ description:+ 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.',+ },+ {+ guidance: true,+ description:+ 'Use contentWidth to keep prose at a readable line length in wide layouts.',+ },+ {+ guidance: true,+ description:+ 'Use inlinePlugins for prefixed identifiers, mentions, and other prose-only shorthand instead of preprocessing the markdown string.',+ },+ {+ guidance: true,+ description:+ 'Provide components.math only for documents that use dollar-delimited math. The renderer owns typesetting and accessible output; Astryx passes the expression as text and never executes raw HTML.',+ },+ {+ guidance: true,+ description:+ 'For direct parsing, use MathParseOptions and handle InlineNodeWithMath or BlockNodeWithMath. Incremental math parsing also uses createIncrementalState<true>() and IncrementalParseState<true>; default calls and ParseOptions annotations keep the legacy unions.',+ },+ {+ guidance: true,+ description:+ 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.',+ },+ {+ guidance: false,+ description:+ 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.',+ },],},};@@ -460,25 +544,66 @@ export const docsDense = {description:'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',bestPractices: [- { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },- { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },- { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns (issue refs, diff refs, mentions) instead of preprocessing the markdown string.' },- { guidance: true, description: 'Headings render id attributes matching useOutlineFromMarkdown ids; pair with Outline for hash navigation.' },- { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },+ {+ guidance: true,+ description:+ 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.',+ },+ {+ guidance: true,+ description:+ 'Use contentWidth to keep prose at a readable line length in wide layouts.',+ },+ {+ guidance: true,+ description:+ 'Use inlinePlugins for prefixed identifiers, mentions, and other prose-only shorthand instead of preprocessing the markdown string.',+ },+ {+ guidance: true,+ description:+ 'Provide components.math only for documents that use dollar-delimited math; the renderer owns typesetting and accessible output.',+ },+ {+ guidance: true,+ description:+ 'Direct math parser calls use MathParseOptions and the explicit WithMath node unions; incremental calls also use createIncrementalState<true>() and IncrementalParseState<true>. Default calls keep the legacy unions.',+ },+ {+ guidance: true,+ description:+ 'Headings render id attributes matching useOutlineFromMarkdown ids; pair with Outline for hash navigation.',+ },+ {+ guidance: false,+ description:+ 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.',+ },],},propDescriptions: {children: 'markdown string',density: "Block spacing. 'default'|'compact'. Default: 'default'.",- headingLevelStart: 'Maps # to this heading level (1-6). Clamped to h6. Default: 1.',- isStreaming: 'Incremental parse + fade-in for streamed chunks. Default: false.',- onLinkClick: '(href, event) => void|false. Return false prevents navigation.',- sources: 'Record<string, MarkdownSource>. Citation sources by ID. [id]/【id】 markers render as chips.',- citationStyle: "'label'|'number'. label=chip w/ title+icon, number=compact badge. Default: 'label'.",- contentWidth: 'number|string. Max width for prose (headings, paragraphs, lists). Tables/code unconstrained.',- contentAlign: "'start'|'center'. Prose alignment when contentWidth < container. Default: 'start'.",- inlinePlugins: 'MarkdownInlinePlugin[]. Regex matches in text nodes -> custom inline React elements. Skips inline/fenced code.',- autolink: "'gfm'. Opt-in GFM autolinking: bare URLs (https?://, www.), <scheme:url>, <email>, user@host. Skips code, code blocks, existing links. Default: off.",+ headingLevelStart:+ 'Maps # to this heading level (1-6). Clamped to h6. Default: 1.',+ isStreaming:+ 'Incremental parse + fade-in for streamed chunks. Default: false.',+ onLinkClick:+ '(href, event) => void|false. Return false prevents navigation.',+ sources:+ 'Record<string, MarkdownSource>. Citation sources by ID. [id]/【id】 markers render as chips.',+ citationStyle:+ "'label'|'number'. label=chip w/ title+icon, number=compact badge. Default: 'label'.",+ contentWidth:+ 'number|string. Max width for prose (headings, paragraphs, lists). Tables/code unconstrained.',+ contentAlign:+ "'start'|'center'. Prose alignment when contentWidth < container. Default: 'start'.",+ inlinePlugins:+ 'MarkdownInlinePlugin[]. Regex matches in text nodes -> custom inline React elements. Skips inline/fenced code and math.',+ autolink:+ "'gfm'. Opt-in GFM autolinking: bare URLs (https?://, www.), <scheme:url>, <email>, user@host. Skips code, code blocks, existing links. Default: off.",+ components:+ 'MarkdownComponents. Custom renderers; math({value, display}) opts into $…$/$$…$$ parsing. Renderer owns output and accessibility.',xstyle: 'stylex.create() for layout (margins, sizing).',className: 'CSS class. Prefer xstyle.',style: 'Inline styles. Prefer xstyle.',diff --git a/packages/core/src/Markdown/Markdown.public.test.ts b/packages/core/src/Markdown/Markdown.public.test.tsnew file mode 100644index 0000000000..54d0d886e9--- /dev/null+++ b/packages/core/src/Markdown/Markdown.public.test.ts@@ -0,0 +1,157 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Markdown.public.test.ts+ * @input Imports Markdown parser functions and node types from the public barrel+ * @output Compile-time compatibility coverage for legacy and math-enabled results+ * @position Public API test guarding @astryxdesign/core/Markdown+ */++import {describe, expectTypeOf, it} from 'vitest';+import {+ createIncrementalState,+ parseInline,+ parseMarkdown,+ parseMarkdownIncremental,+} from './index';+import type {+ BlockNode,+ BlockNodeWithMath,+ InlineNode,+ InlineNodeWithMath,+ ParseOptions,+} from './index';++function assertNever(value: never): never {+ throw new Error(`Unexpected node: ${JSON.stringify(value)}`);+}++// Existing exhaustive consumers must not gain a new case when they do not opt+// into math parsing. These functions fail to compile if the legacy unions widen.+function legacyInlineText(node: InlineNode): string {+ switch (node.type) {+ case 'text':+ case 'code':+ return node.content;+ case 'bold':+ case 'italic':+ case 'strikethrough':+ case 'link':+ return node.children.map(legacyInlineText).join('');+ case 'image':+ return node.alt;+ case 'citation':+ return node.sourceId;+ case 'break':+ return '\n';+ default:+ return assertNever(node);+ }+}++function legacyBlockText(node: BlockNode): string {+ switch (node.type) {+ case 'heading':+ case 'paragraph':+ return node.children.map(legacyInlineText).join('');+ case 'codeblock':+ return node.content;+ case 'blockquote':+ return node.children.map(legacyBlockText).join('\n');+ case 'list':+ return node.items+ .flatMap(item => item.children.map(legacyBlockText))+ .join('\n');+ case 'table':+ return [...node.headers, ...node.rows.flat()]+ .flatMap(cell => cell.children.map(legacyInlineText))+ .join(' ');+ case 'image':+ return node.alt;+ case 'hr':+ return '';+ default:+ return assertNever(node);+ }+}++describe('Markdown public parser types', () => {+ it('keeps default and legacy parser calls on the legacy unions', () => {+ expectTypeOf(parseInline('plain')).toEqualTypeOf<InlineNode[]>();+ expectTypeOf(parseInline('plain', new Set<string>())).toEqualTypeOf<+ InlineNode[]+ >();+ expectTypeOf(parseMarkdown('plain')).toEqualTypeOf<BlockNode[]>();+ expectTypeOf(parseMarkdown('plain', {math: false})).toEqualTypeOf<+ BlockNode[]+ >();+ const annotatedOptions: ParseOptions = {autolink: 'gfm'};+ expectTypeOf(parseInline('plain', annotatedOptions)).toEqualTypeOf<+ InlineNode[]+ >();+ expectTypeOf(parseMarkdown('plain', annotatedOptions)).toEqualTypeOf<+ BlockNode[]+ >();+ expectTypeOf(+ parseMarkdownIncremental(+ 'plain',+ createIncrementalState(),+ annotatedOptions,+ ),+ ).toEqualTypeOf<BlockNode[]>();+ expectTypeOf(+ parseMarkdownIncremental('plain', createIncrementalState()),+ ).toEqualTypeOf<BlockNode[]>();+ expectTypeOf(createIncrementalState().settledBlocks).toEqualTypeOf<+ BlockNode[]+ >();+ expectTypeOf(legacyInlineText).returns.toBeString();+ expectTypeOf(legacyBlockText).returns.toBeString();+ });++ it('rejects ambiguous math options and structurally forged state', () => {+ function compileOnlyGuards() {+ const dynamicOptions: {math: boolean} = {math: true};+ // @ts-expect-error callers must narrow to ParseOptions or MathParseOptions+ parseMarkdown('$$x$$', dynamicOptions);++ const structuralState = {+ prevInput: '',+ settledText: '',+ settledBlocks: [] as BlockNode[],+ settledUpTo: 0,+ };+ // @ts-expect-error math caches must come from createIncrementalState<true>()+ parseMarkdownIncremental('$$x$$', structuralState, {math: true});+ }++ expectTypeOf(compileOnlyGuards).toBeFunction();+ });++ it('types direct and incremental math opt-ins with explicit math unions', () => {+ const inline = parseInline('$x$', {math: true});+ const direct = parseMarkdown('$$x$$', {math: true});+ const incremental = parseMarkdownIncremental(+ '$$x$$',+ createIncrementalState<true>(),+ {math: true},+ );++ // A state carries the same node contract as the parser result it caches.+ // @ts-expect-error math parsing requires a math-enabled incremental state+ parseMarkdownIncremental('$$x$$', createIncrementalState(), {math: true});++ expectTypeOf(inline).toEqualTypeOf<InlineNodeWithMath[]>();+ expectTypeOf(direct).toEqualTypeOf<BlockNodeWithMath[]>();+ expectTypeOf(incremental).toEqualTypeOf<BlockNodeWithMath[]>();+ expectTypeOf(createIncrementalState<true>().settledBlocks).toEqualTypeOf<+ BlockNodeWithMath[]+ >();+ expectTypeOf<+ Extract<InlineNodeWithMath, {type: 'math'}>['value']+ >().toBeString();+ expectTypeOf<+ Extract<BlockNodeWithMath, {type: 'math'}>['value']+ >().toBeString();+ });+});diff --git a/packages/core/src/Markdown/Markdown.spec.md b/packages/core/src/Markdown/Markdown.spec.mdindex b9ba3f7f95..c47b870132 100644--- a/packages/core/src/Markdown/Markdown.spec.md+++ b/packages/core/src/Markdown/Markdown.spec.md@@ -3,41 +3,54 @@ schema_version: 3template_version: 3kind: componentid: component:Markdown-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-09-13owners: [cixzhang]-review_triggers: [theming]+review_triggers: [api, theming]verified_by:[packages/core/src/Markdown/Markdown.test.tsx,+ packages/core/src/Markdown/Markdown.public.test.ts,+ packages/core/src/Markdown/parser.test.ts,+ packages/core/src/Markdown/incremental.test.ts,packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]modules: []families: [family:navigation-destinations]design_specs: []-architecture: [architecture:component-theming-surface]+architecture:+ [architecture:component-theming-surface, architecture:public-component-api]contributing: []-system_specs: [spec:AST-005/DEC-1, spec:AST-005/DEC-2]+system_specs:+ [+ spec:AST-002/DEC-1,+ spec:AST-002/DEC-5,+ spec:AST-005/DEC-1,+ spec:AST-005/DEC-2,+ ]---# Markdown component contract## Intent-Markdown renders parsed content in a Document with stable default block parts.-This draft records the nine current Markdown targets and the custom-renderer-boundary without changing parsing, runtime behavior, styling, targets, or public-API.+Markdown renders parsed content in a Document with stable default block parts and+constrained renderer seams. In addition to the existing element overrides and+prose-only inline plugins, a caller may opt a document into dollar-delimited math+by supplying one typed renderer for both inline and display expressions. The+parser exposes the same syntax only through an explicit option. Existing parsing,+rendering, styling, and streaming behavior remain unchanged when math is absent.## Compatibility and migration- Released default preserved: `yes`-- Compatibility class: additive documentation only; runtime, DOM, styling,- targets, aliases, and public API remain unchanged+- Compatibility class: additive, opt-in public API; existing parser nodes, DOM,+ styling, targets, and dollar-delimited text remain unchanged unless the caller+ supplies `components.math` or passes `{math: true}` to a parser.- Controlled/uncontrolled behavior: not applicable- Migration decision: none@@ -52,33 +65,51 @@ Consumer migration instructions belong in consumer docs and release notes.Image block presentation and the eight current block targets documented below.- Applying block spacing and reflected density (plus Heading level) to thosetargets on the default render path.+- Opt-in recognition of `$…$` inline math and `$$…$$` display math, including+ delimiter boundaries, escape behavior, parser nodes, and streaming parity.+- Passing each recognized expression as inert text to the caller's one math+ renderer with an `inline` or `block` display value.**Does not own / non-goals**-- Output supplied by custom `heading`, `paragraph`, `code`, `blockquote`, `hr`,- or `image` renderers; the custom component owns that replacement's structure- and styling.-- Inline emphasis, link, inline-code, citation, or plugin output as additional- block anatomy.+- Output supplied by custom renderers; each custom component owns its replacement's+ structure, styling, and accessibility semantics.+- Inline emphasis, link, inline-code, citation, plugin, or math-renderer output as+ additional default block anatomy.- Nested anatomy or targets owned by CodeBlock, Blockquote, List, CheckboxList,or Table.-- New block types, custom-renderer behavior, target names, public API, or runtime- behavior.+- Executing or sanitizing a renderer's math library output, raw HTML parsing,+ arbitrary AST plugins, or new list/table/inline-style override slots.## Public concepts-No new public concept is introduced. Consumer props, renderer hooks, defaults,-and usage remain documented in `Markdown.doc.mjs`.+`MarkdownComponents.math` is one optional renderer with the signature+`({value: string, display: 'inline' | 'block'}) => ReactNode`. Supplying it opts+the component into math parsing because the caller owns both whether dollar+syntax means math and how formulas are rendered. Direct parser callers make the+same choice with `MathParseOptions` (`{math: true}`); incremental callers pair+that option with `createIncrementalState<true>()`, which returns the exported+`IncrementalParseState<true>`. Default calls and values+annotated as `ParseOptions` keep the released `InlineNode` and `BlockNode`+unions. Enabled calls return the explicit `InlineNodeWithMath` and+`BlockNodeWithMath` supersets, whose added leaves are `MathInlineNode` and+`MathBlockNode`. Exact syntax and examples remain in `Markdown.doc.mjs`.## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------ |-| FR1 | Block and inline displays render one Document root carrying the current `markdown` target. Inline display renders no block anatomy. | Current source, docs, and tests | Verified current behavior; no new behavior decided |-| FR2 | On the default block render path, Heading, Paragraph, List, Code block, Blockquote, Table, Divider, and Image carry the eight current local block targets documented below. | Current source, docs, tests, and history | Verified current inventory and placement |-| FR3 | A supplied `heading`, `paragraph`, `code`, `blockquote`, `hr`, or safe-URL `image` renderer replaces the corresponding default part, so Markdown does not impose that part's local target on the replacement. | Current source, docs, and history | Verified behavior; focused absence coverage is partial |-| FR4 | The released Code block target is spelled `markdown-codeblock`. Although this runs together a compound name and predates the current naming rule, it is a frozen public target and this factual backfill neither renames it nor adds an alias. | Current source, docs, tests, history, and architecture | Verified compatibility constraint; no target change |-| FR5 | Density and Heading level remain reflected capabilities on their owning targets. Display mode, density, Heading level, streaming state, list kind, and custom-renderer selection do not become separate anatomy entries. | Current source, docs, tests, and architecture | Verified current model; no new anatomy or state target |+| ID | Invariant |+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | Block and inline displays render one Document root carrying the current `markdown` target. Inline display renders no block anatomy. |+| FR2 | On the default block render path, Heading, Paragraph, List, Code block, Blockquote, Table, Divider, and Image carry the eight current local block targets documented below. |+| FR3 | A supplied `heading`, `paragraph`, `code`, `blockquote`, `hr`, or safe-URL `image` renderer replaces the corresponding default part, so Markdown does not impose that part's local target on the replacement. |+| FR4 | The released Code block target remains `markdown-codeblock`; this compatibility anomaly is not renamed or aliased. |+| FR5 | Density and Heading level remain reflected capabilities on their owning targets. Display mode, streaming state, and renderer selection do not become separate anatomy entries. |+| FR6 | Without `components.math`, Markdown does not recognize math syntax. Default, legacy-set, `math: false`, and `ParseOptions`-annotated parser calls retain the released `InlineNode` / `BlockNode` result unions; only `MathParseOptions` returns the explicit math-enabled unions. |+| FR7 | With math enabled, `$…$` produces an inline `math` node and `$$…$$` produces a block `math` node. The renderer receives the delimiter-free source as `value` and its placement as `display`. |+| FR8 | Inline math stays on one line, cannot have whitespace touching either delimiter, and cannot open immediately after a digit or close immediately before one. `$$` is reserved for display math. These boundaries keep paired currency amounts literal. |+| FR9 | A backslash-escaped dollar is literal outside math and does not close math inside it. An unmatched inline or display delimiter remains literal in non-streaming output. |+| FR10 | Code spans and fenced code blocks are opaque to math parsing. Link destinations are opaque; link labels may contain inline math. Inline plugins run only on prose text and never inside math. |+| FR11 | Streaming converges to the same nodes as a full parse at every chunk boundary, including display math nested in ordinary lists, task lists, blockquotes, and their supported combinations, with LF or CRLF and with or without source ranges. Incomplete math is withheld only while its exact owning container remains open; a list/quote exit or quote-depth change restores literal parsing. Math-enabled incremental calls require `IncrementalParseState<true>`, so the cache and returned union share one contract. |### Allowed variation@@ -91,51 +122,75 @@ and usage remain documented in `Markdown.doc.mjs`.- **AV4 — Nested primitives.** Astryx primitives used inside default blocks maychange internal element shape while preserving their own public contracts andMarkdown's outer block targets.+- **AV5 — Math renderer.** The caller may use any renderer that accepts the raw+ expression and display value. Its DOM, styles, typesetting engine, error UI,+ and accessibility representation are outside Markdown's ownership.### Representative states-| State | Required invariant | Allowed variation |-| ---------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |-| Default block content | Every parsed block uses its corresponding current Markdown target. | Block count, order, density, content width, and alignment. |-| Custom block renderers | The replaced Heading, Paragraph, Code block, Blockquote, Divider, or Image lacks the corresponding Markdown target. | Replacement structure and styling. |-| Ordered/unordered list | List carries `markdown-list`. | Marker kind, start value, item count, and nested content. |-| Task list | The outer List part carries `markdown-list`. | Checked values and item content. |-| Safe block image | Default Image carries `markdown-image`, or a custom image renderer replaces it. | Source and alternative text. |-| Unsafe block image URL | Markdown renders its fallback Image part with `markdown-image`; no custom image renderer receives the rejected URL. | Alternative text shown by the fallback. |-| Inline display | Document carries `markdown`; no block target renders. | Inline text, links, code, citations, and plugin output. |+| State | Required invariant | Allowed variation |+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |+| Default block content | Every parsed block uses its corresponding current Markdown target. | Block count, order, density, content width, and alignment. |+| Custom block renderers | The replaced Heading, Paragraph, Code block, Blockquote, Divider, or Image lacks the corresponding Markdown target. | Replacement structure and styling. |+| Ordered/unordered list | List carries `markdown-list`. | Marker kind, start value, item count, and nested content. |+| Task list | The outer List part carries `markdown-list`. | Checked values and item content. |+| Safe block image | Default Image carries `markdown-image`, or a custom image renderer replaces it. | Source and alternative text. |+| Unsafe block image URL | Markdown renders its fallback Image part with `markdown-image`; no custom image renderer receives the rejected URL. | Alternative text shown by the fallback. |+| Inline display | Document carries `markdown`; no block target renders. | Inline text, links, code, citations, plugins, and opt-in inline math. |+| Math renderer absent | Dollar-delimited source follows the released Markdown grammar and no `math` node or renderer output exists. | Currency, unmatched delimiters, and ordinary prose. |+| Math renderer present | Complete supported delimiters are opaque to Markdown formatting and are passed to the renderer as inert text. | Inline or block display and any renderer-owned output. |+| Streaming math | Incomplete math is withheld; once complete, the streamed nodes equal the full-parse nodes at top level and inside list/blockquote containers. | Delimiters and expression text may arrive in separate chunks; source ranges remain optional. |### Transformation and precedence order-- No new parsing, sanitization, heading-level, renderer-selection, spacing, or- styling precedence rule is introduced.+- Fenced and inline code claim their contents before math.+- Complete display math claims a block before headings, tables, lists, and+ paragraphs. Complete inline math claims its source before citations, links,+ emphasis, autolinks, and inline plugins.+- A custom renderer receives only the delimiter-free expression string and its+ display value. Markdown never turns it into HTML or executes it.+- Existing URL sanitization remains in force for links and images; math adds no+ navigation or raw-HTML sink.### Performance and resources-- No new parsing, streaming, render, or resource requirement is introduced.+- Math scanning is disabled unless requested.+- Inline matching is a bounded forward scan of one line. Display matching scans+ only from a candidate `$$` opener to its closer.+- The incremental parser keeps completed blocks cached, treats an open display+ expression like an open code fence, and tracks exact list and blockquote+ container depth so an indented closer cannot become a new opener and a depth+ transition cannot swallow literal content. The factory-created state carries+ the same legacy or math-enabled node contract as the parser call.## Accessibility contract-This draft does not change or extend Markdown's existing document semantics,-heading IDs, paragraph role, list semantics, scrollable Table wrapper, image-alternative text, or custom-renderer responsibilities.+The default document semantics, heading IDs, paragraph role, list semantics,+scrollable Table wrapper, and image alternative text remain unchanged. Math has+no Astryx-owned default output: the caller's renderer owns an accessible+representation appropriate to its typesetting engine (for example MathML or a+labelled `role="math"` element). Markdown adds no wrapper, ARIA attributes, or+HTML injection around renderer output.## Design relationships-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |-| ---------------- | -------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |-| Document | Contains block or inline rendered Markdown content. | Current source and public docs | Supporting | FR1, FR5 |-| Heading | Presents one parsed heading with its resolved level and optional generated ID. | Current source and public docs | Prominent | FR2, FR3, FR5 |-| Paragraph | Presents one prose block using the default composition-safe paragraph structure. | Current source and public docs | Prominent | FR2, FR3 |-| List | Presents ordered, unordered, or task-list items as one block. | Current source and public docs | Prominent | FR2, FR5 |-| Code block | Presents fenced code and owns the outer spacing target on the default path. | Current source and public docs | Prominent | FR2, FR3, FR4 |-| Blockquote | Presents quoted block content on the default path. | Current source and public docs | Prominent | FR2, FR3 |-| Table | Presents parsed rows and columns in a keyboard-scrollable block wrapper. | Current source and public docs | Prominent | FR2 |-| Divider | Presents a horizontal separation between blocks. | Current source and public docs | Supporting | FR2, FR3 |-| Image | Presents a safe block image or the fallback for a rejected image URL. | Current source and public docs | Prominent | FR2, FR3 |--Custom renderers replace six default parts rather than becoming nested Markdown-anatomy. Lists and Tables have no corresponding custom block renderer. The-Document remains Markdown-owned in every display mode.+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | ---------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |+| Document | Contains block or inline rendered Markdown content. | Current source and public docs | Supporting | FR1, FR5 |+| Heading | Presents one parsed heading with its resolved level and optional generated ID. | Current source and public docs | Prominent | FR2, FR3, FR5 |+| Paragraph | Presents one prose block using the default composition-safe paragraph structure. | Current source and public docs | Prominent | FR2, FR3 |+| List | Presents ordered, unordered, or task-list items as one block. | Current source and public docs | Prominent | FR2, FR5 |+| Code block | Presents fenced code and owns the outer spacing target on the default path. | Current source and public docs | Prominent | FR2, FR3, FR4 |+| Blockquote | Presents quoted block content on the default path. | Current source and public docs | Prominent | FR2, FR3 |+| Table | Presents parsed rows and columns in a keyboard-scrollable block wrapper. | Current source and public docs | Prominent | FR2 |+| Divider | Presents a horizontal separation between blocks. | Current source and public docs | Supporting | FR2, FR3 |+| Image | Presents a safe block image or the fallback for a rejected image URL. | Current source and public docs | Prominent | FR2, FR3 |+| Math | Delegates an explicitly enabled expression to the caller's renderer as inert text. | Component contract | Supporting | FR6–FR11 |++Custom renderers replace the existing default parts rather than becoming nested+Markdown anatomy. The opt-in math renderer is also not default anatomy and gets no+Markdown theme target or wrapper. Lists and Tables have no corresponding custom+block renderer. The Document remains Markdown-owned in every display mode.### Theming anatomy@@ -167,6 +222,12 @@ and this change preserves the existing spelling exactly.- `architecture:component-theming-surface` owns anatomy qualification, targetmapping, target-capability state, composition boundaries, and compatibility forfrozen targets.+- `architecture:public-component-api` and `spec:AST-002/DEC-1` own API+ admission. The caller knows whether dollar syntax is math and must choose the+ renderer; Markdown cannot derive either from the source without changing the+ meaning of existing documents.+- `spec:AST-002/DEC-5` requires this accepted component-local contract to be+ current with the implementation.- `family:navigation-destinations` owns the shared accept/block result for parsedlinks and every Astryx-owned navigation sink. `spec:AST-005/DEC-1` requiresMarkdown navigation to remain conformant with Core link plumbing.@@ -178,22 +239,40 @@ and this change preserves the existing spelling exactly.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------ |-| FR1 | `Markdown.test.tsx` root-class, block-root, inline-root, and base-prop suites | Block and inline Document | Removing or moving the root target fails focused root assertions or the global inventory. | `audit:Markdown/anatomy` |-| FR2, FR4, FR5 | `Markdown.test.tsx` block-spacing-target, density, Heading-level, task-list, and render suites | All eight default block types, both densities, Heading level | Removing, renaming, or moving a block target fails focused class or reflected-property assertions. | `audit:Markdown/theming` |-| FR3 | `Markdown.test.tsx` custom Heading and custom Image suites plus source and target-introduction history | Six replaceable default block parts | Imposing a target on a custom replacement violates the owner boundary; only Heading absence is directly pinned today. | `audit:Markdown/theming` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and all nine current targets | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:Markdown/theming` |+| Contract | Verification | Representative states | Failure signal |+| ---------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR5 | `Markdown.test.tsx`, theme-target tests, and `scripts/check-knowledge.mjs` | Default block/inline output and all current targets | Existing DOM, target, spacing, or renderer behavior changes. |+| FR6–FR10 | `parser.test.ts` and `Markdown.test.tsx` | Opt-out, inline/display math, escapes, currency, code, links, plugins | A delimiter is claimed without opt-in, TeX is formatted as Markdown, or opaque contexts leak. |+| FR11 | `incremental.test.ts` and `Markdown.test.tsx` | Every-character top-level/list/task-list/blockquote splits, CRLF, source ranges | Streaming diverges from a full parse, shows partial syntax, mistakes a nested closer for an opener, or crosses a closed container. |+| Public syntax/types | `Markdown.public.test.ts`, core typecheck, and `Markdown.doc.mjs` | Legacy exhaustive switches, component renderer, full and incremental math opt-ins | A legacy union widens, math-enabled results omit math nodes, or docs drift from declarations. |+| Security/accessibility | `parser.test.ts`, `Markdown.test.tsx`, and renderer guidance | Inert expression strings and renderer-owned semantics | Astryx executes math as HTML or silently claims renderer-owned accessibility. |-Focused tests pin all nine current target names and default block placement. They-pin target absence only for a custom Heading; custom Paragraph, Code block,-Blockquote, Divider, and Image replacement paths currently rely on source and-history for the same ownership rule.+Focused tests continue to pin all nine current target names and default block+placement. Math intentionally adds no target and no default anatomy.## Decision log-None. This draft records current facts and introduces no component-local design,-API, behavior, or theming decision.+### DEC-1 — Math is an opt-in renderer contract++**Reference:** `component:Markdown/DEC-1`+**Decider:** `cixzhang`, `2026-09-13`++A caller that supplies `components.math` opts the component into the constrained+dollar-math grammar and receives every complete expression through one renderer+with its source value and inline/block placement. Direct parser callers use+`MathParseOptions`; incremental callers also create+`IncrementalParseState<true>` via `createIncrementalState<true>()` so the cache+and result expose the same math-enabled node union.++This passes API admission because otherwise identical dollar-delimited source may+be prose or math, only the document host knows which meaning applies, and Astryx+cannot choose a typesetting or accessibility implementation for the host. Tying+the opt-in to the required renderer prevents an enabled-but-unrenderable state.+The default remains exactly the released Markdown grammar.++Rejected: a generic AST/plugin escape hatch, raw HTML rendering, new list/table+slots without consumer evidence, or a separate boolean on the component that+could enable math without a renderer.## Open questionsdiff --git a/packages/core/src/Markdown/Markdown.test.tsx b/packages/core/src/Markdown/Markdown.test.tsxindex 21a0a8438d..017cfc441a 100644--- a/packages/core/src/Markdown/Markdown.test.tsx+++ b/packages/core/src/Markdown/Markdown.test.tsx@@ -1,10 +1,19 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';+import {+ describe,+ it,+ expect,+ expectTypeOf,+ vi,+ beforeEach,+ afterEach,+} from 'vitest';import {render, screen, fireEvent} from '@testing-library/react';-import type {ReactNode} from 'react';+import type {ComponentProps, ReactNode} from 'react';import {Markdown} from './Markdown';-import type {MarkdownInlinePlugin} from './Markdown';+import type {MarkdownComponents, MarkdownInlinePlugin} from './Markdown';+import type {ParseOptions} from './index';import {stubMatchMedia} from '../__tests__/stubMatchMedia';import {parseOutlineFromMarkdown} from '../Outline/parseOutlineFromMarkdown';@@ -615,6 +624,53 @@ describe('Markdown', () => {expect(links[0].getAttribute('href')).toBe('https://example.com');expect(links[1].getAttribute('href')).toBe('/page');});++ it('preserves dollar-delimited text when no math renderer is supplied', () => {+ const {container} = render(+ <Markdown>{'Total $5 and formula $x_1 + *y*$.'}</Markdown>,+ );+ expect(container.textContent).toBe('Total $5 and formula $x_1 + y$.');+ expect(container.querySelector('em')).toHaveTextContent('y');+ expect(container.querySelector('[role="math"]')).toBeNull();+ });++ it('passes inline and display expressions to the custom math renderer', () => {+ type MathRendererProps = ComponentProps<+ NonNullable<MarkdownComponents['math']>+ >;+ function MathRenderer({value, display}: MathRendererProps) {+ const Tag = display === 'block' ? 'div' : 'span';+ return (+ <Tag+ role="math"+ aria-label={`Formula: ${value}`}+ data-testid={`${display}-math`}>+ {value}+ </Tag>+ );+ }++ render(+ <Markdown components={{math: MathRenderer}}>+ {'Inline $x_1 + *y*$ here.\n\n$$\n\\sum_i x_i\n$$'}+ </Markdown>,+ );++ expect(screen.getByTestId('inline-math')).toHaveTextContent('x_1 + *y*');+ expect(screen.getByTestId('block-math')).toHaveTextContent('\\sum_i x_i');+ expect(screen.getAllByRole('math')).toHaveLength(2);+ });++ it('exports the math renderer and parser option types', () => {+ type MathRendererProps = ComponentProps<+ NonNullable<MarkdownComponents['math']>+ >;+ expectTypeOf<MathRendererProps>().toEqualTypeOf<{+ value: string;+ display: 'inline' | 'block';+ }>();+ expectTypeOf<ParseOptions>().toMatchTypeOf<{math?: boolean}>();+ });});// ---------------------------------------------------------------------------@@ -667,6 +723,54 @@ describe('inlinePlugins', () => {expect(link!.textContent).toBe('PROJ-123');});+ it('autolinks generic prefixed-number entities without rewriting source', () => {+ const entityPlugin: MarkdownInlinePlugin = {+ pattern: /\b([A-Z][A-Z0-9]+-\d+)\b/g,+ render: (match, key) => (+ <a key={key} href={`/entities/${match[1]}`} data-testid="entity-link">+ {match[0]}+ </a>+ ),+ };+ const {container} = render(+ <Markdown inlinePlugins={[entityPlugin]}>+ {'See DOC-2048, but keep `DOC-9999` literal.'}+ </Markdown>,+ );+ const link = screen.getByTestId('entity-link');+ expect(link).toHaveAttribute('href', '/entities/DOC-2048');+ expect(link).toHaveTextContent('DOC-2048');+ expect(container.querySelector('code')).toHaveTextContent('DOC-9999');+ expect(+ container.querySelectorAll('[data-testid="entity-link"]'),+ ).toHaveLength(1);+ });++ it('keeps math opaque to entity plugins while transforming surrounding prose', () => {+ const entityPlugin: MarkdownInlinePlugin = {+ pattern: /\b(DOC-\d+)\b/g,+ render: (match, key) => (+ <a key={key} href={`/entities/${match[1]}`} data-testid="entity-link">+ {match[0]}+ </a>+ ),+ };+ const MathRenderer: NonNullable<MarkdownComponents['math']> = ({value}) => (+ <span role="math">{value}</span>+ );+ render(+ <Markdown+ components={{math: MathRenderer}}+ inlinePlugins={[entityPlugin]}>+ {'DOC-1 and $DOC-2 + x$ and `DOC-3`'}+ </Markdown>,+ );+ expect(screen.getAllByTestId('entity-link')).toHaveLength(1);+ expect(screen.getByTestId('entity-link')).toHaveTextContent('DOC-1');+ expect(screen.getByRole('math')).toHaveTextContent('DOC-2 + x');+ expect(screen.getByText('DOC-3').tagName).toBe('CODE');+ });+it('supports multiple plugins', () => {const {container} = render(<Markdown inlinePlugins={[createTicketPlugin(), createXRefPlugin()]}>diff --git a/packages/core/src/Markdown/Markdown.tsx b/packages/core/src/Markdown/Markdown.tsxindex 0ba2449fa8..75e68af7c7 100644--- a/packages/core/src/Markdown/Markdown.tsx+++ b/packages/core/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(() => {diff --git a/packages/core/src/Markdown/incremental.test.ts b/packages/core/src/Markdown/incremental.test.tsindex edb61e66b4..18b2df4578 100644--- a/packages/core/src/Markdown/incremental.test.ts+++ b/packages/core/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));diff --git a/packages/core/src/Markdown/index.ts b/packages/core/src/Markdown/index.tsindex 3aa229ef48..47f1614ddc 100644--- a/packages/core/src/Markdown/index.ts+++ b/packages/core/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';diff --git a/packages/core/src/Markdown/parser.perf.test.ts b/packages/core/src/Markdown/parser.perf.test.tsindex e0acf324aa..bbe078ccb8 100644--- a/packages/core/src/Markdown/parser.perf.test.ts+++ b/packages/core/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();diff --git a/packages/core/src/Markdown/parser.test.ts b/packages/core/src/Markdown/parser.test.tsindex 65c6f89fc3..01ddda255c 100644--- a/packages/core/src/Markdown/parser.test.ts+++ b/packages/core/src/Markdown/parser.test.ts@@ -42,6 +42,73 @@ describe('parseInline', () => {expect(result).toEqual([{type: 'code', content: 'const x'}]);});+ it('leaves math delimiters as literal text by default', () => {+ expect(parseInline('Euler: $e^{i * pi} + 1 = 0$.')).toEqual([+ {type: 'text', content: 'Euler: $e^{i * pi} + 1 = 0$.'},+ ]);+ });++ it('parses inline math before Markdown formatting when explicitly enabled', () => {+ expect(parseInline('Euler: $e^{i * pi} + 1 = 0$.', {math: true})).toEqual([+ {type: 'text', content: 'Euler: '},+ {type: 'math', value: 'e^{i * pi} + 1 = 0'},+ {type: 'text', content: '.'},+ ]);+ });++ it('preserves escaped delimiters inside math and leaves escaped openers literal', () => {+ expect(+ parseInline('Price: \\$5; formula: $x \\$ y$.', {math: true}),+ ).toEqual([+ {type: 'text', content: 'Price: '},+ {type: 'text', content: '$5; formula: '},+ {type: 'math', value: 'x \\$ y'},+ {type: 'text', content: '.'},+ ]);+ });++ it('leaves an unmatched inline math delimiter literal', () => {+ expect(parseInline('The value is $x + 1.', {math: true})).toEqual([+ {type: 'text', content: 'The value is $x + 1.'},+ ]);+ });++ it('does not mistake paired currency amounts for inline math', () => {+ expect(+ parseInline('Tickets cost $20 and $30 today.', {math: true}),+ ).toEqual([{type: 'text', content: 'Tickets cost $20 and $30 today.'}]);+ expect(parseInline('$x$5 and $y$', {math: true})).toEqual([+ {type: 'text', content: '$x$5 and '},+ {type: 'math', value: 'y'},+ ]);+ });++ it('allows an inline expression to begin with a number', () => {+ expect(parseInline('Result: $2 + 2$.', {math: true})).toEqual([+ {type: 'text', content: 'Result: '},+ {type: 'math', value: '2 + 2'},+ {type: 'text', content: '.'},+ ]);+ });++ it('does not treat non-block double-dollar runs as inline math', () => {+ expect(parseInline('Keep $$x + y$$ literal.', {math: true})).toEqual([+ {type: 'text', content: 'Keep $$x + y$$ literal.'},+ ]);+ });++ it('keeps code and link destinations opaque while parsing math in link labels', () => {+ expect(parseInline('`$code$` [$label$](/price/$5)', {math: true})).toEqual([+ {type: 'code', content: '$code$'},+ {type: 'text', content: ' '},+ {+ type: 'link',+ href: '/price/$5',+ children: [{type: 'math', value: 'label'}],+ },+ ]);+ });+it('parses links', () => {const result = parseInline('[click](https://example.com)');expect(result[0].type).toBe('link');@@ -270,6 +337,61 @@ describe('parseMarkdown', () => {}});+ it('parses display math only when explicitly enabled', () => {+ const source = '$$\n\\int_0^1 x^2 \\, dx\n$$';+ expect(parseMarkdown(source)).not.toContainEqual({+ type: 'math',+ value: '\\int_0^1 x^2 \\, dx',+ });+ expect(parseMarkdown(source, {math: true})).toEqual([+ {type: 'math', value: '\\int_0^1 x^2 \\, dx'},+ ]);+ });++ it('parses a same-line display math block', () => {+ expect(parseMarkdown('$$E = mc^2$$', {math: true})).toEqual([+ {type: 'math', value: 'E = mc^2'},+ ]);+ });++ it('keeps empty display delimiters literal', () => {+ const source = '$$\n$$';+ expect(parseMarkdown(source, {math: true})).toEqual(parseMarkdown(source));+ });++ it('leaves unmatched display math delimiters literal', () => {+ const source = '$$\nx + y';+ expect(parseMarkdown(source, {math: true})).toEqual(parseMarkdown(source));+ });++ it('leaves escaped display delimiters literal', () => {+ const blocks = parseMarkdown('\\$\\$\nx + y\n\\$\\$', {math: true});+ expect(blocks.some(block => block.type === 'math')).toBe(false);+ });++ it('reports a display-math source range including its delimiters', () => {+ const source = 'Before.\n\n$$\nx + y\n$$\n\nAfter.';+ const blocks = parseMarkdown(source, {math: true, sourceRanges: true});+ expect(blocks[1]?.range).toEqual({start: 9, end: 20});+ expect(source.slice(blocks[1].range?.start, blocks[1].range?.end)).toBe(+ '$$\nx + y\n$$',+ );+ });++ it('keeps fenced code opaque when math parsing is enabled', () => {+ expect(parseMarkdown('```tex\n$x$\n$$y$$\n```', {math: true})).toEqual([+ {type: 'codeblock', language: 'tex', content: '$x$\n$$y$$'},+ ]);+ });++ it('does not collect link definitions from display math', () => {+ const blocks = parseMarkdown('$$\n[x]: /not-a-link\n$$\n\n[x]', {+ math: true,+ });+ expect(blocks[0]).toEqual({type: 'math', value: '[x]: /not-a-link'});+ expect(JSON.stringify(blocks[1])).not.toContain('"type":"link"');+ });+it('parses blockquotes', () => {const result = parseMarkdown('> This is a quote');expect(result[0].type).toBe('blockquote');diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.tsindex 6c0215ab83..6dee3b2eb9 100644--- a/packages/core/src/Markdown/parser.ts+++ b/packages/core/src/Markdown/parser.ts@@ -3,7 +3,8 @@/*** @file parser.ts* @input Markdown string- * @output Array of MarkdownNode AST nodes; heading slug helpers+ * @output Array of MarkdownNode AST nodes, including opt-in math; heading slug+ * helpers* (inlineText, slugify, uniqueSlug) shared by Markdown rendering and* Outline's parseOutlineFromMarkdown* @position Core parser; consumed by Markdown.tsx and Outline@@ -13,6 +14,7 @@// Types// ---------------------------------------------------------------------------+/** Nodes returned by default and legacy parser calls. */export type InlineNode =| {type: 'text'; content: string}| {type: 'bold'; children: InlineNode[]}@@ -24,7 +26,23 @@ export type InlineNode =| {type: 'citation'; sourceId: string}| {type: 'break'};-export type BlockNode = BlockNodeKind & {+/** The additional inline node returned only when parsing with `math: true`. */+export type MathInlineNode = {type: 'math'; value: string};++/** Nodes returned by an explicitly math-enabled inline parse. */+export type InlineNodeWithMath =+ | {type: 'text'; content: string}+ | {type: 'bold'; children: InlineNodeWithMath[]}+ | {type: 'italic'; children: InlineNodeWithMath[]}+ | {type: 'strikethrough'; children: InlineNodeWithMath[]}+ | {type: 'code'; content: string}+ | MathInlineNode+ | {type: 'link'; href: string; children: InlineNodeWithMath[]}+ | {type: 'image'; src: string; alt: string}+ | {type: 'citation'; sourceId: string}+ | {type: 'break'};++type BlockMetadata = {/*** Where this block came from in the source, when parsed with the* `sourceRanges` option. Top-level blocks only.@@ -32,7 +50,7 @@ export type BlockNode = BlockNodeKind & {range?: SourceRange;};-type BlockNodeKind =+type LegacyBlockNodeKind =| {type: 'heading'; level: 1 | 2 | 3 | 4 | 5 | 6; children: InlineNode[]}| {type: 'paragraph'; children: InlineNode[]}| {type: 'codeblock'; language: string; content: string}@@ -55,6 +73,43 @@ type BlockNodeKind =| {type: 'hr'}| {type: 'image'; src: string; alt: string};+/** Blocks returned by default and legacy parser calls. */+export type BlockNode = LegacyBlockNodeKind & BlockMetadata;++/** The additional block returned only when parsing with `math: true`. */+export type MathBlockNode = {type: 'math'; value: string} & BlockMetadata;++type MathEnabledBlockNodeKind =+ | {+ type: 'heading';+ level: 1 | 2 | 3 | 4 | 5 | 6;+ children: InlineNodeWithMath[];+ }+ | {type: 'paragraph'; children: InlineNodeWithMath[]}+ | {type: 'codeblock'; language: string; content: string}+ | MathBlockNode+ | {type: 'blockquote'; children: BlockNodeWithMath[]}+ | {+ type: 'list';+ ordered: boolean;+ start?: number;+ /** Ordered-list marker delimiter ('.' or ')'). Undefined for bullets. */+ delimiter?: '.' | ')';+ loose?: boolean;+ items: ListItemNodeWithMath[];+ }+ | {+ type: 'table';+ headers: TableCellNodeWithMath[];+ alignments: TableAlignment[];+ rows: TableCellNodeWithMath[][];+ }+ | {type: 'hr'}+ | {type: 'image'; src: string; alt: string};++/** Blocks returned by an explicitly math-enabled block parse. */+export type BlockNodeWithMath = MathEnabledBlockNodeKind & BlockMetadata;+/*** Where a block sits in the source string handed to `parseMarkdown`:* `source.slice(start, end)` is the block, and `end` excludes the block's@@ -67,7 +122,12 @@ type BlockNodeKind =export type SourceRange = {readonly start: number; readonly end: number};export type ListItemNode = {checked?: boolean; children: BlockNode[]};+type ListItemNodeWithMath = {+ checked?: boolean;+ children: BlockNodeWithMath[];+};export type TableCellNode = {children: InlineNode[]};+type TableCellNodeWithMath = {children: InlineNodeWithMath[]};export type TableAlignment = 'left' | 'center' | 'right' | null;// ---------------------------------------------------------------------------@@ -81,7 +141,7 @@ export type TableAlignment = 'left' | 'center' | 'right' | null;* `parseMarkdownIncremental` functions also accept the legacy* `ReadonlySet<string>` shape as the second argument.*/-export type ParseOptions = {+type CommonParseOptions = {/** Set of citation source ids — `[id]` / `【id】` markers in this set* become citation nodes instead of plain text / links. */sourceIds?: ReadonlySet<string>;@@ -109,9 +169,22 @@ export type ParseOptions = {sourceRanges?: boolean;};+/** Options for default and legacy parser results. */+export type ParseOptions = CommonParseOptions & {math?: false | undefined};++/**+ * Options that explicitly parse `$…$` and `$$…$$` into math-enabled result+ * unions. Keeping this separate prevents a legacy `ParseOptions` annotation+ * from silently widening an exhaustive node switch.+ */+export type MathParseOptions = CommonParseOptions & {math: true};++type RuntimeParseOptions = CommonParseOptions & {math?: boolean};+type ResolvedOptions = {readonly sourceIds: ReadonlySet<string> | undefined;readonly autolink: 'gfm' | undefined;+ readonly math?: boolean;readonly sourceRanges?: boolean;/*** Offset of this parse's input within the document the ranges are reported@@ -131,7 +204,7 @@ type ResolvedOptions = {const EMPTY_OPTS: ResolvedOptions = {sourceIds: undefined, autolink: undefined};function resolveOptions(- arg: ReadonlySet<string> | ParseOptions | undefined,+ arg: ReadonlySet<string> | RuntimeParseOptions | undefined,): ResolvedOptions {if (arg == null) {return EMPTY_OPTS;@@ -144,10 +217,11 @@ function resolveOptions(if (typeof (arg as {has?: unknown}).has === 'function') {return {sourceIds: arg as ReadonlySet<string>, autolink: undefined};}- const opts = arg as ParseOptions;+ const opts = arg as RuntimeParseOptions;return {sourceIds: opts.sourceIds,autolink: opts.autolink,+ math: opts.math === true ? true : undefined,sourceRanges: opts.sourceRanges,};}@@ -175,6 +249,149 @@ function normalizeLinkLabel(label: string): string {return label.trim().replace(/\s+/g, ' ').toLowerCase();}+type DisplayMathContainer = {+ outerQuoteDepth: number;+ listBaseIndent: number | null;+ innerQuoteDepth: number;+};++type DisplayMathMatch = {+ value: string;+ nextIndex: number;+ endLine: number;+};++function stripBlockquoteMarkers(line: string): {+ content: string;+ quoteDepth: number;+} {+ let content = line.endsWith('\r') ? line.slice(0, -1) : line;+ let quoteDepth = 0;+ while (true) {+ const marker = /^ {0,3}> ?/.exec(content);+ if (marker == null) {+ return {content, quoteDepth};+ }+ content = content.slice(marker[0].length);+ quoteDepth++;+ }+}++function stripExactBlockquoteDepth(+ line: string,+ quoteDepth: number,+): string | null {+ let content = line;+ for (let depth = 0; depth < quoteDepth; depth++) {+ const marker = /^ {0,3}> ?/.exec(content);+ if (marker == null) {+ return null;+ }+ content = content.slice(marker[0].length);+ }+ return content;+}++/**+ * Recognize a standalone display-math marker at the current container boundary.+ * A list opener carries its base indent so an indented continuation marker can+ * close it; blockquotes must keep the same quote depth.+ */+function displayMathContainer(line: string): DisplayMathContainer | null {+ const outer = stripBlockquoteMarkers(line);+ const listMarker = /^( {0,9})(?:[-*+]|\d+[.)]) +(.*)$/.exec(outer.content);+ if (listMarker != null) {+ const taskMarker = /^\[[ xX]\] +(.*)$/.exec(listMarker[2]);+ const inner = stripBlockquoteMarkers(taskMarker?.[1] ?? listMarker[2]);+ return inner.content.trim() === '$$'+ ? {+ outerQuoteDepth: outer.quoteDepth,+ listBaseIndent: listMarker[1].length,+ innerQuoteDepth: inner.quoteDepth,+ }+ : null;+ }+ return outer.content.trim() === '$$'+ ? {+ outerQuoteDepth: outer.quoteDepth,+ listBaseIndent: null,+ innerQuoteDepth: 0,+ }+ : null;+}++type DisplayMathLineState = 'close' | 'inside' | 'outside';++function displayMathLineState(+ line: string,+ container: DisplayMathContainer,+): DisplayMathLineState {+ const outerContent = stripExactBlockquoteDepth(+ line,+ container.outerQuoteDepth,+ );+ if (outerContent == null) {+ return 'outside';+ }++ if (container.listBaseIndent == null) {+ // A deeper quote starts a different container. It cannot close or continue+ // the math expression owned by the shallower quote.+ if (/^ {0,3}> ?/.test(outerContent)) {+ return 'outside';+ }+ return outerContent.trim() === '$$' ? 'close' : 'inside';+ }++ const continuationIndent =+ outerContent.length - outerContent.trimStart().length;+ if (continuationIndent <= container.listBaseIndent) {+ return 'outside';+ }+ const innerContent = stripExactBlockquoteDepth(+ outerContent.trimStart(),+ container.innerQuoteDepth,+ );+ if (innerContent == null || /^ {0,3}> ?/.test(innerContent)) {+ return 'outside';+ }+ return innerContent.trim() === '$$' ? 'close' : 'inside';+}++/** Match a complete `$$…$$` display-math block without consuming partial input. */+function matchDisplayMathBlock(+ lines: string[],+ lineIndex: number,+): DisplayMathMatch | null {+ const trimmed = lines[lineIndex].trim();+ if (+ trimmed.length > 4 &&+ trimmed.startsWith('$$') &&+ trimmed.endsWith('$$')+ ) {+ const value = trimmed.slice(2, -2);+ return value.trim() === ''+ ? null+ : {value, nextIndex: lineIndex + 1, endLine: lineIndex};+ }+ if (trimmed !== '$$') {+ return null;+ }+ for (let index = lineIndex + 1; index < lines.length; index++) {+ if (lines[index].trim() === '$$') {+ const value = lines.slice(lineIndex + 1, index).join('\n');+ return value.trim() === ''+ ? null+ : {+ value,+ nextIndex: index + 1,+ endLine: index,+ };+ }+ }+ return null;+}+function matchLinkDefinition(line: string,): {label: string; destination: string; hasTitle: boolean} | null {@@ -211,7 +428,10 @@ function matchLinkDefinition(* where every definition is global. Separating a footer definition block with* a blank line — the usual form — always works.*/-function extractLinkDefinitions(input: string): {+function extractLinkDefinitions(+ input: string,+ math = false,+): {defs: ReadonlyMap<string, string>;cleaned: string;/**@@ -240,6 +460,16 @@ function extractLinkDefinitions(input: string): {}continue;}+ if (math) {+ const displayMath = matchDisplayMathBlock(lines, index);+ if (displayMath != null) {+ // Math is opaque Markdown content: definition-shaped TeX must not leak+ // into the document-wide link-definition map.+ index = displayMath.endLine;+ atBoundary = true;+ continue;+ }+ }const fenceMatch = line.match(/^(`{3,}|~{3,})/);if (fenceMatch) {inFence = true;@@ -312,7 +542,7 @@ function matchReferenceLink(start: number,linkDefs: ReadonlyMap<string, string>,opts: ResolvedOptions,-): {node: InlineNode; end: number} | null {+): {node: InlineNodeWithMath; end: number} | null {const textClose = text.indexOf(']', start + 1);if (textClose === -1) {return null;@@ -357,7 +587,7 @@ function matchReferenceImage(text: string,start: number,linkDefs: ReadonlyMap<string, string>,-): {node: InlineNode; end: number} | null {+): {node: InlineNodeWithMath; end: number} | null {const altClose = text.indexOf(']', start + 2);if (altClose === -1) {return null;@@ -412,6 +642,64 @@ function isWordChar(ch: string | undefined): boolean {return /\w/.test(ch);}+/** True when the character at `index` is preceded by an odd backslash run. */+function isEscaped(text: string, index: number): boolean {+ let backslashes = 0;+ for (let i = index - 1; i >= 0 && text[i] === '\\'; i--) {+ backslashes++;+ }+ return backslashes % 2 === 1;+}++/**+ * Find the closing delimiter for `$…$` math on the same line.+ *+ * The whitespace and numeric-edge rules mirror common dollar-math parsers:+ * whitespace cannot hug the delimiters, a digit cannot sit immediately before+ * the opener or after the closer, and `$$` is reserved for display math. The+ * numeric guard prevents ordinary prose such as "$20 and $30" from becoming a+ * formula even in a math-enabled document.+ */+function isInlineMathStart(text: string, index: number): boolean {+ return (+ text[index] === '$' &&+ text[index - 1] !== '$' &&+ text[index + 1] !== '$' &&+ text[index + 1] != null &&+ !/\s/.test(text[index + 1]) &&+ !/\d/.test(text[index - 1] ?? '') &&+ !isEscaped(text, index)+ );+}++function findInlineMathEnd(text: string, start: number): number {+ if (!isInlineMathStart(text, start)) {+ return -1;+ }++ for (let index = start + 1; index < text.length; index++) {+ if (text[index] === '\n') {+ return -1;+ }+ if (text[index] !== '$' || isEscaped(text, index)) {+ continue;+ }+ // An unescaped dollar ends this candidate: it either forms a valid closer+ // or makes the whole span literal. Never skip over one and pair with a+ // later dollar, which would swallow currency or another expression.+ if (+ text[index - 1] === '$' ||+ text[index + 1] === '$' ||+ /\s/.test(text[index - 1]) ||+ /\d/.test(text[index + 1] ?? '')+ ) {+ return -1;+ }+ return index;+ }+ return -1;+}+// ---------------------------------------------------------------------------// URL scheme sanitization// ---------------------------------------------------------------------------@@ -494,11 +782,15 @@ export function parseInline(text: string,sourceIds?: ReadonlySet<string>,): InlineNode[];+export function parseInline(+ text: string,+ options: MathParseOptions,+): InlineNodeWithMath[];export function parseInline(text: string, options: ParseOptions): InlineNode[];export function parseInline(text: string,- arg?: ReadonlySet<string> | ParseOptions,-): InlineNode[] {+ arg?: ReadonlySet<string> | RuntimeParseOptions,+): InlineNodeWithMath[] {return parseInlineEntry(text, resolveOptions(arg));}@@ -509,15 +801,21 @@ export function parseInline(* wrapper and call `parseInlineImpl` directly so the transform runs only on* the outermost block's inline tree — letting `transformAutolinks` decide* which subtrees to descend into (text, bold, italic, strikethrough) and- * which to skip (link, code, image, citation, break).+ * which to skip (link, code, math, image, citation, break).*/-function parseInlineEntry(text: string, opts: ResolvedOptions): InlineNode[] {+function parseInlineEntry(+ text: string,+ opts: ResolvedOptions,+): InlineNodeWithMath[] {const nodes = parseInlineImpl(text, opts);return opts.autolink === 'gfm' ? transformAutolinks(nodes) : nodes;}-function parseInlineImpl(text: string, opts: ResolvedOptions): InlineNode[] {- const nodes: InlineNode[] = [];+function parseInlineImpl(+ text: string,+ opts: ResolvedOptions,+): InlineNodeWithMath[] {+ const nodes: InlineNodeWithMath[] = [];let i = 0;while (i < text.length) {@@ -540,6 +838,16 @@ function parseInlineImpl(text: string, opts: ResolvedOptions): InlineNode[] {}}+ // --- Inline math (opt-in; code takes precedence) ---+ if (opts.math && text[i] === '$') {+ const closeIndex = findInlineMathEnd(text, i);+ if (closeIndex !== -1) {+ nodes.push({type: 'math', value: text.slice(i + 1, closeIndex)});+ i = closeIndex + 1;+ continue;+ }+ }+// --- Citation: fullwidth 【id】 ---{const citation = matchFullwidthCitation(text, i, opts);@@ -718,7 +1026,11 @@ function parseInlineImpl(text: string, opts: ResolvedOptions): InlineNode[] {// --- Plain text (with line-break detection) ---let end = i + 1;- while (end < text.length && !'*_~`[!\\\n\u3010'.includes(text[end])) {+ while (+ end < text.length &&+ !'*_~`[!\\\n\u3010'.includes(text[end]) &&+ !(opts.math && text[end] === '$')+ ) {end++;}@@ -991,12 +1303,12 @@ function scanAutolinksInText(text: string): AutolinkMatch[] {* Split a text-node `content` string into a sequence of text + link nodes* based on autolink matches.*/-function splitTextOnAutolinks(content: string): InlineNode[] {+function splitTextOnAutolinks(content: string): InlineNodeWithMath[] {const matches = scanAutolinksInText(content);if (matches.length === 0) {return [{type: 'text', content}];}- const out: InlineNode[] = [];+ const out: InlineNodeWithMath[] = [];let cursor = 0;for (const m of matches) {if (m.start > cursor) {@@ -1023,8 +1335,8 @@ function splitTextOnAutolinks(content: string): InlineNode[] {* `image` alt text, `citation`, or `break`. Runs only on the outermost* block's inline tree (see `parseInlineEntry`).*/-function transformAutolinks(nodes: InlineNode[]): InlineNode[] {- const out: InlineNode[] = [];+function transformAutolinks(nodes: InlineNodeWithMath[]): InlineNodeWithMath[] {+ const out: InlineNodeWithMath[] = [];for (const node of nodes) {if (node.type === 'text') {const split = splitTextOnAutolinks(node.content);@@ -1198,8 +1510,8 @@ function parseTable(lines: string[],lineIndex: number,opts: ResolvedOptions,-): {node: BlockNode; nextIndex: number} {- const headers: TableCellNode[] = splitTableRow(lines[lineIndex]).map(+): {node: BlockNodeWithMath; nextIndex: number} {+ const headers: TableCellNodeWithMath[] = splitTableRow(lines[lineIndex]).map(cell => ({children: parseInlineEntry(cell, opts)}),);const alignments: TableAlignment[] = splitTableRow(lines[lineIndex + 1]).map(@@ -1216,7 +1528,7 @@ function parseTable(: null;},);- const rows: TableCellNode[][] = [];+ const rows: TableCellNodeWithMath[][] = [];let rowIndex = lineIndex + 2;while (rowIndex < lines.length &&@@ -1241,8 +1553,8 @@ function parseList(startIndex: number,ordered: boolean,opts: ResolvedOptions,-): {node: BlockNode; nextIndex: number} {- const items: ListItemNode[] = [];+): {node: BlockNodeWithMath; nextIndex: number} {+ const items: ListItemNodeWithMath[] = [];const baseIndent = getIndent(lines[startIndex]);// Ordered lists may use either '.' or ')' as the marker delimiter// (CommonMark 5.2). Capture which one this list starts with so its items@@ -1335,21 +1647,25 @@ export function parseMarkdown(input: string,sourceIds?: ReadonlySet<string>,): BlockNode[];+export function parseMarkdown(+ input: string,+ options: MathParseOptions,+): BlockNodeWithMath[];export function parseMarkdown(input: string,options: ParseOptions,): BlockNode[];export function parseMarkdown(input: string,- arg?: ReadonlySet<string> | ParseOptions,-): BlockNode[] {+ arg?: ReadonlySet<string> | RuntimeParseOptions,+): BlockNodeWithMath[] {return parseMarkdownImpl(input, resolveOptions(arg));}function parseMarkdownImpl(input: string,baseOpts: ResolvedOptions,-): BlockNode[] {+): BlockNodeWithMath[] {// Collect this input's link reference definitions and strip their lines,// then merge them with any definitions inherited from an enclosing parse// (the incremental parser passes the whole document's definitions in; a@@ -1357,7 +1673,7 @@ function parseMarkdownImpl(// definitions win on conflict, matching CommonMark's first-definition-wins// in document order; locally-nested definitions still resolve within this// parse.- const {defs, cleaned, lineMap} = extractLinkDefinitions(input);+ const {defs, cleaned, lineMap} = extractLinkDefinitions(input, baseOpts.math);const inherited = baseOpts.linkDefs;let linkDefs: ReadonlyMap<string, string> | undefined;if (defs.size === 0) {@@ -1370,7 +1686,7 @@ function parseMarkdownImpl(const opts: ResolvedOptions =linkDefs != null ? {...baseOpts, linkDefs} : baseOpts;const lines = cleaned.split('\n');- const blocks: BlockNode[] = [];+ const blocks: BlockNodeWithMath[] = [];// The line each block started on, parallel to `blocks`. Only collected when// ranges were asked for; a block's end is resolved after the loop, since the// branch that produced it has already moved `index` past whatever it read.@@ -1381,7 +1697,7 @@ function parseMarkdownImpl(? []: null;let blockStartLine = 0;- const pushBlock = (node: BlockNode, endLine?: number) => {+ const pushBlock = (node: BlockNodeWithMath, endLine?: number) => {blocks.push(node);blockStartLines?.push(blockStartLine);blockEndLines?.push(endLine);@@ -1418,6 +1734,19 @@ function parseMarkdownImpl(continue;}+ // --- Display math (opt-in; fenced code takes precedence) ---+ if (opts.math) {+ const displayMath = matchDisplayMathBlock(lines, index);+ if (displayMath != null) {+ pushBlock(+ {type: 'math', value: displayMath.value},+ displayMath.endLine,+ );+ index = displayMath.nextIndex;+ continue;+ }+ }+// --- Heading ---const headingMatch = line.match(/^(#{1,6}) +(.*)/);if (headingMatch) {@@ -1502,6 +1831,7 @@ function parseMarkdownImpl(while (index < lines.length &&!isBlockStart(lines[index]) &&+ !(opts.math && matchDisplayMathBlock(lines, index) != null) &&lines[index].trim() !== '') {paraLines.push(lines[index]);@@ -1536,7 +1866,7 @@ function parseMarkdownImpl(* `lineMap` says which input line each surviving line came from.*/function stampSourceRanges(- blocks: BlockNode[],+ blocks: BlockNodeWithMath[],blockStartLines: number[],blockEndLines: (number | undefined)[],lines: string[],@@ -1581,10 +1911,17 @@ function stampSourceRanges(// Incremental parsing// ----------------------------------------------------------------------------export interface IncrementalState {+type IncrementalBlockNode<MathEnabled extends boolean> =+ MathEnabled extends true ? BlockNodeWithMath : BlockNode;++declare const incrementalStateMode: unique symbol;++export interface IncrementalState<MathEnabled extends boolean = false> {+ /** @internal Nominally couples a factory-created cache to its node union. */+ readonly [incrementalStateMode]: MathEnabled;prevInput: string;settledText: string;- settledBlocks: BlockNode[];+ settledBlocks: IncrementalBlockNode<MathEnabled>[];settledUpTo: number;/*** The `autolink` option the cached `settledBlocks` were parsed with.@@ -1593,6 +1930,8 @@ export interface IncrementalState {* with newly-arriving content.*/autolink?: 'gfm';+ /** Whether the cached settled blocks were parsed with math enabled. */+ math?: MathEnabled;/*** The `sourceRanges` option the cached `settledBlocks` were parsed with.* Flipping it invalidates them the same way `autolink` does: they either@@ -1632,10 +1971,15 @@ type IncrementalCache = {work: IncrementalWork;};-const incrementalCaches = new WeakMap<IncrementalState, IncrementalCache>();+const incrementalCaches = new WeakMap<+ IncrementalState<boolean>,+ IncrementalCache+>();-function makeIncrementalCache(state: IncrementalState): IncrementalCache {- const {defs} = extractLinkDefinitions(state.settledText);+function makeIncrementalCache(+ state: IncrementalState<boolean>,+): IncrementalCache {+ const {defs} = extractLinkDefinitions(state.settledText, state.math);const cache: IncrementalCache = {settledEnd: state.settledText.length,settledLinkDefs: new Map(defs),@@ -1653,13 +1997,19 @@ function makeIncrementalCache(state: IncrementalState): IncrementalCache {return cache;}-export function createIncrementalState(): IncrementalState {- const state: IncrementalState = {+/**+ * Create an incremental parser cache. Use the `<true>` type argument with+ * `MathParseOptions` so the cache and returned nodes share the math contract.+ */+export function createIncrementalState<+ MathEnabled extends boolean = false,+>(): IncrementalState<MathEnabled> {+ const state = {prevInput: '',settledText: '',settledBlocks: [],settledUpTo: 0,- };+ } as unknown as IncrementalState<MathEnabled>;makeIncrementalCache(state);return state;}@@ -1669,7 +2019,7 @@ export function createIncrementalState(): IncrementalState {* @internal Exported from this module for performance regression tests only.*/export function getIncrementalParseWork(- state: IncrementalState,+ state: IncrementalState<boolean>,): IncrementalWork {return (incrementalCaches.get(state)?.work ?? {@@ -1695,47 +2045,91 @@ export function getIncrementalParseWork(* the boundary to -1 even though the content before the fence opened cannot be* changed by anything typed inside it.*/-function findSettledBoundary(lines: string[]): {+function findSettledBoundary(+ lines: string[],+ math = false,+): {boundary: number;openFence: boolean;+ openMath: boolean;} {let inFence = false;let fenceMarker = '';+ let mathContainer: DisplayMathContainer | null = null;+ let suppressMathUntilBoundary = false;let lastBoundary = -1;let boundaryBeforeFence = -1;+ let boundaryBeforeMath = -1;for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {const line = lines[lineIndex];- // Fence open / close — match the specific marker character and length- const fenceMatch = line.match(/^(`{3,}|~{3,})/);- if (fenceMatch) {- if (!inFence) {- inFence = true;- fenceMarker = fenceMatch[1];- boundaryBeforeFence = lastBoundary;- } else if (+ if (inFence) {+ const fenceMatch = line.match(/^(`{3,}|~{3,})/);+ if (+ fenceMatch &&fenceMatch[1].startsWith(fenceMarker[0]) &&fenceMatch[1].length >= fenceMarker.length) {inFence = false;fenceMarker = '';}+ continue;}- if (- !inFence &&- line.trim() === '' &&- lineIndex > 0 &&- lineIndex < lines.length - 1- ) {- lastBoundary = lineIndex;+ if (mathContainer != null) {+ const state = displayMathLineState(line, mathContainer);+ if (state === 'close') {+ mathContainer = null;+ continue;+ }+ if (state === 'inside') {+ continue;+ }+ // The list item or blockquote ended before a closer arrived. The parser+ // treats that unmatched opener literally, so resume ordinary boundary+ // detection on this first line outside the container.+ mathContainer = null;+ suppressMathUntilBoundary = true;+ }++ // A complete same-line `$$…$$` expression never changes boundary state.+ // A standalone marker may belong to the top level, a blockquote, or one+ // list item; remember that container so its continuation marker closes the+ // same expression instead of opening a new one.+ if (math && !suppressMathUntilBoundary) {+ const container = displayMathContainer(line);+ if (container != null) {+ mathContainer = container;+ boundaryBeforeMath = lastBoundary;+ continue;+ }+ }++ const fenceMatch = line.match(/^(`{3,}|~{3,})/);+ if (fenceMatch) {+ inFence = true;+ fenceMarker = fenceMatch[1];+ boundaryBeforeFence = lastBoundary;+ continue;+ }++ if (line.trim() === '') {+ suppressMathUntilBoundary = false;+ if (lineIndex > 0 && lineIndex < lines.length - 1) {+ lastBoundary = lineIndex;+ }}}return {- boundary: inFence ? boundaryBeforeFence : lastBoundary,+ boundary: inFence+ ? boundaryBeforeFence+ : mathContainer != null+ ? boundaryBeforeMath+ : lastBoundary,openFence: inFence,+ openMath: mathContainer != null,};}@@ -1743,10 +2137,55 @@ function findSettledBoundary(lines: string[]): {* Strip trailing incomplete inline syntax that appears during streaming.* Only affects the tail of the last line — safe to apply to the full string.*/-export function trimStreamingArtifacts(input: string): string {- const lastNL = input.lastIndexOf('\n');- const prefix = lastNL === -1 ? '' : input.slice(0, lastNL + 1);- let tail = lastNL === -1 ? input : input.slice(lastNL + 1);+export function trimStreamingArtifacts(+ input: string,+ options?: {math?: boolean},+): string {+ // First remove an incomplete display expression as one structural unit. This+ // full-input scan distinguishes a terminal nested closer from a new opener;+ // looking only at the final `$$` line cannot.+ const displayTrimmed = options?.math ? trimOpenDisplayMath(input) : input;+ const lastNL = displayTrimmed.lastIndexOf('\n');+ const prefix = lastNL === -1 ? '' : displayTrimmed.slice(0, lastNL + 1);+ let tail = lastNL === -1 ? displayTrimmed : displayTrimmed.slice(lastNL + 1);++ if (options?.math) {+ // Hold an unmatched inline opener so raw TeX syntax does not flash while+ // streaming. If another unescaped dollar is already present but fails the+ // closing-boundary rule, keep both literal (the currency case).+ for (let index = 0; index < tail.length; index++) {+ if (+ tail[index] === '$' &&+ tail[index + 1] == null &&+ tail[index - 1] !== '$' &&+ !/\d/.test(tail[index - 1] ?? '') &&+ !isEscaped(tail, index)+ ) {+ tail = tail.slice(0, index);+ break;+ }+ if (!isInlineMathStart(tail, index)) {+ continue;+ }+ const close = findInlineMathEnd(tail, index);+ if (close !== -1) {+ index = close;+ continue;+ }+ let laterDollar = -1;+ for (let next = index + 1; next < tail.length; next++) {+ if (tail[next] === '$' && !isEscaped(tail, next)) {+ laterDollar = next;+ break;+ }+ }+ if (laterDollar === -1) {+ tail = tail.slice(0, index);+ break;+ }+ index = laterDollar;+ }+ }// Scan backwards for unclosed syntax markers — no regex to avoid ReDoS// Find the last unclosed [ or ![ (link/image start)@@ -1904,6 +2343,67 @@ export function trimStreamingArtifacts(input: string): string {* Once a table is established (header + separator exist), new data rows* render immediately — no suppression.*/+function trimOpenDisplayMath(text: string): string {+ const lines = text.split('\n');+ let inFence = false;+ let fenceMarker = '';+ let mathContainer: DisplayMathContainer | null = null;+ let suppressMathUntilBoundary = false;+ let mathStartLine = -1;++ for (let index = 0; index < lines.length; index++) {+ const line = lines[index];+ if (inFence) {+ const fence = line.match(/^(`{3,}|~{3,})/);+ if (+ fence != null &&+ fence[1].startsWith(fenceMarker[0]) &&+ fence[1].length >= fenceMarker.length+ ) {+ inFence = false;+ fenceMarker = '';+ }+ continue;+ }+ if (mathContainer != null) {+ const state = displayMathLineState(line, mathContainer);+ if (state === 'close') {+ mathContainer = null;+ mathStartLine = -1;+ continue;+ }+ if (state === 'inside') {+ continue;+ }+ mathContainer = null;+ mathStartLine = -1;+ suppressMathUntilBoundary = true;+ }++ if (line.trim() === '') {+ suppressMathUntilBoundary = false;+ }++ const fence = line.match(/^(`{3,}|~{3,})/);+ if (fence != null) {+ inFence = true;+ fenceMarker = fence[1];+ continue;+ }+ const container = suppressMathUntilBoundary+ ? null+ : displayMathContainer(line);+ if (container != null) {+ mathContainer = container;+ mathStartLine = index;+ }+ }++ return mathContainer != null && mathStartLine >= 0+ ? lines.slice(0, mathStartLine).join('\n').trimEnd()+ : text;+}+function trimUnsettledStructural(text: string): string {const lines = text.split('\n');@@ -1981,9 +2481,9 @@ function atOffset(opts: ResolvedOptions, offset: number): ResolvedOptions {* lists even though the full-text parser joins them per CommonMark §5.3.*/function mergeSettledBlocks(- prev: BlockNode[],- delta: BlockNode[],-): BlockNode[] {+ prev: BlockNodeWithMath[],+ delta: BlockNodeWithMath[],+): BlockNodeWithMath[] {if (prev.length === 0 || delta.length === 0) {return [...prev, ...delta];}@@ -1995,7 +2495,7 @@ function mergeSettledBlocks(prevLast.ordered === deltaFirst.ordered &&prevLast.delimiter === deltaFirst.delimiter) {- const merged: BlockNode = {+ const merged: BlockNodeWithMath = {type: 'list',ordered: prevLast.ordered,start: prevLast.start,@@ -2014,7 +2514,10 @@ function mergeSettledBlocks(}/** Append a newly-settled slice without copying the already-settled prefix. */-function appendSettledBlocks(prev: BlockNode[], delta: BlockNode[]): void {+function appendSettledBlocks(+ prev: BlockNodeWithMath[],+ delta: BlockNodeWithMath[],+): void {if (delta.length === 0) {return;}@@ -2066,7 +2569,7 @@ function sameUnsettledDefinitions(}function resetIncrementalCache(- state: IncrementalState,+ state: IncrementalState<boolean>,cache: IncrementalCache,): void {state.prevInput = '';@@ -2074,6 +2577,7 @@ function resetIncrementalCache(state.settledBlocks = [];state.settledUpTo = 0;state.linkDefsKey = undefined;+ state.math = undefined;cache.settledEnd = 0;cache.settledLinkDefs.clear();cache.tailLinkDefs = new Map();@@ -2100,32 +2604,39 @@ function resetIncrementalCache(*/export function parseMarkdownIncremental(input: string,- state: IncrementalState,+ state: IncrementalState<false>,sourceIds?: ReadonlySet<string>,): BlockNode[];export function parseMarkdownIncremental(input: string,- state: IncrementalState,+ state: IncrementalState<true>,+ options: MathParseOptions,+): BlockNodeWithMath[];+export function parseMarkdownIncremental(+ input: string,+ state: IncrementalState<false>,options: ParseOptions,): BlockNode[];export function parseMarkdownIncremental(input: string,- state: IncrementalState,- arg?: ReadonlySet<string> | ParseOptions,-): BlockNode[] {+ state: IncrementalState<boolean>,+ arg?: ReadonlySet<string> | RuntimeParseOptions,+): BlockNodeWithMath[] {const opts = resolveOptions(arg);const cache = incrementalCaches.get(state) ?? makeIncrementalCache(state);let reparseSettled = false;- // Invalidate cache when the autolink or sourceRanges option flips — cached+ // Invalidate cache when an option that changes parsed nodes flips — cached// settled blocks were parsed with the previous setting and would otherwise// be reused unchanged.if (state.autolink !== opts.autolink ||+ state.math !== opts.math ||Boolean(state.sourceRanges) !== Boolean(opts.sourceRanges)) {reparseSettled = true;state.autolink = opts.autolink;+ state.math = opts.math;state.sourceRanges = opts.sourceRanges;}if (input === '') {@@ -2147,6 +2658,7 @@ export function parseMarkdownIncremental() {resetIncrementalCache(state, cache);state.autolink = opts.autolink;+ state.math = opts.math;state.sourceRanges = opts.sourceRanges;}@@ -2156,7 +2668,10 @@ export function parseMarkdownIncremental(const oldSettledEnd = cache.settledEnd;const tailRaw = input.slice(oldSettledEnd);const tailLines = tailRaw.split('\n');- const {boundary, openFence} = findSettledBoundary(tailLines);+ const {boundary, openFence, openMath} = findSettledBoundary(+ tailLines,+ opts.math,+ );const settledDelta =boundary >= 0 ? tailLines.slice(0, boundary).join('\n') : '';const nextSettledEnd = oldSettledEnd + settledDelta.length;@@ -2168,7 +2683,7 @@ export function parseMarkdownIncremental(// blocks: document-global references may precede their footer definition.let definitionsChanged = false;if (settledDelta !== '') {- const {defs: deltaDefs} = extractLinkDefinitions(settledDelta);+ const {defs: deltaDefs} = extractLinkDefinitions(settledDelta, opts.math);for (const [label, destination] of deltaDefs) {if (!cache.settledLinkDefs.has(label)) {cache.settledLinkDefs.set(label, destination);@@ -2178,7 +2693,10 @@ export function parseMarkdownIncremental(}}}- const {defs: tailLinkDefs} = extractLinkDefinitions(unsettledInput);+ const {defs: tailLinkDefs} = extractLinkDefinitions(+ unsettledInput,+ opts.math,+ );if (!sameUnsettledDefinitions(cache.tailLinkDefs,@@ -2209,13 +2727,22 @@ export function parseMarkdownIncremental(cache.settledEnd = nextSettledEnd;}- const unsettledRaw = unsettledInput.trim();+ const trimmedUnsettledInput = unsettledInput.trim();+ // String#trim removes the CR that belongs to the final content line of a+ // CRLF snapshot along with trailing blank lines. Keep that one byte so+ // source ranges and delimiter content remain identical to a full parse.+ const unsettledRaw =+ trimmedUnsettledInput !== '' && /\r(?:\n[\s]*)?$/.test(unsettledInput)+ ? `${trimmedUnsettledInput}\r`+ : trimmedUnsettledInput;// Structural trimming holds back lines that look like an incomplete list or// table, which inside a fence is ordinary code: a TypeScript union or a `- `// would disappear from the code block as it streams.const unsettledText = openFence? unsettledRaw- : trimUnsettledStructural(unsettledRaw);+ : openMath+ ? trimOpenDisplayMath(unsettledRaw)+ : trimUnsettledStructural(unsettledRaw);let parsedSettledBlocks = 0;if (reparseSettled) {@@ -2275,13 +2802,14 @@ export function parseMarkdownIncremental(// resolve to a rendered heading by construction./** Flatten inline nodes into their plain text content. */-export function inlineText(nodes: InlineNode[]): string {+export function inlineText(nodes: ReadonlyArray<InlineNodeWithMath>): string {return nodes.map(node => {switch (node.type) {case 'text':case 'code':- return node.content;+ case 'math':+ return node.type === 'math' ? node.value : node.content;case 'bold':case 'italic':case 'strikethrough':diff --git a/packages/core/src/Markdown/utils.ts b/packages/core/src/Markdown/utils.tsindex ba39831acf..aa48a9eb1c 100644--- a/packages/core/src/Markdown/utils.ts+++ b/packages/core/src/Markdown/utils.ts@@ -16,9 +16,15 @@ export {export type {InlineNode,+ InlineNodeWithMath,+ MathInlineNode,BlockNode,+ BlockNodeWithMath,+ MathBlockNode,ListItemNode,TableCellNode,TableAlignment,+ ParseOptions,+ MathParseOptions,IncrementalState,} from './parser';