Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat: XDSMarkdown — zero-dep markdown renderer with incremental parser (#1125)

Cindy Zhangd50e9e4a91e2
diff --git a/apps/storybook/stories/Markdown.stories.tsx b/apps/storybook/stories/Markdown.stories.tsx
new file mode 100644
index 0000000000..f35e177dfa
--- /dev/null
+++ b/apps/storybook/stories/Markdown.stories.tsx
@@ -0,0 +1,190 @@
+import {useState, useEffect, useCallback} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSMarkdown} from '@xds/core/Markdown';
+import {XDSButton} from '@xds/core/Button';
+
+const meta: Meta<typeof XDSMarkdown> = {
+ title: 'Components/XDSMarkdown',
+ component: XDSMarkdown,
+ tags: ['autodocs'],
+ argTypes: {
+ density: {
+ control: 'select',
+ options: ['default', 'compact'],
+ },
+ headingLevelStart: {
+ control: 'select',
+ options: [1, 2, 3, 4, 5, 6],
+ },
+ isStreaming: {control: 'boolean'},
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSMarkdown>;
+
+const SAMPLE_MD = [
+ '# XDSMarkdown Demo',
+ '',
+ 'Renders **markdown** with *design-system-consistent* styling.',
+ '',
+ '## Features',
+ '',
+ '- Headings mapped to XDS type scale',
+ '- **Bold**, *italic*, and ~~strikethrough~~ text',
+ '- [Links](https://example.com) with external detection',
+ '- Inline `code` and fenced code blocks',
+ '',
+ '### Code Block',
+ '',
+ '```typescript',
+ 'interface User {',
+ ' id: string;',
+ ' name: string;',
+ '}',
+ '',
+ 'function greet(user: User) {',
+ ' return `Hello, ${user.name}!`;',
+ '}',
+ '```',
+ '',
+ '### Blockquote',
+ '',
+ '> Design systems free teams to focus on problems that matter.',
+ '',
+ '### Table',
+ '',
+ '| Component | Status | Tests |',
+ '|:----------|:------:|------:|',
+ '| XDSMarkdown | Active | 73 |',
+ '| XDSCodeBlock | Active | 44 |',
+ '',
+ '### Task List',
+ '',
+ '- [x] Parser',
+ '- [x] Renderer',
+ '- [ ] Storybook stories',
+ '',
+ '---',
+ '',
+ '1. First ordered item',
+ '2. Second ordered item',
+].join('\n');
+
+const AI_RESPONSE = [
+ 'Here is how you fetch a user in TypeScript:',
+ '',
+ '```typescript',
+ 'const response = await fetch(`/api/users/${id}`);',
+ 'const user: User = await response.json();',
+ '```',
+ '',
+ 'Key points:',
+ '',
+ '- Always check `response.ok` before parsing',
+ '- Use `AbortController` for cancellation',
+ '- Consider a `useUser` hook for React apps',
+ '',
+ '| Method | Status | Use Case |',
+ '|--------|--------|----------|',
+ '| GET | 200 | Fetch resource |',
+ '| POST | 201 | Create resource |',
+ '| PUT | 200 | Update resource |',
+ '',
+ '> **Tip**: Wrap fetch calls in a try/catch for error handling.',
+].join('\n');
+
+export const Default: Story = {
+ args: {
+ children: SAMPLE_MD,
+ },
+};
+
+export const Compact: Story = {
+ args: {
+ children: SAMPLE_MD,
+ density: 'compact',
+ },
+};
+
+export const AIResponse: Story = {
+ name: 'AI Response',
+ args: {
+ children: AI_RESPONSE,
+ density: 'compact',
+ headingLevelStart: 3,
+ },
+};
+
+export const ShiftedHeadings: Story = {
+ name: 'Shifted Headings (start at h3)',
+ args: {
+ children: SAMPLE_MD,
+ headingLevelStart: 3,
+ },
+};
+
+export const TableFocused: Story = {
+ name: 'Table',
+ args: {
+ children: [
+ '## Comparison Table',
+ '',
+ '| Feature | React | Vue | Svelte |',
+ '|:--------|:-----:|:---:|-------:|',
+ '| Virtual DOM | Yes | Yes | No |',
+ '| Bundle Size | ~40KB | ~30KB | ~2KB |',
+ '| TypeScript | Native | Plugin | Native |',
+ '| Learning Curve | Medium | Easy | Easy |',
+ ].join('\n'),
+ },
+};
+
+export const Streaming: Story = {
+ render: () => {
+ const text = AI_RESPONSE;
+ const [charIndex, setCharIndex] = useState(0);
+ const [isStreaming, setIsStreaming] = useState(true);
+ const [key, setKey] = useState(0);
+
+ useEffect(() => {
+ if (!isStreaming) return;
+ if (charIndex >= text.length) {
+ setIsStreaming(false);
+ return;
+ }
+ const chunkSize = Math.floor(Math.random() * 8) + 2;
+ const delay = 30 + Math.random() * 60;
+ const timer = setTimeout(() => {
+ setCharIndex(prev => Math.min(prev + chunkSize, text.length));
+ }, delay);
+ return () => clearTimeout(timer);
+ }, [charIndex, isStreaming, text]);
+
+ const replay = useCallback(() => {
+ setCharIndex(0);
+ setIsStreaming(true);
+ setKey(k => k + 1);
+ }, []);
+
+ return (
+ <div>
+ <div style={{marginBlockEnd: 12, display: 'flex', gap: 8, alignItems: 'center'}}>
+ <XDSButton
+ label="Replay"
+ variant="secondary"
+ size="sm"
+ onClick={replay}
+ isDisabled={isStreaming}
+ />
+ <span style={{fontSize: 12, color: '#666'}}>
+ {isStreaming ? `Streaming... ${charIndex}/${text.length}` : 'Complete'}
+ </span>
+ </div>
+ <XDSMarkdown key={key} isStreaming={isStreaming} density="compact" headingLevelStart={3}>
+ {text.slice(0, charIndex)}
+ </XDSMarkdown>
+ </div>
+ );
+ },
+};
diff --git a/internal/test-utils/src/setup.ts b/internal/test-utils/src/setup.ts
index 18af52f747..94e604b960 100644
--- a/internal/test-utils/src/setup.ts
+++ b/internal/test-utils/src/setup.ts
@@ -10,6 +10,21 @@
/// <reference types="@testing-library/jest-dom" />
import '@testing-library/jest-dom/vitest';
+// Polyfill for matchMedia (not supported in jsdom)
+if (typeof window !== 'undefined' && !window.matchMedia) {
+ window.matchMedia = (query: string) =>
+ ({
+ matches: false,
+ media: query,
+ onchange: null,
+ addListener: () => {},
+ removeListener: () => {},
+ addEventListener: () => {},
+ removeEventListener: () => {},
+ dispatchEvent: () => false,
+ }) as MediaQueryList;
+}
+
// Polyfill for Popover API (not supported in jsdom)
// This prevents errors when testing components that use XDSTooltip
if (typeof HTMLElement.prototype.showPopover === 'undefined') {
diff --git a/packages/core/package.json b/packages/core/package.json
index 018897e28c..e4748ff04d 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -208,6 +208,12 @@
"import": "./dist/List/index.mjs",
"require": "./dist/List/index.js"
},
+ "./Markdown": {
+ "source": "./src/Markdown/index.ts",
+ "types": "./dist/Markdown/index.d.ts",
+ "import": "./dist/Markdown/index.mjs",
+ "require": "./dist/Markdown/index.js"
+ },
"./MetadataList": {
"source": "./src/MetadataList/index.ts",
"types": "./dist/MetadataList/index.d.ts",
diff --git a/packages/core/src/Markdown/XDSMarkdown.test.tsx b/packages/core/src/Markdown/XDSMarkdown.test.tsx
new file mode 100644
index 0000000000..6263b302f8
--- /dev/null
+++ b/packages/core/src/Markdown/XDSMarkdown.test.tsx
@@ -0,0 +1,202 @@
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {XDSMarkdown} from './XDSMarkdown';
+
+describe('XDSMarkdown', () => {
+ it('renders with role="document"', () => {
+ render(<XDSMarkdown>Hello</XDSMarkdown>);
+ expect(screen.getByRole('document')).toBeInTheDocument();
+ });
+
+ it('renders xds-markdown class name', () => {
+ const {container} = render(<XDSMarkdown>Hello</XDSMarkdown>);
+ expect(container.firstElementChild!.className).toContain('xds-markdown');
+ });
+
+ it('renders headings', () => {
+ render(<XDSMarkdown>{'# Heading 1\n\n## Heading 2'}</XDSMarkdown>);
+ expect(screen.getByText('Heading 1').tagName).toBe('H1');
+ expect(screen.getByText('Heading 2').tagName).toBe('H2');
+ });
+
+ it('renders paragraphs', () => {
+ render(<XDSMarkdown>{'Hello world'}</XDSMarkdown>);
+ expect(screen.getByText('Hello world').tagName).toBe('P');
+ });
+
+ it('renders bold text', () => {
+ render(<XDSMarkdown>{'**bold text**'}</XDSMarkdown>);
+ expect(screen.getByText('bold text').tagName).toBe('STRONG');
+ });
+
+ it('renders italic text', () => {
+ render(<XDSMarkdown>{'*italic text*'}</XDSMarkdown>);
+ expect(screen.getByText('italic text').tagName).toBe('EM');
+ });
+
+ it('renders strikethrough text', () => {
+ render(<XDSMarkdown>{'~~struck~~'}</XDSMarkdown>);
+ expect(screen.getByText('struck').tagName).toBe('DEL');
+ });
+
+ it('renders inline code with XDSCode', () => {
+ render(<XDSMarkdown>{'Use `code` here'}</XDSMarkdown>);
+ expect(screen.getByText('code').tagName).toBe('CODE');
+ });
+
+ it('renders code blocks with XDSCodeBlock', () => {
+ render(<XDSMarkdown>{'```js\nconst x = 1;\n```'}</XDSMarkdown>);
+ // XDSCodeBlock renders in a <pre>
+ const pre = document.querySelector('pre');
+ expect(pre).toBeInTheDocument();
+ });
+
+ it('renders links with correct href', () => {
+ render(<XDSMarkdown>{'[click](https://example.com)'}</XDSMarkdown>);
+ const link = screen.getByText('click');
+ expect(link.tagName).toBe('A');
+ expect(link.getAttribute('href')).toBe('https://example.com');
+ });
+
+ it('adds target="_blank" to external links', () => {
+ render(<XDSMarkdown>{'[ext](https://example.com)'}</XDSMarkdown>);
+ const link = screen.getByText('ext');
+ expect(link.getAttribute('target')).toBe('_blank');
+ expect(link.getAttribute('rel')).toBe('noopener noreferrer');
+ });
+
+ it('does not add target="_blank" to relative links', () => {
+ render(<XDSMarkdown>{'[internal](/page)'}</XDSMarkdown>);
+ const link = screen.getByText('internal');
+ expect(link.getAttribute('target')).toBeNull();
+ });
+
+ it('calls onLinkClick when link is clicked', () => {
+ const handleClick = vi.fn();
+ render(
+ <XDSMarkdown onLinkClick={handleClick}>
+ {'[click me](https://example.com)'}
+ </XDSMarkdown>,
+ );
+ fireEvent.click(screen.getByText('click me'));
+ expect(handleClick).toHaveBeenCalledWith(
+ 'https://example.com',
+ expect.any(Object),
+ );
+ });
+
+ it('renders blockquotes', () => {
+ render(<XDSMarkdown>{'> A quote'}</XDSMarkdown>);
+ const bq = document.querySelector('blockquote');
+ expect(bq).toBeInTheDocument();
+ });
+
+ it('renders unordered lists', () => {
+ render(<XDSMarkdown>{'- A\n- B\n- C'}</XDSMarkdown>);
+ const ul = document.querySelector('ul');
+ expect(ul).toBeInTheDocument();
+ expect(document.querySelectorAll('li')).toHaveLength(3);
+ });
+
+ it('renders ordered lists', () => {
+ render(<XDSMarkdown>{'1. A\n2. B'}</XDSMarkdown>);
+ const ol = document.querySelector('ol');
+ expect(ol).toBeInTheDocument();
+ });
+
+ it('renders task lists with checkboxes', () => {
+ render(<XDSMarkdown>{'- [x] Done\n- [ ] Todo'}</XDSMarkdown>);
+ const checkboxes = document.querySelectorAll('input[type="checkbox"]');
+ expect(checkboxes).toHaveLength(2);
+ expect((checkboxes[0] as HTMLInputElement).checked).toBe(true);
+ expect((checkboxes[1] as HTMLInputElement).checked).toBe(false);
+ });
+
+ it('renders tables', () => {
+ render(
+ <XDSMarkdown>{'| A | B |\n| --- | --- |\n| 1 | 2 |'}</XDSMarkdown>,
+ );
+ expect(document.querySelector('table')).toBeInTheDocument();
+ expect(document.querySelectorAll('th')).toHaveLength(2);
+ expect(document.querySelectorAll('td')).toHaveLength(2);
+ });
+
+ it('renders horizontal rules', () => {
+ render(<XDSMarkdown>{'---'}</XDSMarkdown>);
+ expect(document.querySelector('hr')).toBeInTheDocument();
+ });
+
+ it('renders images', () => {
+ render(<XDSMarkdown>{'![alt text](image.png)'}</XDSMarkdown>);
+ const img = document.querySelector('img');
+ expect(img).toBeInTheDocument();
+ expect(img!.getAttribute('alt')).toBe('alt text');
+ expect(img!.getAttribute('src')).toBe('image.png');
+ });
+
+ it('shifts heading levels with headingLevelStart', () => {
+ render(
+ <XDSMarkdown headingLevelStart={3}>{'# Heading 1'}</XDSMarkdown>,
+ );
+ expect(screen.getByText('Heading 1').tagName).toBe('H3');
+ });
+
+ it('shows streaming cursor when isStreaming is true', () => {
+ const {container} = render(
+ <XDSMarkdown isStreaming>{'Hello'}</XDSMarkdown>,
+ );
+ // Streaming mode parses incrementally but no cursor element
+ expect(container.querySelector('[role="document"]')).toBeInTheDocument();
+ });
+
+ it('hides cursor when not streaming', () => {
+ const {container} = render(<XDSMarkdown>{'Hello'}</XDSMarkdown>);
+ const cursor = container.querySelector('span[aria-hidden]');
+ expect(cursor).not.toBeInTheDocument();
+ });
+
+ it('applies compact density', () => {
+ const {container} = render(
+ <XDSMarkdown density="compact">{'Hello'}</XDSMarkdown>,
+ );
+ expect(container.firstElementChild!.className).toContain('compact');
+ });
+
+ it('supports data-testid', () => {
+ render(<XDSMarkdown data-testid="md">{'Hello'}</XDSMarkdown>);
+ expect(screen.getByTestId('md')).toBeInTheDocument();
+ });
+
+ it('forwards ref', () => {
+ const ref = {current: null as HTMLDivElement | null};
+ render(<XDSMarkdown ref={ref}>{'Hello'}</XDSMarkdown>);
+ expect(ref.current).toBeInstanceOf(HTMLDivElement);
+ });
+
+ it('sanitizes javascript: URLs in links', () => {
+ const {container} = render(
+ <XDSMarkdown>{'[click](javascript:alert(1))'}</XDSMarkdown>,
+ );
+ const link = container.querySelector('a');
+ expect(link).toBeNull();
+ expect(container.textContent).toContain('click');
+ });
+
+ it('sanitizes data: URLs in images', () => {
+ const {container} = render(
+ <XDSMarkdown>{'![xss](data:text/html,<script>alert(1)</script>)'}</XDSMarkdown>,
+ );
+ const img = container.querySelector('img');
+ expect(img).toBeNull();
+ });
+
+ it('allows safe URLs', () => {
+ const {container} = render(
+ <XDSMarkdown>{'[safe](https://example.com) and [relative](/page)'}</XDSMarkdown>,
+ );
+ const links = container.querySelectorAll('a');
+ expect(links).toHaveLength(2);
+ expect(links[0].getAttribute('href')).toBe('https://example.com');
+ expect(links[1].getAttribute('href')).toBe('/page');
+ });
+});
diff --git a/packages/core/src/Markdown/XDSMarkdown.tsx b/packages/core/src/Markdown/XDSMarkdown.tsx
new file mode 100644
index 0000000000..86f8a1fb1b
--- /dev/null
+++ b/packages/core/src/Markdown/XDSMarkdown.tsx
@@ -0,0 +1,665 @@
+'use client';
+
+/**
+ * @file XDSMarkdown.tsx
+ * @input Markdown string, parser AST types
+ * @output Exports XDSMarkdown component and XDSMarkdownProps
+ * @position Core implementation; renders markdown as XDS components
+ */
+
+import {useMemo, useRef} from 'react';
+import type React from 'react';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import * as stylex from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ radiusVars,
+ typeScaleVars,
+ typographyVars,
+ fontWeightVars,
+ borderVars,
+} from '../theme/tokens.stylex';
+import {XDSCodeBlock, XDSCode} from '../CodeBlock';
+import {XDSCheckboxList} from '../CheckboxList/XDSCheckboxList';
+import {XDSCheckboxListItem} from '../CheckboxList/XDSCheckboxListItem';
+import {xdsClassName, mergeProps} from '../utils';
+import {
+ parseMarkdown,
+ parseMarkdownIncremental,
+ createIncrementalState,
+ trimStreamingArtifacts,
+} from './parser';
+import type {
+ BlockNode,
+ InlineNode,
+ IncrementalState,
+} from './parser';
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+export interface XDSMarkdownProps {
+ ref?: React.Ref<HTMLDivElement>;
+ children: string;
+ density?: 'default' | 'compact';
+ /**
+ * The HTML heading level that markdown `#` maps to.
+ * Shifts all heading levels down to fit the surrounding page hierarchy.
+ * E.g. headingLevelStart={3} renders `#` as h3, `##` as h4, `###` as h5.
+ * Levels that would exceed h6 are clamped to h6.
+ * @default 1
+ */
+ headingLevelStart?: 1 | 2 | 3 | 4 | 5 | 6;
+ isStreaming?: boolean;
+ onLinkClick?: (href: string, event: React.MouseEvent<HTMLAnchorElement>) => void | false;
+ xstyle?: StyleXStyles;
+ className?: string;
+ style?: React.CSSProperties;
+ 'data-testid'?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+const styles = stylex.create({
+ root: {
+ fontFamily: typographyVars['--font-family-body'],
+ color: colorVars['--color-text-primary'],
+ lineHeight: typeScaleVars['--text-body-leading'],
+ fontSize: typeScaleVars['--text-body-size'],
+ },
+ // Headings
+ headingBase: {
+ fontFamily: typographyVars['--font-family-heading'],
+ color: colorVars['--color-text-primary'],
+ },
+ h1: {
+ fontSize: typeScaleVars['--text-heading-1-size'],
+ fontWeight: typeScaleVars['--text-heading-1-weight'],
+ lineHeight: typeScaleVars['--text-heading-1-leading'],
+ },
+ h2: {
+ fontSize: typeScaleVars['--text-heading-2-size'],
+ fontWeight: typeScaleVars['--text-heading-2-weight'],
+ lineHeight: typeScaleVars['--text-heading-2-leading'],
+ },
+ h3: {
+ fontSize: typeScaleVars['--text-heading-3-size'],
+ fontWeight: typeScaleVars['--text-heading-3-weight'],
+ lineHeight: typeScaleVars['--text-heading-3-leading'],
+ },
+ h4: {
+ fontSize: typeScaleVars['--text-heading-4-size'],
+ fontWeight: typeScaleVars['--text-heading-4-weight'],
+ lineHeight: typeScaleVars['--text-heading-4-leading'],
+ },
+ h5: {
+ fontSize: typeScaleVars['--text-heading-5-size'],
+ fontWeight: typeScaleVars['--text-heading-5-weight'],
+ lineHeight: typeScaleVars['--text-heading-5-leading'],
+ },
+ h6: {
+ fontSize: typeScaleVars['--text-heading-6-size'],
+ fontWeight: typeScaleVars['--text-heading-6-weight'],
+ lineHeight: typeScaleVars['--text-heading-6-leading'],
+ },
+ // Block spacing — per element type, default density
+ spacingHeadingMajorDefault: {
+ marginBlockStart: spacingVars['--spacing-6'],
+ marginBlockEnd: spacingVars['--spacing-3'],
+ },
+ spacingHeadingMinorDefault: {
+ marginBlockStart: spacingVars['--spacing-4'],
+ marginBlockEnd: spacingVars['--spacing-2'],
+ },
+ spacingParagraphDefault: {
+ marginBlockStart: spacingVars['--spacing-3'],
+ marginBlockEnd: spacingVars['--spacing-3'],
+ },
+ spacingCodeblockDefault: {
+ marginBlockStart: spacingVars['--spacing-4'],
+ marginBlockEnd: spacingVars['--spacing-4'],
+ },
+ spacingBlockquoteDefault: {
+ marginBlockStart: spacingVars['--spacing-4'],
+ marginBlockEnd: spacingVars['--spacing-4'],
+ },
+ spacingListDefault: {
+ marginBlockStart: spacingVars['--spacing-3'],
+ marginBlockEnd: spacingVars['--spacing-3'],
+ },
+ spacingTableDefault: {
+ marginBlockStart: spacingVars['--spacing-4'],
+ marginBlockEnd: spacingVars['--spacing-4'],
+ },
+ spacingHrDefault: {
+ marginBlockStart: spacingVars['--spacing-6'],
+ marginBlockEnd: spacingVars['--spacing-6'],
+ },
+ spacingImageDefault: {
+ marginBlockStart: spacingVars['--spacing-3'],
+ marginBlockEnd: spacingVars['--spacing-3'],
+ },
+ // Block spacing — per element type, compact density
+ spacingHeadingMajorCompact: {
+ marginBlockStart: spacingVars['--spacing-4'],
+ marginBlockEnd: spacingVars['--spacing-2'],
+ },
+ spacingHeadingMinorCompact: {
+ marginBlockStart: spacingVars['--spacing-3'],
+ marginBlockEnd: spacingVars['--spacing-1'],
+ },
+ spacingParagraphCompact: {
+ marginBlockStart: spacingVars['--spacing-1'],
+ marginBlockEnd: spacingVars['--spacing-1'],
+ },
+ spacingCodeblockCompact: {
+ marginBlockStart: spacingVars['--spacing-2'],
+ marginBlockEnd: spacingVars['--spacing-2'],
+ },
+ spacingBlockquoteCompact: {
+ marginBlockStart: spacingVars['--spacing-2'],
+ marginBlockEnd: spacingVars['--spacing-2'],
+ },
+ spacingListCompact: {
+ marginBlockStart: spacingVars['--spacing-1'],
+ marginBlockEnd: spacingVars['--spacing-1'],
+ },
+ spacingTableCompact: {
+ marginBlockStart: spacingVars['--spacing-2'],
+ marginBlockEnd: spacingVars['--spacing-2'],
+ },
+ spacingHrCompact: {
+ marginBlockStart: spacingVars['--spacing-3'],
+ marginBlockEnd: spacingVars['--spacing-3'],
+ },
+ spacingImageCompact: {
+ marginBlockStart: spacingVars['--spacing-2'],
+ marginBlockEnd: spacingVars['--spacing-2'],
+ },
+ noMarginBlockStart: {
+ marginBlockStart: 0,
+ },
+ noMarginBlockEnd: {
+ marginBlockEnd: 0,
+ },
+ // Blockquote
+ blockquote: {
+ borderInlineStartWidth: spacingVars['--spacing-0-5'],
+ borderInlineStartStyle: 'solid',
+ borderInlineStartColor: colorVars['--color-accent'],
+ paddingInlineStart: spacingVars['--spacing-4'],
+ color: colorVars['--color-text-secondary'],
+ marginInlineStart: 0,
+ marginInlineEnd: 0,
+ },
+ // List
+ list: {
+ paddingInlineStart: spacingVars['--spacing-6'],
+ },
+
+ // Table
+ tableWrapper: {
+ overflowX: 'auto',
+ },
+ table: {
+ borderCollapse: 'collapse',
+ width: '100%',
+ },
+ th: {
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ textAlign: 'left',
+ padding: spacingVars['--spacing-2'],
+ borderBottomWidth: borderVars['--border-width'],
+ borderBottomStyle: 'solid',
+ borderBottomColor: colorVars['--color-border-emphasized'],
+ },
+ td: {
+ padding: spacingVars['--spacing-2'],
+ borderBottomWidth: borderVars['--border-width'],
+ borderBottomStyle: 'solid',
+ borderBottomColor: colorVars['--color-border'],
+ },
+ alignLeft: {textAlign: 'left'},
+ alignCenter: {textAlign: 'center'},
+ alignRight: {textAlign: 'right'},
+ // HR
+ hr: {
+ borderWidth: 0,
+ borderTopWidth: borderVars['--border-width'],
+ borderTopStyle: 'solid',
+ borderTopColor: colorVars['--color-border'],
+ },
+ // Image
+ image: {
+ maxWidth: '100%',
+ borderRadius: radiusVars['--radius-element'],
+ },
+ // Inline
+ bold: {
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ },
+ strikethrough: {
+ color: colorVars['--color-text-secondary'],
+ },
+ link: {
+ color: colorVars['--color-text-accent'],
+ textDecoration: {
+ default: 'none',
+ ':hover': 'underline',
+ },
+ },
+});
+
+const headingStyles = {
+ 1: styles.h1,
+ 2: styles.h2,
+ 3: styles.h3,
+ 4: styles.h4,
+ 5: styles.h5,
+ 6: styles.h6,
+} as const;
+
+// ---------------------------------------------------------------------------
+// URL sanitization — block dangerous protocols
+// ---------------------------------------------------------------------------
+
+const DANGEROUS_URL_PATTERN = /^(javascript|data|vbscript):/i;
+
+function sanitizeUrl(url: string): string | null {
+ const trimmed = url.trim();
+ if (trimmed.length === 0) return null;
+ if (DANGEROUS_URL_PATTERN.test(trimmed)) return null;
+ return trimmed;
+}
+
+// ---------------------------------------------------------------------------
+// Inline renderer
+// ---------------------------------------------------------------------------
+
+function renderInline(
+ node: InlineNode,
+ index: number,
+ onLinkClick?: XDSMarkdownProps['onLinkClick'],
+): React.ReactNode {
+ switch (node.type) {
+ case 'text':
+ return node.content;
+ case 'bold':
+ return (
+ <strong key={index} {...stylex.props(styles.bold)}>
+ {node.children.map((c, i) => renderInline(c, i, onLinkClick))}
+ </strong>
+ );
+ case 'italic':
+ return (
+ <em key={index}>
+ {node.children.map((c, i) => renderInline(c, i, onLinkClick))}
+ </em>
+ );
+ case 'strikethrough':
+ return (
+ <del key={index} {...stylex.props(styles.strikethrough)}>
+ {node.children.map((c, i) => renderInline(c, i, onLinkClick))}
+ </del>
+ );
+ case 'code':
+ return <XDSCode key={index}>{node.content}</XDSCode>;
+ case 'link': {
+ const safeHref = sanitizeUrl(node.href);
+ if (safeHref == null) {
+ // Unsafe URL — render as plain text
+ return <span key={index}>{node.children.map((c, i) => renderInline(c, i, onLinkClick))}</span>;
+ }
+ const isExternal = safeHref.startsWith('http');
+ const handleClick = onLinkClick
+ ? (e: React.MouseEvent<HTMLAnchorElement>) => {
+ const result = onLinkClick(safeHref, e);
+ if (result === false) {
+ e.preventDefault();
+ }
+ }
+ : undefined;
+ return (
+ <a
+ key={index}
+ href={safeHref}
+ onClick={handleClick}
+ {...(isExternal ? {target: '_blank', rel: 'noopener noreferrer'} : {})}
+ {...stylex.props(styles.link)}
+ >
+ {node.children.map((c, i) => renderInline(c, i, onLinkClick))}
+ </a>
+ );
+ }
+ case 'image': {
+ const safeSrc = sanitizeUrl(node.src);
+ if (safeSrc == null) return <span key={index}>[{node.alt}]</span>;
+ return <img key={index} src={safeSrc} alt={node.alt} {...stylex.props(styles.image)} />;
+ }
+ case 'break':
+ return <br key={index} />;
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Block spacing helper
+// ---------------------------------------------------------------------------
+
+function getElementSpacing(
+ node: BlockNode,
+ density: 'default' | 'compact',
+): StyleXStyles {
+ const compact = density === 'compact';
+ switch (node.type) {
+ case 'heading':
+ return node.level <= 3
+ ? (compact ? styles.spacingHeadingMajorCompact : styles.spacingHeadingMajorDefault)
+ : (compact ? styles.spacingHeadingMinorCompact : styles.spacingHeadingMinorDefault);
+ case 'paragraph':
+ return compact ? styles.spacingParagraphCompact : styles.spacingParagraphDefault;
+ case 'codeblock':
+ return compact ? styles.spacingCodeblockCompact : styles.spacingCodeblockDefault;
+ case 'blockquote':
+ return compact ? styles.spacingBlockquoteCompact : styles.spacingBlockquoteDefault;
+ case 'list':
+ return compact ? styles.spacingListCompact : styles.spacingListDefault;
+ case 'table':
+ return compact ? styles.spacingTableCompact : styles.spacingTableDefault;
+ case 'hr':
+ return compact ? styles.spacingHrCompact : styles.spacingHrDefault;
+ case 'image':
+ return compact ? styles.spacingImageCompact : styles.spacingImageDefault;
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Block renderer
+// ---------------------------------------------------------------------------
+
+function renderBlock(
+ node: BlockNode,
+ index: number,
+ blockCount: number,
+ density: 'default' | 'compact',
+ headingLevelStart: 1 | 2 | 3 | 4 | 5 | 6,
+ onLinkClick?: XDSMarkdownProps['onLinkClick'],
+): React.ReactNode {
+ const spacing = getElementSpacing(node, density);
+ const isFirst = index === 0;
+ const isLast = index === blockCount - 1;
+
+ switch (node.type) {
+ case 'heading': {
+ const level = Math.min(node.level + headingLevelStart - 1, 6) as 1 | 2 | 3 | 4 | 5 | 6;
+ const Tag = `h${level}` as const;
+ return (
+ <Tag
+ key={index}
+ {...stylex.props(
+ styles.headingBase,
+ headingStyles[level],
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ )}
+ >
+ {node.children.map((c, i) => renderInline(c, i, onLinkClick))}
+ </Tag>
+ );
+ }
+ case 'paragraph':
+ return (
+ <p
+ key={index}
+ {...stylex.props(
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ )}
+ >
+ {node.children.map((c, i) => renderInline(c, i, onLinkClick))}
+ </p>
+ );
+ case 'codeblock':
+ return (
+ <div
+ key={index}
+ {...stylex.props(
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ )}
+ >
+ <XDSCodeBlock code={node.content} language={node.language} />
+ </div>
+ );
+ case 'blockquote':
+ return (
+ <blockquote
+ key={index}
+ {...stylex.props(
+ styles.blockquote,
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ )}
+ >
+ {node.children.map((c, i) => renderBlock(c, i, node.children.length, density, headingLevelStart, onLinkClick))}
+ </blockquote>
+ );
+ case 'list': {
+ // Detect task lists: all items have a checked state
+ const isTaskList = node.items.length > 0 && node.items.every(item => item.checked != null);
+
+ if (isTaskList) {
+ // Extract labels from task items — use first paragraph's inline text
+ const checkedValues = node.items
+ .map((item, i) => ({item, key: `task-${i}`}))
+ .filter(({item}) => item.checked)
+ .map(({key}) => key);
+
+ return (
+ <div
+ key={index}
+ {...stylex.props(
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ )}
+ >
+ <XDSCheckboxList
+ label="Task list"
+ isLabelHidden
+ value={checkedValues}
+ isDisabled
+ density={density === 'compact' ? 'compact' : 'balanced'}
+ >
+ {node.items.map((item, i) => {
+ const firstChild = item.children[0];
+ const isInline = item.children.length === 1 && firstChild?.type === 'paragraph';
+ // Build label from first paragraph text
+ const label = isInline
+ ? firstChild.children.map(c => c.type === 'text' ? c.content : '').join('')
+ : `Item ${i + 1}`;
+
+ return (
+ <XDSCheckboxListItem
+ key={i}
+ value={`task-${i}`}
+ label={label}
+ description={
+ isInline
+ ? undefined
+ : undefined
+ }
+ />
+ );
+ })}
+ </XDSCheckboxList>
+ </div>
+ );
+ }
+
+ const Tag = node.ordered ? 'ol' : 'ul';
+ return (
+ <Tag
+ key={index}
+ {...(node.ordered && node.start != null ? {start: node.start} : {})}
+ {...stylex.props(
+ styles.list,
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ )}
+ >
+ {node.items.map((item, i) => {
+ const firstChild = item.children[0];
+ const isInline = item.children.length === 1 && firstChild?.type === 'paragraph';
+
+ return (
+ <li key={i}>
+ {isInline ? (
+ <span>{firstChild.children.map((c, j) => renderInline(c, j, onLinkClick))}</span>
+ ) : (
+ item.children.map((c, j) => renderBlock(c, j, item.children.length, density, headingLevelStart, onLinkClick))
+ )}
+ </li>
+ );
+ })}
+ </Tag>
+ );
+ }
+ case 'table': {
+ const alignStyle = (a: typeof node.alignments[number]) =>
+ a === 'center' ? styles.alignCenter : a === 'right' ? styles.alignRight : styles.alignLeft;
+ return (
+ <div
+ key={index}
+ {...stylex.props(
+ styles.tableWrapper,
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ )}
+ >
+ <table {...stylex.props(styles.table)}>
+ <thead>
+ <tr>
+ {node.headers.map((h, i) => (
+ <th key={i} {...stylex.props(styles.th, alignStyle(node.alignments[i]))}>
+ {h.children.map((c, j) => renderInline(c, j, onLinkClick))}
+ </th>
+ ))}
+ </tr>
+ </thead>
+ <tbody>
+ {node.rows.map((row, i) => (
+ <tr key={i}>
+ {row.map((cell, j) => (
+ <td key={j} {...stylex.props(styles.td, alignStyle(node.alignments[j]))}>
+ {cell.children.map((c, k) => renderInline(c, k, onLinkClick))}
+ </td>
+ ))}
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </div>
+ );
+ }
+ case 'hr':
+ return (
+ <hr
+ key={index}
+ {...stylex.props(
+ styles.hr,
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ )}
+ />
+ );
+ case 'image': {
+ const safeSrc = sanitizeUrl(node.src);
+ if (safeSrc == null) {
+ return (
+ <p
+ key={index}
+ {...stylex.props(
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ )}
+ >
+ [{node.alt}]
+ </p>
+ );
+ }
+ return (
+ <p
+ key={index}
+ {...stylex.props(
+ spacing,
+ isFirst && styles.noMarginBlockStart,
+ isLast && styles.noMarginBlockEnd,
+ )}
+ >
+ <img src={safeSrc} alt={node.alt} {...stylex.props(styles.image)} />
+ </p>
+ );
+ }
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function XDSMarkdown({
+ ref,
+ children,
+ density = 'default',
+ headingLevelStart = 1,
+ isStreaming = false,
+ onLinkClick,
+ xstyle,
+ className,
+ style,
+ 'data-testid': testId,
+}: XDSMarkdownProps): React.ReactElement {
+ const incrementalState = useRef<IncrementalState>(createIncrementalState());
+
+ const blocks = useMemo(() => {
+ if (isStreaming) {
+ if (children === '') {
+ incrementalState.current = createIncrementalState();
+ return [];
+ }
+ const input = trimStreamingArtifacts(children);
+ return parseMarkdownIncremental(input, incrementalState.current);
+ }
+ return parseMarkdown(children);
+ }, [children, isStreaming]);
+
+ return (
+ <div
+ role="document"
+ ref={ref}
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('markdown', {density}),
+ stylex.props(styles.root, xstyle),
+ className,
+ style,
+ )}
+ >
+ {blocks.map((block, i) => renderBlock(block, i, blocks.length, density, headingLevelStart, onLinkClick))}
+ </div>
+ );
+}
+
+XDSMarkdown.displayName = 'XDSMarkdown';
diff --git a/packages/core/src/Markdown/incremental.test.ts b/packages/core/src/Markdown/incremental.test.ts
new file mode 100644
index 0000000000..8b9d6b2402
--- /dev/null
+++ b/packages/core/src/Markdown/incremental.test.ts
@@ -0,0 +1,159 @@
+import {describe, it, expect} from 'vitest';
+import {parseMarkdown, parseMarkdownIncremental, createIncrementalState} from './parser';
+import type {BlockNode} from './parser';
+
+function simulateStreaming(fullText: string, chunkSize = 10) {
+ const state = createIncrementalState();
+ const snapshots: BlockNode[][] = [];
+ for (let i = chunkSize; i <= fullText.length; i += chunkSize) {
+ snapshots.push(parseMarkdownIncremental(fullText.slice(0, i), state));
+ }
+ const final = parseMarkdownIncremental(fullText, state);
+ snapshots.push(final);
+ return {snapshots, final, state};
+}
+
+describe('parseMarkdownIncremental', () => {
+ it('produces same final result as full parse', () => {
+ const text = '# Hello\n\nThis is a paragraph.\n\n- Item 1\n- Item 2';
+ const {final} = simulateStreaming(text);
+ const full = parseMarkdown(text);
+ expect(final).toEqual(full);
+ });
+
+ it('handles empty input', () => {
+ const state = createIncrementalState();
+ const result = parseMarkdownIncremental('', state);
+ expect(result).toEqual([]);
+ });
+
+ it('settles blocks after double newline', () => {
+ const state = createIncrementalState();
+ const input = '# Heading\n\nParagraph text\n\nMore text';
+ parseMarkdownIncremental(input, state);
+ expect(state.settledBlocks.length).toBeGreaterThan(0);
+ });
+
+ it('code fences prevent false settlement', () => {
+ const state = createIncrementalState();
+ const input = '```javascript\nconst x = 1;\n\n// still in code\nconsole.log(x);';
+ parseMarkdownIncremental(input, state);
+ // Inside an unclosed fence, nothing should be settled
+ expect(state.settledBlocks).toHaveLength(0);
+ });
+
+ it('handles heading then code block', () => {
+ const text = '# Title\n\n```ts\nconst x = 1;\n```';
+ const {final} = simulateStreaming(text);
+ const full = parseMarkdown(text);
+ expect(final).toEqual(full);
+ });
+
+ it('handles table streaming', () => {
+ const text = '| Col1 | Col2 |\n| --- | --- |\n| a | b |\n| c | d |';
+ const {final} = simulateStreaming(text, 5);
+ const full = parseMarkdown(text);
+ expect(final).toEqual(full);
+ });
+
+ it('handles list streaming', () => {
+ const text = '- Item 1\n- Item 2\n- Item 3';
+ const {final} = simulateStreaming(text);
+ const full = parseMarkdown(text);
+ expect(final).toEqual(full);
+ if (final[0].type === 'list') {
+ expect(final[0].items).toHaveLength(3);
+ }
+ });
+
+ it('handles 1-char chunks and matches full parse', () => {
+ const text = '# Hello\n\nWorld';
+ const {final} = simulateStreaming(text, 1);
+ const full = parseMarkdown(text);
+ expect(final).toEqual(full);
+ });
+
+ it('handles multiple code fences', () => {
+ const text = '```js\nconst a = 1;\n```\n\n```py\nprint("hi")\n```';
+ const {final} = simulateStreaming(text);
+ const full = parseMarkdown(text);
+ expect(final).toEqual(full);
+ });
+
+ it('resets state on empty input', () => {
+ const state = createIncrementalState();
+ parseMarkdownIncremental('# Hello\n\nWorld', state);
+ expect(state.prevInput).not.toBe('');
+ parseMarkdownIncremental('', state);
+ expect(state.prevInput).toBe('');
+ expect(state.settledBlocks).toEqual([]);
+ expect(state.settledUpTo).toBe(0);
+ expect(state.settledText).toBe('');
+ });
+
+ it('unclosed fence keeps everything unsettled', () => {
+ const state = createIncrementalState();
+ const input = '# Title\n\n```python\ndef foo():\n pass\n\n# still inside fence';
+ parseMarkdownIncremental(input, state);
+ expect(state.settledBlocks).toHaveLength(0);
+ });
+
+ it('handles task list streaming', () => {
+ const text = '- [ ] Todo 1\n- [x] Done 1\n- [ ] Todo 2';
+ const {final} = simulateStreaming(text);
+ const full = parseMarkdown(text);
+ expect(final).toEqual(full);
+ if (final[0].type === 'list') {
+ expect(final[0].items[0].checked).toBe(false);
+ expect(final[0].items[1].checked).toBe(true);
+ }
+ });
+
+ it('complex mixed content matches full parse', () => {
+ const text = [
+ '# Overview',
+ '',
+ 'This is an introduction paragraph.',
+ '',
+ '```typescript',
+ 'function hello() {',
+ ' return "world";',
+ '}',
+ '```',
+ '',
+ '| Feature | Status |',
+ '| --- | --- |',
+ '| Auth | Done |',
+ '',
+ '> A blockquote with important info.',
+ '',
+ '1. First step',
+ '2. Second step',
+ '',
+ '---',
+ '',
+ 'Visit [our site](https://example.com) for more.',
+ ].join('\n');
+ const {final} = simulateStreaming(text, 15);
+ const full = parseMarkdown(text);
+ expect(final).toEqual(full);
+ });
+
+ it('reuses cached settled blocks when settled portion is unchanged', () => {
+ const state = createIncrementalState();
+ // First call: establish settled content
+ parseMarkdownIncremental('# Title\n\nParagraph\n\nStill typing', state);
+ const cachedBlocks = state.settledBlocks;
+
+ // Second call: only unsettled tail changed
+ parseMarkdownIncremental('# Title\n\nParagraph\n\nStill typing more', state);
+ // The settled blocks array reference should be the same (reused, not re-parsed)
+ expect(state.settledBlocks).toBe(cachedBlocks);
+ });
+
+ it('tracks settledText correctly', () => {
+ const state = createIncrementalState();
+ parseMarkdownIncremental('# Hello\n\nWorld', state);
+ expect(state.settledText).toBe('# Hello');
+ });
+});
diff --git a/packages/core/src/Markdown/index.ts b/packages/core/src/Markdown/index.ts
new file mode 100644
index 0000000000..e9baab6797
--- /dev/null
+++ b/packages/core/src/Markdown/index.ts
@@ -0,0 +1,25 @@
+'use client';
+
+/**
+ * @file index.ts
+ * @output Exports Markdown component, parser functions, and types
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ */
+
+export {XDSMarkdown} from './XDSMarkdown';
+export type {XDSMarkdownProps} from './XDSMarkdown';
+
+export {
+ parseMarkdown,
+ parseMarkdownIncremental,
+ createIncrementalState,
+ parseInline,
+} from './parser';
+export type {
+ BlockNode,
+ InlineNode,
+ ListItemNode,
+ TableCellNode,
+ TableAlignment,
+ IncrementalState as IncrementalParseState,
+} from './parser';
diff --git a/packages/core/src/Markdown/parser.perf.test.ts b/packages/core/src/Markdown/parser.perf.test.ts
new file mode 100644
index 0000000000..ea65c42933
--- /dev/null
+++ b/packages/core/src/Markdown/parser.perf.test.ts
@@ -0,0 +1,138 @@
+import {describe, it, expect} from 'vitest';
+import {parseMarkdown, parseMarkdownIncremental, createIncrementalState} from './parser';
+import type {BlockNode} from './parser';
+
+function generateAIResponse(paragraphs: number): string {
+ const sections: string[] = [];
+ for (let i = 0; i < paragraphs; i++) {
+ const mod = i % 6;
+ switch (mod) {
+ case 0:
+ sections.push(`## Section ${i + 1}\n\nThis is paragraph ${i + 1} of the AI response. It contains analysis about the data and provides context for the following sections.`);
+ break;
+ case 1:
+ sections.push('```typescript\nfunction process(data: Record<string, unknown>[]) {\n return data.filter(item => item.valid)\n .map(item => transform(item))\n .reduce((acc, val) => merge(acc, val), {});\n}\n```');
+ break;
+ case 2:
+ sections.push(`- First point about topic ${i}\n- Second important finding\n- Third observation with **bold emphasis**\n- Fourth conclusion`);
+ break;
+ case 3:
+ sections.push(`| Metric | Value | Change |\n| :--- | :---: | ---: |\n| Accuracy | ${90 + (i % 10)}% | +${i % 5}% |\n| Latency | ${10 + i}ms | -${i % 3}ms |`);
+ break;
+ case 4:
+ sections.push(`> **Note:** This is an important observation about item ${i}.\n> It spans multiple lines and contains *italic* text.`);
+ break;
+ case 5:
+ sections.push(`1. Step one of process ${i}\n2. Step two with \`inline code\`\n3. Final step with [link](https://example.com/${i})`);
+ break;
+ }
+ }
+ return sections.join('\n\n');
+}
+
+function simulateStreamingFullReparse(fullText: string, chunkSize = 50): BlockNode[] {
+ let result: BlockNode[] = [];
+ for (let i = chunkSize; i <= fullText.length; i += chunkSize) {
+ result = parseMarkdown(fullText.slice(0, i));
+ }
+ result = parseMarkdown(fullText);
+ return result;
+}
+
+function simulateStreamingIncremental(fullText: string, chunkSize = 50): BlockNode[] {
+ const state = createIncrementalState();
+ let result: BlockNode[] = [];
+ for (let i = chunkSize; i <= fullText.length; i += chunkSize) {
+ result = parseMarkdownIncremental(fullText.slice(0, i), state);
+ }
+ result = parseMarkdownIncremental(fullText, state);
+ return result;
+}
+
+describe('parseMarkdown performance', () => {
+ const sizes = [
+ {name: 'Small', paragraphs: 10, maxMs: 20},
+ {name: 'Medium', paragraphs: 50, maxMs: 50},
+ {name: 'Large', paragraphs: 200, maxMs: 100},
+ {name: 'XL', paragraphs: 500, maxMs: 400},
+ {name: 'XXL', paragraphs: 2000, maxMs: 1000},
+ ];
+
+ // Report sizes
+ it('reports input sizes', () => {
+ for (const size of sizes) {
+ const text = generateAIResponse(size.paragraphs);
+ const lines = text.split('\n').length;
+ console.log(`${size.name} (${size.paragraphs} paragraphs): ${text.length} chars, ${lines} lines`);
+ }
+ });
+
+ // Full re-parse benchmarks
+ for (const size of sizes) {
+ it(`full re-parse ${size.name} (${size.paragraphs} paragraphs) under ${size.maxMs}ms`, () => {
+ const text = generateAIResponse(size.paragraphs);
+ const start = performance.now();
+ const result = parseMarkdown(text);
+ const elapsed = performance.now() - start;
+ console.log(` ${size.name} full parse: ${elapsed.toFixed(2)}ms → ${result.length} blocks`);
+ expect(elapsed).toBeLessThan(size.maxMs);
+ expect(result.length).toBeGreaterThan(0);
+ });
+ }
+
+ // Streaming with full re-parse
+ for (const size of [{name: 'Medium', paragraphs: 50, maxMs: 5000}, {name: 'XL', paragraphs: 500, maxMs: 30000}]) {
+ it(`streaming full re-parse ${size.name} under ${size.maxMs}ms`, () => {
+ const text = generateAIResponse(size.paragraphs);
+ const chunkSize = 50;
+ const iterations = Math.ceil(text.length / chunkSize);
+ const start = performance.now();
+ const result = simulateStreamingFullReparse(text, chunkSize);
+ const elapsed = performance.now() - start;
+ console.log(` ${size.name} streaming full re-parse: ${elapsed.toFixed(2)}ms (${iterations} iterations)`);
+ expect(elapsed).toBeLessThan(size.maxMs);
+ expect(result.length).toBeGreaterThan(0);
+ });
+ }
+
+ // Streaming with incremental parse
+ for (const size of [{name: 'Medium', paragraphs: 50, maxMs: 5000}, {name: 'XL', paragraphs: 500, maxMs: 30000}]) {
+ it(`streaming incremental ${size.name} under ${size.maxMs}ms`, () => {
+ const text = generateAIResponse(size.paragraphs);
+ const chunkSize = 50;
+ const iterations = Math.ceil(text.length / chunkSize);
+ const start = performance.now();
+ const result = simulateStreamingIncremental(text, chunkSize);
+ const elapsed = performance.now() - start;
+ console.log(` ${size.name} streaming incremental: ${elapsed.toFixed(2)}ms (${iterations} iterations)`);
+ expect(elapsed).toBeLessThan(size.maxMs);
+ expect(result.length).toBeGreaterThan(0);
+ });
+ }
+
+ // --- Incremental vs Full speedup benchmark ---
+ it('incremental parse is faster than full re-parse for streaming', () => {
+ const text = generateAIResponse(200);
+ const chunkSize = 50;
+
+ // Full re-parse timing
+ const fullStart = performance.now();
+ simulateStreamingFullReparse(text, chunkSize);
+ const fullElapsed = performance.now() - fullStart;
+
+ // Incremental timing
+ const incrStart = performance.now();
+ simulateStreamingIncremental(text, chunkSize);
+ const incrElapsed = performance.now() - incrStart;
+
+ const speedup = fullElapsed / incrElapsed;
+ console.log(`\n === Incremental vs Full Re-parse Speedup ===`);
+ console.log(` Input: ${text.length} chars, chunk size: ${chunkSize}`);
+ console.log(` Full re-parse: ${fullElapsed.toFixed(2)}ms`);
+ console.log(` Incremental: ${incrElapsed.toFixed(2)}ms`);
+ console.log(` Speedup ratio: ${speedup.toFixed(2)}x\n`);
+
+ // Incremental should be at least as fast (allowing small margin for noise)
+ expect(incrElapsed).toBeLessThanOrEqual(fullElapsed * 1.1);
+ });
+});
diff --git a/packages/core/src/Markdown/parser.test.ts b/packages/core/src/Markdown/parser.test.ts
new file mode 100644
index 0000000000..539c377b8a
--- /dev/null
+++ b/packages/core/src/Markdown/parser.test.ts
@@ -0,0 +1,368 @@
+import {describe, it, expect} from 'vitest';
+import {parseMarkdown, parseInline} from './parser';
+
+describe('parseInline', () => {
+ it('parses plain text', () => {
+ const result = parseInline('hello world');
+ expect(result).toEqual([{type: 'text', content: 'hello world'}]);
+ });
+
+ it('parses bold with **', () => {
+ const result = parseInline('**bold text**');
+ expect(result[0].type).toBe('bold');
+ if (result[0].type === 'bold') {
+ expect(result[0].children[0]).toEqual({type: 'text', content: 'bold text'});
+ }
+ });
+
+ it('parses italic with *', () => {
+ const result = parseInline('*italic text*');
+ expect(result[0].type).toBe('italic');
+ if (result[0].type === 'italic') {
+ expect(result[0].children[0]).toEqual({type: 'text', content: 'italic text'});
+ }
+ });
+
+ it('parses inline code', () => {
+ const result = parseInline('`const x`');
+ expect(result).toEqual([{type: 'code', content: 'const x'}]);
+ });
+
+ it('parses links', () => {
+ const result = parseInline('[click](https://example.com)');
+ expect(result[0].type).toBe('link');
+ if (result[0].type === 'link') {
+ expect(result[0].href).toBe('https://example.com');
+ expect(result[0].children[0]).toEqual({type: 'text', content: 'click'});
+ }
+ });
+
+ it('parses images', () => {
+ const result = parseInline('![alt](img.png)');
+ expect(result).toEqual([{type: 'image', src: 'img.png', alt: 'alt'}]);
+ });
+
+ it('parses strikethrough', () => {
+ const result = parseInline('~~deleted~~');
+ expect(result[0].type).toBe('strikethrough');
+ if (result[0].type === 'strikethrough') {
+ expect(result[0].children[0]).toEqual({type: 'text', content: 'deleted'});
+ }
+ });
+
+ it('parses mixed inline formatting', () => {
+ const result = parseInline('Hello **bold** and *italic* with `code` and [link](url)');
+ expect(result.length).toBeGreaterThanOrEqual(5);
+ });
+
+ it('handles escape sequences', () => {
+ const result = parseInline('\\*not italic\\*');
+ const hasItalic = result.some(n => n.type === 'italic');
+ expect(hasItalic).toBe(false);
+ });
+
+ // --- Bold-italic ---
+
+ it('parses ***bold italic*** with asterisks', () => {
+ const result = parseInline('***bold italic***');
+ expect(result).toHaveLength(1);
+ expect(result[0].type).toBe('bold');
+ if (result[0].type === 'bold') {
+ expect(result[0].children).toHaveLength(1);
+ expect(result[0].children[0].type).toBe('italic');
+ if (result[0].children[0].type === 'italic') {
+ expect(result[0].children[0].children[0]).toEqual({type: 'text', content: 'bold italic'});
+ }
+ }
+ });
+
+ it('parses ___bold italic___ with underscores', () => {
+ const result = parseInline('___bold italic___');
+ expect(result).toHaveLength(1);
+ expect(result[0].type).toBe('bold');
+ if (result[0].type === 'bold') {
+ expect(result[0].children[0].type).toBe('italic');
+ }
+ });
+
+ // --- Underscore word boundary ---
+
+ it('does NOT italicize underscores inside words', () => {
+ const result = parseInline('some_variable_name');
+ expect(result).toHaveLength(1);
+ expect(result[0].type).toBe('text');
+ if (result[0].type === 'text') {
+ expect(result[0].content).toBe('some_variable_name');
+ }
+ });
+
+ it('does NOT bold underscores inside words', () => {
+ const result = parseInline('foo__bar__baz');
+ expect(result).toHaveLength(1);
+ expect(result[0].type).toBe('text');
+ if (result[0].type === 'text') {
+ expect(result[0].content).toBe('foo__bar__baz');
+ }
+ });
+
+ it('italicizes underscores at word boundaries', () => {
+ const result = parseInline('hello _world_ end');
+ const italic = result.find(n => n.type === 'italic');
+ expect(italic).toBeDefined();
+ if (italic?.type === 'italic') {
+ expect(italic.children[0]).toEqual({type: 'text', content: 'world'});
+ }
+ });
+
+ it('asterisk italic works mid-word', () => {
+ const result = parseInline('some*thing*here');
+ const italic = result.find(n => n.type === 'italic');
+ expect(italic).toBeDefined();
+ });
+
+ // --- Balanced parentheses in URLs ---
+
+ it('handles parentheses in link URLs', () => {
+ const result = parseInline('[text](https://example.com/wiki/Foo_(bar))');
+ expect(result[0].type).toBe('link');
+ if (result[0].type === 'link') {
+ expect(result[0].href).toBe('https://example.com/wiki/Foo_(bar)');
+ }
+ });
+
+ it('handles parentheses in image URLs', () => {
+ const result = parseInline('![alt](https://example.com/img_(1).png)');
+ expect(result[0].type).toBe('image');
+ if (result[0].type === 'image') {
+ expect(result[0].src).toBe('https://example.com/img_(1).png');
+ }
+ });
+
+ // --- Line breaks ---
+
+ it('detects line break from two trailing spaces before newline', () => {
+ const result = parseInline('hello \nworld');
+ const breakNode = result.find(n => n.type === 'break');
+ expect(breakNode).toBeDefined();
+ expect(result).toEqual([
+ {type: 'text', content: 'hello'},
+ {type: 'break'},
+ {type: 'text', content: 'world'},
+ ]);
+ });
+
+ it('does NOT produce break with only one trailing space', () => {
+ const result = parseInline('hello \nworld');
+ const breakNode = result.find(n => n.type === 'break');
+ expect(breakNode).toBeUndefined();
+ });
+});
+
+describe('parseMarkdown', () => {
+ it('parses headings', () => {
+ const result = parseMarkdown('# Hello');
+ expect(result[0].type).toBe('heading');
+ if (result[0].type === 'heading') {
+ expect(result[0].level).toBe(1);
+ }
+ });
+
+ it('parses h1-h6', () => {
+ const input = '# H1\n## H2\n### H3\n#### H4\n##### H5\n###### H6';
+ const result = parseMarkdown(input);
+ expect(result).toHaveLength(6);
+ result.forEach((block, i) => {
+ expect(block.type).toBe('heading');
+ if (block.type === 'heading') {
+ expect(block.level).toBe(i + 1);
+ }
+ });
+ });
+
+ it('parses paragraphs', () => {
+ const result = parseMarkdown('Hello world');
+ expect(result[0].type).toBe('paragraph');
+ });
+
+ it('separates paragraphs by blank lines', () => {
+ const result = parseMarkdown('First paragraph\n\nSecond paragraph');
+ const paragraphs = result.filter(b => b.type === 'paragraph');
+ expect(paragraphs).toHaveLength(2);
+ });
+
+ it('parses fenced code blocks with backticks', () => {
+ const input = '```javascript\nconst x = 1;\nconsole.log(x);\n```';
+ const result = parseMarkdown(input);
+ expect(result[0].type).toBe('codeblock');
+ if (result[0].type === 'codeblock') {
+ expect(result[0].language).toBe('javascript');
+ expect(result[0].content).toContain('const x = 1;');
+ }
+ });
+
+ it('parses code blocks with tilde fences', () => {
+ const input = '~~~python\nprint("hello")\n~~~';
+ const result = parseMarkdown(input);
+ expect(result[0].type).toBe('codeblock');
+ if (result[0].type === 'codeblock') {
+ expect(result[0].language).toBe('python');
+ }
+ });
+
+ it('parses blockquotes', () => {
+ const result = parseMarkdown('> This is a quote');
+ expect(result[0].type).toBe('blockquote');
+ });
+
+ it('parses horizontal rules', () => {
+ const result = parseMarkdown('---');
+ expect(result[0].type).toBe('hr');
+ });
+
+ it('parses unordered lists', () => {
+ const input = '- Item 1\n- Item 2\n- Item 3';
+ const result = parseMarkdown(input);
+ expect(result[0].type).toBe('list');
+ if (result[0].type === 'list') {
+ expect(result[0].ordered).toBe(false);
+ expect(result[0].items).toHaveLength(3);
+ }
+ });
+
+ it('parses ordered lists', () => {
+ const input = '1. First\n2. Second';
+ const result = parseMarkdown(input);
+ expect(result[0].type).toBe('list');
+ if (result[0].type === 'list') {
+ expect(result[0].ordered).toBe(true);
+ expect(result[0].items).toHaveLength(2);
+ }
+ });
+
+ it('parses task lists', () => {
+ const input = '- [ ] Unchecked\n- [x] Checked';
+ const result = parseMarkdown(input);
+ expect(result[0].type).toBe('list');
+ if (result[0].type === 'list') {
+ expect(result[0].items[0].checked).toBe(false);
+ expect(result[0].items[1].checked).toBe(true);
+ }
+ });
+
+ it('parses GFM tables', () => {
+ const input = '| Name | Age |\n| --- | --- |\n| Alice | 30 |\n| Bob | 25 |';
+ const result = parseMarkdown(input);
+ expect(result[0].type).toBe('table');
+ if (result[0].type === 'table') {
+ expect(result[0].headers).toHaveLength(2);
+ expect(result[0].rows).toHaveLength(2);
+ }
+ });
+
+ it('parses table alignment', () => {
+ const input = '| Left | Center | Right |\n| :--- | :---: | ---: |\n| a | b | c |';
+ const result = parseMarkdown(input);
+ expect(result[0].type).toBe('table');
+ if (result[0].type === 'table') {
+ expect(result[0].alignments).toEqual(['left', 'center', 'right']);
+ }
+ });
+
+ it('parses standalone images', () => {
+ const result = parseMarkdown('![alt text](image.png)');
+ expect(result[0].type).toBe('image');
+ if (result[0].type === 'image') {
+ expect(result[0].src).toBe('image.png');
+ expect(result[0].alt).toBe('alt text');
+ }
+ });
+
+ it('parses complex AI response', () => {
+ const input = [
+ '# Analysis',
+ '',
+ 'Here is the result of the analysis.',
+ '',
+ '```typescript',
+ 'const result = analyze(data);',
+ '```',
+ '',
+ '- Point one',
+ '- Point two',
+ '- Point three',
+ '',
+ '> Important note about the findings.',
+ '',
+ '| Metric | Value |',
+ '| --- | --- |',
+ '| Score | 95 |',
+ ].join('\n');
+ const result = parseMarkdown(input);
+ const types = result.map(b => b.type);
+ expect(types).toContain('heading');
+ expect(types).toContain('paragraph');
+ expect(types).toContain('codeblock');
+ expect(types).toContain('list');
+ expect(types).toContain('blockquote');
+ expect(types).toContain('table');
+ });
+
+ // --- Nested lists ---
+
+ it('parses nested unordered lists', () => {
+ const input = '- Item 1\n - Nested 1a\n - Nested 1b\n- Item 2';
+ const result = parseMarkdown(input);
+ expect(result[0].type).toBe('list');
+ if (result[0].type === 'list') {
+ expect(result[0].items).toHaveLength(2);
+ // Item 1 should have children that include a nested list
+ const item1Children = result[0].items[0].children;
+ const nestedList = item1Children.find(c => c.type === 'list');
+ expect(nestedList).toBeDefined();
+ if (nestedList?.type === 'list') {
+ expect(nestedList.items).toHaveLength(2);
+ }
+ }
+ });
+
+ it('parses deeply nested lists', () => {
+ const input = '- L1\n - L2\n - L3';
+ const result = parseMarkdown(input);
+ expect(result[0].type).toBe('list');
+ if (result[0].type === 'list') {
+ const item = result[0].items[0];
+ const l2 = item.children.find(c => c.type === 'list');
+ expect(l2).toBeDefined();
+ if (l2?.type === 'list') {
+ const l3 = l2.items[0].children.find(c => c.type === 'list');
+ expect(l3).toBeDefined();
+ }
+ }
+ });
+
+ // --- Table without leading pipe ---
+
+ it('parses table without leading pipe', () => {
+ const input = 'Name | Age\n--- | ---\nAlice | 30\nBob | 25';
+ const result = parseMarkdown(input);
+ expect(result[0].type).toBe('table');
+ if (result[0].type === 'table') {
+ expect(result[0].headers).toHaveLength(2);
+ expect(result[0].rows).toHaveLength(2);
+ }
+ });
+
+ // --- HR variants ---
+
+ it('parses spaced HR: - - -', () => {
+ expect(parseMarkdown('- - -')[0].type).toBe('hr');
+ });
+
+ it('parses spaced HR: * * *', () => {
+ expect(parseMarkdown('* * *')[0].type).toBe('hr');
+ });
+
+ it('parses spaced HR: _ _ _', () => {
+ expect(parseMarkdown('_ _ _')[0].type).toBe('hr');
+ });
+});
diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.ts
new file mode 100644
index 0000000000..0be02ae5bc
--- /dev/null
+++ b/packages/core/src/Markdown/parser.ts
@@ -0,0 +1,574 @@
+/**
+ * @file parser.ts
+ * @input Markdown string
+ * @output Array of MarkdownNode AST nodes
+ * @position Core parser; consumed by XDSMarkdown.tsx
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type InlineNode =
+ | {type: 'text'; content: string}
+ | {type: 'bold'; children: InlineNode[]}
+ | {type: 'italic'; children: InlineNode[]}
+ | {type: 'strikethrough'; children: InlineNode[]}
+ | {type: 'code'; content: string}
+ | {type: 'link'; href: string; children: InlineNode[]}
+ | {type: 'image'; src: string; alt: string}
+ | {type: 'break'};
+
+export type BlockNode =
+ | {type: 'heading'; level: 1 | 2 | 3 | 4 | 5 | 6; children: InlineNode[]}
+ | {type: 'paragraph'; children: InlineNode[]}
+ | {type: 'codeblock'; language: string; content: string}
+ | {type: 'blockquote'; children: BlockNode[]}
+ | {type: 'list'; ordered: boolean; start?: number; items: ListItemNode[]}
+ | {type: 'table'; headers: TableCellNode[]; alignments: TableAlignment[]; rows: TableCellNode[][]}
+ | {type: 'hr'}
+ | {type: 'image'; src: string; alt: string};
+
+export type ListItemNode = {checked?: boolean; children: BlockNode[]};
+export type TableCellNode = {children: InlineNode[]};
+export type TableAlignment = 'left' | 'center' | 'right' | null;
+
+// ---------------------------------------------------------------------------
+// Inline parser helpers
+// ---------------------------------------------------------------------------
+
+/** Find closing ')' that balances nested parentheses. */
+function findClosingParen(text: string, start: number): number {
+ let depth = 1;
+ for (let index = start; index < text.length; index++) {
+ if (text[index] === '(') depth++;
+ else if (text[index] === ')') {
+ depth--;
+ if (depth === 0) return index;
+ }
+ }
+ return -1;
+}
+
+function isWordChar(ch: string | undefined): boolean {
+ if (ch == null) return false;
+ return /\w/.test(ch);
+}
+
+// ---------------------------------------------------------------------------
+// Inline parser
+// ---------------------------------------------------------------------------
+
+export function parseInline(text: string): InlineNode[] {
+ const nodes: InlineNode[] = [];
+ let i = 0;
+
+ while (i < text.length) {
+ // --- Escape ---
+ if (text[i] === '\\' && i + 1 < text.length) {
+ nodes.push({type: 'text', content: text[i + 1]});
+ i += 2;
+ continue;
+ }
+
+ // --- Inline code ---
+ if (text[i] === '`') {
+ const tickCount = text[i + 1] === '`' ? (text[i + 2] === '`' ? 3 : 2) : 1;
+ const openIndex = i + tickCount;
+ const closeIndex = text.indexOf('`'.repeat(tickCount), openIndex);
+ if (closeIndex !== -1) {
+ nodes.push({type: 'code', content: text.slice(openIndex, closeIndex)});
+ i = closeIndex + tickCount;
+ continue;
+ }
+ }
+
+ // --- Image ![alt](src) ---
+ if (text[i] === '!' && text[i + 1] === '[') {
+ const altClose = text.indexOf(']', i + 2);
+ if (altClose !== -1 && text[altClose + 1] === '(') {
+ const srcClose = findClosingParen(text, altClose + 2);
+ if (srcClose !== -1) {
+ nodes.push({type: 'image', src: text.slice(altClose + 2, srcClose), alt: text.slice(i + 2, altClose)});
+ i = srcClose + 1;
+ continue;
+ }
+ }
+ }
+
+ // --- Link [text](url) ---
+ if (text[i] === '[') {
+ const textClose = text.indexOf(']', i + 1);
+ if (textClose !== -1 && text[textClose + 1] === '(') {
+ const urlClose = findClosingParen(text, textClose + 2);
+ if (urlClose !== -1) {
+ nodes.push({type: 'link', href: text.slice(textClose + 2, urlClose), children: parseInline(text.slice(i + 1, textClose))});
+ i = urlClose + 1;
+ continue;
+ }
+ }
+ }
+
+ // --- Bold-italic: *** or ___ ---
+ if (
+ (text[i] === '*' && text[i + 1] === '*' && text[i + 2] === '*') ||
+ (text[i] === '_' && text[i + 1] === '_' && text[i + 2] === '_')
+ ) {
+ const marker = text.slice(i, i + 3);
+ const isUnderscore = text[i] === '_';
+ if (isUnderscore && isWordChar(text[i - 1])) {
+ // mid-word underscore — fall through
+ } else {
+ const closeIndex = text.indexOf(marker, i + 3);
+ if (closeIndex !== -1 && (!isUnderscore || !isWordChar(text[closeIndex + 3]))) {
+ nodes.push({type: 'bold', children: [{type: 'italic', children: parseInline(text.slice(i + 3, closeIndex))}]});
+ i = closeIndex + 3;
+ continue;
+ }
+ }
+ }
+
+ // --- Bold: ** or __ ---
+ if (
+ (text[i] === '*' && text[i + 1] === '*') ||
+ (text[i] === '_' && text[i + 1] === '_')
+ ) {
+ const marker = text.slice(i, i + 2);
+ const isUnderscore = text[i] === '_';
+ if (isUnderscore && isWordChar(text[i - 1])) {
+ // mid-word underscore — fall through
+ } else {
+ const closeIndex = text.indexOf(marker, i + 2);
+ if (closeIndex !== -1 && (!isUnderscore || !isWordChar(text[closeIndex + 2]))) {
+ nodes.push({type: 'bold', children: parseInline(text.slice(i + 2, closeIndex))});
+ i = closeIndex + 2;
+ continue;
+ }
+ }
+ }
+
+ // --- Strikethrough: ~~ ---
+ if (text[i] === '~' && text[i + 1] === '~') {
+ const closeIndex = text.indexOf('~~', i + 2);
+ if (closeIndex !== -1) {
+ nodes.push({type: 'strikethrough', children: parseInline(text.slice(i + 2, closeIndex))});
+ i = closeIndex + 2;
+ continue;
+ }
+ }
+
+ // --- Italic: * or _ ---
+ if (text[i] === '*' || text[i] === '_') {
+ const isUnderscore = text[i] === '_';
+ if (isUnderscore && isWordChar(text[i - 1])) {
+ // mid-word underscore — fall through
+ } else {
+ const closeIndex = text.indexOf(text[i], i + 1);
+ if (closeIndex !== -1 && closeIndex > i + 1 && (!isUnderscore || !isWordChar(text[closeIndex + 1]))) {
+ nodes.push({type: 'italic', children: parseInline(text.slice(i + 1, closeIndex))});
+ i = closeIndex + 1;
+ continue;
+ }
+ }
+ }
+
+ // --- Plain text (with line-break detection) ---
+ let end = i + 1;
+ while (end < text.length && !'*_~`[!\\\n'.includes(text[end])) end++;
+
+ const content = text.slice(i, end);
+
+ // Detect trailing-space line break: 2+ spaces immediately before \n
+ if (end < text.length && text[end] === '\n') {
+ const trimmed = content.replace(/ +$/, '');
+ if (content.length - trimmed.length >= 2) {
+ if (trimmed.length > 0) {
+ const last = nodes[nodes.length - 1];
+ if (last?.type === 'text') last.content += trimmed;
+ else nodes.push({type: 'text', content: trimmed});
+ }
+ nodes.push({type: 'break'});
+ i = end + 1;
+ continue;
+ }
+ }
+
+ const last = nodes[nodes.length - 1];
+ if (last?.type === 'text') last.content += content;
+ else nodes.push({type: 'text', content});
+ i = end;
+ }
+ return nodes;
+}
+
+// ---------------------------------------------------------------------------
+// Block parser helpers
+// ---------------------------------------------------------------------------
+
+function getIndent(line: string): number {
+ let count = 0;
+ while (count < line.length && line[count] === ' ') count++;
+ return count;
+}
+
+/** HR: 3+ identical markers (-, *, _) optionally separated by spaces. */
+function isHorizontalRule(line: string): boolean {
+ const trimmed = line.trim();
+ if (trimmed.length < 3) return false;
+ const stripped = trimmed.replace(/ /g, '');
+ if (stripped.length < 3) return false;
+ const ch = stripped[0];
+ if (ch !== '-' && ch !== '*' && ch !== '_') return false;
+ for (let idx = 1; idx < stripped.length; idx++) {
+ if (stripped[idx] !== ch) return false;
+ }
+ return true;
+}
+
+/** GFM separator row: cells contain only dashes/colons. */
+function isTableSeparator(line: string): boolean {
+ if (!line.includes('|')) return false;
+ const cells = line.split('|').map(cell => cell.trim());
+ const nonEmpty = cells.filter(cell => cell.length > 0);
+ return nonEmpty.length > 0 && nonEmpty.every(cell => /^:?-+:?$/.test(cell));
+}
+
+/**
+ * Returns true when a line could start a new block — used to stop paragraph
+ * continuation. Every regex here uses bounded or single-class quantifiers
+ * to avoid ReDoS.
+ */
+function isBlockStart(line: string): boolean {
+ if (/^#{1,6} /.test(line)) return true;
+ if (/^(`{3,}|~{3,})/.test(line)) return true;
+ if (isHorizontalRule(line)) return true;
+ if (line.startsWith('> ') || line === '>') return true;
+ if (/^ {0,9}[-*+] /.test(line)) return true;
+ if (/^ {0,9}\d+\. /.test(line)) return true;
+ if (line.includes('|')) return true;
+ return false;
+}
+
+function splitTableRow(line: string): string[] {
+ let start = 0;
+ let end = line.length;
+ if (line[0] === '|') {
+ start = 1;
+ while (start < end && line[start] === ' ') start++;
+ }
+ while (end > start && line[end - 1] === ' ') end--;
+ if (end > start && line[end - 1] === '|') end--;
+ return line.slice(start, end).split('|').map(segment => segment.trim());
+}
+
+function parseTable(lines: string[], lineIndex: number): {node: BlockNode; nextIndex: number} {
+ const headers: TableCellNode[] = splitTableRow(lines[lineIndex]).map(cell => ({children: parseInline(cell)}));
+ const alignments: TableAlignment[] = splitTableRow(lines[lineIndex + 1]).map(cell => {
+ const trimmed = cell.trim();
+ const leftAligned = trimmed.startsWith(':');
+ const rightAligned = trimmed.endsWith(':');
+ return leftAligned && rightAligned ? 'center' : rightAligned ? 'right' : leftAligned ? 'left' : null;
+ });
+ const rows: TableCellNode[][] = [];
+ let rowIndex = lineIndex + 2;
+ while (rowIndex < lines.length && lines[rowIndex].includes('|') && lines[rowIndex].trim() !== '') {
+ rows.push(splitTableRow(lines[rowIndex]).map(cell => ({children: parseInline(cell)})));
+ rowIndex++;
+ }
+ return {node: {type: 'table', headers, alignments, rows}, nextIndex: rowIndex};
+}
+
+function parseList(lines: string[], startIndex: number, ordered: boolean): {node: BlockNode; nextIndex: number} {
+ const items: ListItemNode[] = [];
+ const baseIndent = getIndent(lines[startIndex]);
+ const itemPattern = ordered
+ ? new RegExp(`^ {${baseIndent}}\\d+\\. `)
+ : new RegExp(`^ {${baseIndent}}[-*+] `);
+
+ const startMatch = ordered ? lines[startIndex].match(/^ *(\d+)\./) : null;
+ const start = startMatch ? parseInt(startMatch[1], 10) : undefined;
+
+ let index = startIndex;
+ while (index < lines.length && itemPattern.test(lines[index])) {
+ const content = ordered
+ ? lines[index].replace(/^ *\d+\. /, '')
+ : lines[index].replace(/^ *[-*+] /, '');
+
+ const taskMatch = content.match(/^\[([ xX])\] (.*)/);
+ let checked: boolean | undefined;
+ let itemText: string;
+ if (taskMatch) {
+ checked = taskMatch[1].toLowerCase() === 'x';
+ itemText = taskMatch[2];
+ } else {
+ itemText = content;
+ }
+
+ index++;
+
+ // Collect sub-content (nested items or continuation lines)
+ const subLines: string[] = [];
+ while (index < lines.length && lines[index].trim() !== '' && getIndent(lines[index]) > baseIndent) {
+ subLines.push(lines[index]);
+ index++;
+ }
+
+ if (subLines.length > 0) {
+ const minSubIndent = Math.min(...subLines.map(subLine => getIndent(subLine)));
+ const deindented = subLines.map(subLine => subLine.slice(minSubIndent));
+ itemText += '\n' + deindented.join('\n');
+ }
+
+ items.push({checked, children: parseMarkdown(itemText)});
+ }
+ return {node: {type: 'list', ordered, start, items}, nextIndex: index};
+}
+
+// ---------------------------------------------------------------------------
+// Main block parser
+// ---------------------------------------------------------------------------
+
+export function parseMarkdown(input: string): BlockNode[] {
+ const lines = input.split('\n');
+ const blocks: BlockNode[] = [];
+ let index = 0;
+
+ while (index < lines.length) {
+ const line = lines[index];
+ if (line.trim() === '') { index++; continue; }
+
+ // --- Fenced code block ---
+ const fenceMatch = line.match(/^(`{3,}|~{3,})(\w*)/);
+ if (fenceMatch) {
+ const fence = fenceMatch[1];
+ const language = fenceMatch[2] || 'plaintext';
+ const codeLines: string[] = [];
+ index++;
+ while (index < lines.length && !lines[index].startsWith(fence)) {
+ codeLines.push(lines[index]);
+ index++;
+ }
+ index++; // skip closing fence
+ blocks.push({type: 'codeblock', language, content: codeLines.join('\n')});
+ continue;
+ }
+
+ // --- Heading ---
+ const headingMatch = line.match(/^(#{1,6}) +(.*)/);
+ if (headingMatch) {
+ blocks.push({type: 'heading', level: headingMatch[1].length as 1 | 2 | 3 | 4 | 5 | 6, children: parseInline(headingMatch[2])});
+ index++;
+ continue;
+ }
+
+ // --- HR (must precede list check to handle `- - -`, `* * *`, `_ _ _`) ---
+ if (isHorizontalRule(line)) {
+ blocks.push({type: 'hr'});
+ index++;
+ continue;
+ }
+
+ // --- Standalone image ---
+ const imageMatch = line.match(/^!\[([^\]]*)\]\(([^)]+)\)/);
+ if (imageMatch && line.trim() === imageMatch[0]) {
+ blocks.push({type: 'image', alt: imageMatch[1], src: imageMatch[2]});
+ index++;
+ continue;
+ }
+
+ // --- Table (with or without leading pipe) ---
+ if (index + 1 < lines.length && line.includes('|') && isTableSeparator(lines[index + 1])) {
+ const tableResult = parseTable(lines, index);
+ blocks.push(tableResult.node);
+ index = tableResult.nextIndex;
+ continue;
+ }
+
+ // --- Blockquote ---
+ if (line.startsWith('> ') || line === '>') {
+ const quoteLines: string[] = [];
+ while (index < lines.length && (lines[index].startsWith('> ') || lines[index] === '>')) {
+ quoteLines.push(lines[index].replace(/^> ?/, ''));
+ index++;
+ }
+ blocks.push({type: 'blockquote', children: parseMarkdown(quoteLines.join('\n'))});
+ continue;
+ }
+
+ // --- Unordered list ---
+ if (/^ {0,9}[-*+] /.test(line)) {
+ const listResult = parseList(lines, index, false);
+ blocks.push(listResult.node);
+ index = listResult.nextIndex;
+ continue;
+ }
+
+ // --- Ordered list ---
+ if (/^ {0,9}\d+\. /.test(line)) {
+ const listResult = parseList(lines, index, true);
+ blocks.push(listResult.node);
+ index = listResult.nextIndex;
+ continue;
+ }
+
+ // --- Paragraph ---
+ const paraLines: string[] = [line];
+ index++;
+ while (index < lines.length && !isBlockStart(lines[index]) && lines[index].trim() !== '') {
+ paraLines.push(lines[index]);
+ index++;
+ }
+ blocks.push({type: 'paragraph', children: parseInline(paraLines.join('\n'))});
+ }
+ return blocks;
+}
+
+// ---------------------------------------------------------------------------
+// Incremental parsing
+// ---------------------------------------------------------------------------
+
+export interface IncrementalState {
+ prevInput: string;
+ settledText: string;
+ settledBlocks: BlockNode[];
+ settledUpTo: number;
+}
+
+export function createIncrementalState(): IncrementalState {
+ return {prevInput: '', settledText: '', settledBlocks: [], settledUpTo: 0};
+}
+
+/**
+ * Find the line-index of the last blank line that is NOT inside a fenced code
+ * block. Returns -1 when nothing is settled (unclosed fence or no blank line).
+ */
+function findSettledBoundary(lines: string[]): number {
+ let inFence = false;
+ let fenceMarker = '';
+ let lastBoundary = -1;
+
+ for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+ const line = lines[lineIndex];
+
+ // Fence open / close — match the specific marker character and length
+ const fenceMatch = line.match(/^(`{3,}|~{3,})/);
+ if (fenceMatch) {
+ if (!inFence) {
+ inFence = true;
+ fenceMarker = fenceMatch[1];
+ } else if (
+ fenceMatch[1][0] === fenceMarker[0] &&
+ fenceMatch[1].length >= fenceMarker.length
+ ) {
+ inFence = false;
+ fenceMarker = '';
+ }
+ }
+
+ if (!inFence && line.trim() === '' && lineIndex > 0) {
+ lastBoundary = lineIndex;
+ }
+ }
+
+ return inFence ? -1 : lastBoundary;
+}
+
+/**
+ * Strip trailing incomplete inline syntax that appears during streaming.
+ * Only affects the tail of the last line — safe to apply to the full string.
+ */
+export function trimStreamingArtifacts(input: 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);
+
+ // Scan backwards for unclosed syntax markers — no regex to avoid ReDoS
+ // Find the last unclosed [ (link start)
+ const lastBracket = tail.lastIndexOf('[');
+ if (lastBracket !== -1 && !tail.slice(lastBracket).includes('])')) {
+ tail = tail.slice(0, lastBracket);
+ }
+
+ // Find trailing unclosed backticks
+ let end = tail.length;
+ while (end > 0 && tail[end - 1] === '`') end--;
+ if (end < tail.length && end > 0) {
+ // There are trailing backticks — check if they opened inline code
+ const ticks = tail.length - end;
+ const opener = tail.lastIndexOf('`'.repeat(ticks), end - 1);
+ if (opener === -1) {
+ // Unclosed — trim from the backticks
+ tail = tail.slice(0, end);
+ }
+ }
+
+ // Find trailing unclosed bold/italic markers (*)
+ end = tail.length;
+ while (end > 0 && tail[end - 1] === '*') end--;
+ if (end < tail.length && end > 0) {
+ const stars = tail.length - end;
+ if (stars <= 3) tail = tail.slice(0, end);
+ }
+
+ // Find trailing unclosed strikethrough (~~)
+ if (tail.length >= 2 && tail.endsWith('~~')) {
+ tail = tail.slice(0, -2);
+ } else if (tail.endsWith('~')) {
+ // Single trailing ~ after content — might be start of ~~
+ const secondLast = tail.length - 2;
+ if (secondLast >= 0 && tail[secondLast] !== '~') {
+ tail = tail.slice(0, -1);
+ }
+ }
+
+ return prefix + tail;
+}
+
+export function parseMarkdownIncremental(
+ input: string,
+ state: IncrementalState,
+): BlockNode[] {
+ if (input === '') {
+ state.prevInput = '';
+ state.settledText = '';
+ state.settledBlocks = [];
+ state.settledUpTo = 0;
+ return [];
+ }
+
+ const lines = input.split('\n');
+ const boundary = findSettledBoundary(lines);
+
+ if (boundary < 0) {
+ // Inside an unclosed fence or no blank-line boundary — full re-parse
+ state.prevInput = input;
+ return parseMarkdown(input);
+ }
+
+ const settledText = lines.slice(0, boundary).join('\n');
+ const unsettledText = lines.slice(boundary).join('\n').trim();
+
+ let settledBlocks: BlockNode[];
+
+ if (settledText === state.settledText) {
+ // Settled portion unchanged — reuse cached blocks
+ settledBlocks = state.settledBlocks;
+ } else if (state.settledText.length > 0 && settledText.startsWith(state.settledText)) {
+ // Settled portion grew — parse only the new delta
+ const delta = settledText.slice(state.settledText.length);
+ const deltaBlocks = parseMarkdown(delta);
+ settledBlocks = [...state.settledBlocks, ...deltaBlocks];
+ } else {
+ // Content before the boundary changed — full re-parse of settled portion
+ settledBlocks = parseMarkdown(settledText);
+ }
+
+ const unsettledBlocks = unsettledText ? parseMarkdown(unsettledText) : [];
+
+ state.settledText = settledText;
+ state.settledBlocks = settledBlocks;
+ state.settledUpTo = boundary;
+ state.prevInput = input;
+
+ return [...settledBlocks, ...unsettledBlocks];
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 667b2daa15..af3117c877 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -25,6 +25,7 @@ export * from './Calendar';
export * from './Center';
export * from './CodeBlock';
export * from './CommandPalette';
+export * from './Markdown';
export * from './CheckboxInput';
export * from './CheckboxList';
export * from './Collapsible';