Skip to content

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

TypeScript

feat(markdown): streaming fade-in animation and syntax suppression (#1154)

Cindy Zhangd7741d1b338b
diff --git a/apps/storybook/stories/Markdown.stories.tsx b/apps/storybook/stories/Markdown.stories.tsx
index f35e177dfa..df7d7a2796 100644
--- a/apps/storybook/stories/Markdown.stories.tsx
+++ b/apps/storybook/stories/Markdown.stories.tsx
@@ -71,27 +71,81 @@ const SAMPLE_MD = [
'2. Second ordered item',
].join('\n');
-const AI_RESPONSE = [
- 'Here is how you fetch a user in TypeScript:',
+const STREAMING_RESPONSE = [
+ '## Setting Up a Design System',
+ '',
+ 'A design system is more than a component library — it\'s a **shared language** between design and engineering. Here\'s how to build one that scales.',
+ '',
+ '### 1. Start with Tokens',
+ '',
+ 'Design tokens are the atomic values that define your visual language:',
'',
'```typescript',
- 'const response = await fetch(`/api/users/${id}`);',
- 'const user: User = await response.json();',
+ 'const tokens = {',
+ ' color: {',
+ ' primary: \'#0066FF\',',
+ ' secondary: \'#6B7280\',',
+ ' success: \'#10B981\',',
+ ' danger: \'#EF4444\',',
+ ' },',
+ ' spacing: {',
+ ' xs: \'4px\',',
+ ' sm: \'8px\',',
+ ' md: \'16px\',',
+ ' lg: \'24px\',',
+ ' xl: \'32px\',',
+ ' },',
+ ' radius: {',
+ ' sm: \'4px\',',
+ ' md: \'8px\',',
+ ' lg: \'16px\',',
+ ' full: \'9999px\',',
+ ' },',
+ '};',
'```',
'',
- 'Key points:',
+ 'These tokens should be the *single source of truth* for every component.',
+ '',
+ '### 2. Component Architecture',
+ '',
+ 'Good components follow these principles:',
+ '',
+ '- **Composable** — small pieces that combine into complex UIs',
+ '- **Accessible** — keyboard navigation and screen reader support built-in',
+ '- **Themeable** — visual customization without forking',
+ '- **Documented** — usage examples, props tables, and do/don\'t guidelines',
+ '',
+ '> The best design systems are *opinionated enough* to ensure consistency, but *flexible enough* to handle edge cases gracefully.',
+ '',
+ '### 3. Adoption Strategy',
'',
- '- Always check `response.ok` before parsing',
- '- Use `AbortController` for cancellation',
- '- Consider a `useUser` hook for React apps',
+ 'Rolling out a design system requires planning:',
'',
- '| Method | Status | Use Case |',
- '|--------|--------|----------|',
- '| GET | 200 | Fetch resource |',
- '| POST | 201 | Create resource |',
- '| PUT | 200 | Update resource |',
+ '| Phase | Duration | Goal |',
+ '|:------|:--------:|:-----|',
+ '| Alpha | 4 weeks | Core components, internal dogfooding |',
+ '| Beta | 8 weeks | Expanded component set, 2-3 pilot teams |',
+ '| GA | Ongoing | Full adoption, migration support |',
+ '',
+ 'Key metrics to track:',
+ '',
+ '1. **Component coverage** — what percentage of UI patterns are served',
+ '2. **Adoption rate** — teams actively using the system',
+ '3. **Contribution rate** — external PRs and feature requests',
+ '4. **Consistency score** — visual audits across products',
+ '',
+ '### 4. Maintenance',
+ '',
+ 'A design system is a *living product*. Plan for:',
+ '',
+ '- [x] Automated visual regression testing',
+ '- [x] Semantic versioning with changelogs',
+ '- [ ] Breaking change codemods',
+ '- [ ] Cross-platform support (web, mobile, native)',
+ '',
+ '---',
'',
- '> **Tip**: Wrap fetch calls in a try/catch for error handling.',
+ 'The most important thing? **Ship early, iterate often.** A design system that exists and is used beats a perfect one that\'s still in planning.',
].join('\n');
export const Default: Story = {
@@ -110,7 +164,7 @@ export const Compact: Story = {
export const AIResponse: Story = {
name: 'AI Response',
args: {
- children: AI_RESPONSE,
+ children: STREAMING_RESPONSE,
density: 'compact',
headingLevelStart: 3,
},
@@ -142,7 +196,7 @@ export const TableFocused: Story = {
export const Streaming: Story = {
render: () => {
- const text = AI_RESPONSE;
+ const text = STREAMING_RESPONSE;
const [charIndex, setCharIndex] = useState(0);
const [isStreaming, setIsStreaming] = useState(true);
const [key, setKey] = useState(0);
diff --git a/packages/core/src/Markdown/XDSMarkdown.tsx b/packages/core/src/Markdown/XDSMarkdown.tsx
index fe2c11d0ec..54db46a953 100644
--- a/packages/core/src/Markdown/XDSMarkdown.tsx
+++ b/packages/core/src/Markdown/XDSMarkdown.tsx
@@ -19,6 +19,8 @@ import {
typographyVars,
fontWeightVars,
borderVars,
+ durationVars,
+ easeVars,
} from '../theme/tokens.stylex';
import {XDSCodeBlock, XDSCode} from '../CodeBlock';
import {XDSCheckboxList} from '../CheckboxList/XDSCheckboxList';
@@ -26,6 +28,7 @@ import {XDSCheckboxListItem} from '../CheckboxList/XDSCheckboxListItem';
import {XDSList} from '../List/XDSList';
import {XDSListItem} from '../List/XDSListItem';
import {xdsClassName, mergeProps} from '../utils';
+import {useXDSStreamingText} from '../hooks/useXDSStreamingText';
import {
parseMarkdown,
parseMarkdownIncremental,
@@ -250,6 +253,99 @@ const styles = stylex.create({
},
});
+// ---------------------------------------------------------------------------
+// Streaming fade-in animation
+// ---------------------------------------------------------------------------
+
+const streamingStyles = stylex.create({
+ fadeIn: {
+ // Resting state is fully visible — safe fallback if animation doesn't fire.
+ // @starting-style declares the entry state (opacity: 0) so the browser
+ // transitions from invisible to visible when the element first mounts.
+ opacity: 1,
+ transitionProperty: 'opacity',
+ transitionDuration: durationVars['--duration-fast-max'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ '@starting-style': {
+ opacity: 0,
+ },
+ },
+});
+
+/**
+ * Mutable cursor threaded through the render tree during streaming.
+ * Tracks how many text characters we've visited so far. When `offset`
+ * crosses `boundary`, newly rendered content is wrapped in a fade-in span.
+ */
+interface StreamingCursor {
+ /** Characters visited so far in this render pass */
+ offset: number;
+ /** Character position where "new" content begins */
+ boundary: number;
+ /** Whether streaming fade is active */
+ active: boolean;
+}
+
+/**
+ * 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 {
+ let len = 0;
+ for (const node of nodes) {
+ switch (node.type) {
+ case 'text':
+ len += node.content.length;
+ break;
+ case 'code':
+ len += node.content.length;
+ break;
+ case 'bold':
+ case 'italic':
+ case 'strikethrough':
+ case 'link':
+ len += countInlineTextLength(node.children);
+ break;
+ case 'break':
+ len += 1;
+ break;
+ }
+ }
+ return len;
+}
+
+/**
+ * Count total text characters in a block node tree.
+ */
+function countBlockTextLength(nodes: BlockNode[]): number {
+ let len = 0;
+ for (const node of nodes) {
+ switch (node.type) {
+ case 'heading':
+ case 'paragraph':
+ len += countInlineTextLength(node.children);
+ break;
+ case 'codeblock':
+ len += node.content.length;
+ break;
+ case 'blockquote':
+ len += countBlockTextLength(node.children);
+ break;
+ case 'list':
+ for (const item of node.items) {
+ len += countBlockTextLength(item.children);
+ }
+ break;
+ case 'table':
+ for (const h of node.headers) len += countInlineTextLength(h.children);
+ for (const row of node.rows)
+ for (const cell of row) len += countInlineTextLength(cell.children);
+ break;
+ }
+ }
+ return len;
+}
+
const headingStyles = {
1: styles.h1,
2: styles.h2,
@@ -276,41 +372,99 @@ function sanitizeUrl(url: string): string | null {
// Inline renderer
// ---------------------------------------------------------------------------
+/**
+ * Wrap a text string with a fade-in span for the portion that is "new".
+ * If the entire string is old, returns it as-is. If partially new, splits
+ * into [old, <span fade>new</span>]. If entirely new, wraps the whole thing.
+ */
+function wrapTextWithFade(
+ content: string,
+ cursor: StreamingCursor,
+ key: string | number,
+): React.ReactNode {
+ const startOffset = cursor.offset;
+ cursor.offset += content.length;
+
+ if (!cursor.active) return content;
+ if (startOffset >= cursor.boundary) {
+ // Entirely new text
+ return (
+ <span
+ key={`fade-${key}-${startOffset}`}
+ {...stylex.props(streamingStyles.fadeIn)}>
+ {content}
+ </span>
+ );
+ }
+ if (startOffset + content.length <= cursor.boundary) {
+ // Entirely old text
+ return content;
+ }
+ // Split: some old, some new
+ const splitAt = cursor.boundary - startOffset;
+ return (
+ <>
+ {content.slice(0, splitAt)}
+ <span
+ key={`fade-${key}-${cursor.boundary}`}
+ {...stylex.props(streamingStyles.fadeIn)}>
+ {content.slice(splitAt)}
+ </span>
+ </>
+ );
+}
+
function renderInline(
node: InlineNode,
index: number,
- onLinkClick?: XDSMarkdownProps['onLinkClick'],
+ onLinkClick: XDSMarkdownProps['onLinkClick'] | undefined,
+ cursor: StreamingCursor,
): React.ReactNode {
switch (node.type) {
case 'text':
- return node.content;
+ return wrapTextWithFade(node.content, cursor, index);
case 'bold':
return (
<strong key={index} {...stylex.props(styles.bold)}>
- {node.children.map((c, i) => renderInline(c, i, onLinkClick))}
+ {node.children.map((c, i) => renderInline(c, i, onLinkClick, cursor))}
</strong>
);
case 'italic':
return (
<em key={index}>
- {node.children.map((c, i) => renderInline(c, i, onLinkClick))}
+ {node.children.map((c, i) => renderInline(c, i, onLinkClick, cursor))}
</em>
);
case 'strikethrough':
return (
<del key={index} {...stylex.props(styles.strikethrough)}>
- {node.children.map((c, i) => renderInline(c, i, onLinkClick))}
+ {node.children.map((c, i) => renderInline(c, i, onLinkClick, cursor))}
</del>
);
- case 'code':
+ case 'code': {
+ // Track code content length for cursor but don't split inside code
+ const startOffset = cursor.offset;
+ cursor.offset += node.content.length;
+ if (cursor.active && startOffset >= cursor.boundary) {
+ return (
+ <span
+ key={`fade-code-${index}-${startOffset}`}
+ {...stylex.props(streamingStyles.fadeIn)}>
+ <XDSCode>{node.content}</XDSCode>
+ </span>
+ );
+ }
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))}
+ {node.children.map((c, i) =>
+ renderInline(c, i, onLinkClick, cursor),
+ )}
</span>
);
}
@@ -332,7 +486,7 @@ function renderInline(
? {target: '_blank', rel: 'noopener noreferrer'}
: {})}
{...stylex.props(styles.link)}>
- {node.children.map((c, i) => renderInline(c, i, onLinkClick))}
+ {node.children.map((c, i) => renderInline(c, i, onLinkClick, cursor))}
</a>
);
}
@@ -349,6 +503,7 @@ function renderInline(
);
}
case 'break':
+ cursor.offset += 1;
return <br key={index} />;
}
}
@@ -404,7 +559,8 @@ function renderBlock(
blockCount: number,
density: 'default' | 'compact',
headingLevelStart: 1 | 2 | 3 | 4 | 5 | 6,
- onLinkClick?: XDSMarkdownProps['onLinkClick'],
+ onLinkClick: XDSMarkdownProps['onLinkClick'] | undefined,
+ cursor: StreamingCursor,
): React.ReactNode {
const spacing = getElementSpacing(node, density);
const isFirst = index === 0;
@@ -430,7 +586,7 @@ function renderBlock(
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
)}>
- {node.children.map((c, i) => renderInline(c, i, onLinkClick))}
+ {node.children.map((c, i) => renderInline(c, i, onLinkClick, cursor))}
</Tag>
);
}
@@ -443,10 +599,12 @@ function renderBlock(
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
)}>
- {node.children.map((c, i) => renderInline(c, i, onLinkClick))}
+ {node.children.map((c, i) => renderInline(c, i, onLinkClick, cursor))}
</p>
);
- case 'codeblock':
+ case 'codeblock': {
+ // Track codeblock content in cursor for accurate character counting
+ cursor.offset += node.content.length;
return (
<div
key={index}
@@ -458,6 +616,7 @@ function renderBlock(
<XDSCodeBlock code={node.content} language={node.language} />
</div>
);
+ }
case 'blockquote':
return (
<blockquote
@@ -476,6 +635,7 @@ function renderBlock(
density,
headingLevelStart,
onLinkClick,
+ cursor,
),
)}
</blockquote>
@@ -512,10 +672,13 @@ function renderBlock(
item.children.length === 1 &&
firstChild?.type === 'paragraph';
+ const itemIsNew =
+ cursor.active && cursor.offset >= cursor.boundary;
+
const label = isInline ? (
<>
{firstChild.children.map((c, j) =>
- renderInline(c, j, onLinkClick),
+ renderInline(c, j, onLinkClick, cursor),
)}
</>
) : (
@@ -528,18 +691,31 @@ function renderBlock(
density,
headingLevelStart,
onLinkClick,
+ cursor,
),
)}
</>
);
- return (
+ const checkboxItem = (
<XDSCheckboxListItem
key={i}
value={`task-${i}`}
label={label}
/>
);
+
+ if (itemIsNew) {
+ return (
+ <span
+ key={`fade-task-${i}`}
+ {...stylex.props(streamingStyles.fadeIn)}>
+ {checkboxItem}
+ </span>
+ );
+ }
+
+ return checkboxItem;
})}
</XDSCheckboxList>
</div>
@@ -562,10 +738,16 @@ function renderBlock(
const isInline =
item.children.length === 1 && firstChild?.type === 'paragraph';
+ // Check if this entire list item is "new" — if so, fade the
+ // whole item as a block instead of fading individual text spans.
+ const itemTextLen = countBlockTextLength(item.children);
+ const itemIsNew =
+ cursor.active && cursor.offset >= cursor.boundary;
+
const label = isInline ? (
<>
{firstChild.children.map((c, j) =>
- renderInline(c, j, onLinkClick),
+ renderInline(c, j, onLinkClick, cursor),
)}
</>
) : (
@@ -578,11 +760,22 @@ function renderBlock(
density,
headingLevelStart,
onLinkClick,
+ cursor,
),
)}
</>
);
+ if (itemIsNew) {
+ return (
+ <span
+ key={`fade-li-${i}-${cursor.offset - itemTextLen}`}
+ {...stylex.props(streamingStyles.fadeIn)}>
+ <XDSListItem label={label} />
+ </span>
+ );
+ }
+
return <XDSListItem key={i} label={label} />;
})}
</XDSList>
@@ -615,28 +808,37 @@ function renderBlock(
styles.th,
alignStyle(node.alignments[i]),
)}>
- {h.children.map((c, j) => renderInline(c, j, onLinkClick))}
+ {h.children.map((c, j) =>
+ renderInline(c, j, onLinkClick, cursor),
+ )}
</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>
- ))}
+ {node.rows.map((row, i) => {
+ const rowIsNew =
+ cursor.active && cursor.offset >= cursor.boundary;
+ const cells = row.map((cell, j) => (
+ <td
+ key={j}
+ {...stylex.props(
+ styles.td,
+ alignStyle(node.alignments[j]),
+ )}>
+ {cell.children.map((c, k) =>
+ renderInline(c, k, onLinkClick, cursor),
+ )}
+ </td>
+ ));
+ return (
+ <tr
+ key={rowIsNew ? `fade-row-${i}` : i}
+ {...(rowIsNew ? stylex.props(streamingStyles.fadeIn) : {})}>
+ {cells}
+ </tr>
+ );
+ })}
</tbody>
</table>
</div>
@@ -700,21 +902,37 @@ export function XDSMarkdown({
style,
'data-testid': testId,
}: XDSMarkdownProps): React.ReactElement {
+ // Smooth bursty streamed chunks into a steady character-by-character reveal.
+ // When not streaming, the hook returns children unchanged (no-op).
+ const smoothedText = useXDSStreamingText(children, isStreaming);
+
const incrementalState = useRef<IncrementalState>(createIncrementalState());
+ // Track how much text content was rendered on the previous pass.
+ // Everything beyond this boundary is "new" and gets the fade-in animation.
+ const prevTextLenRef = useRef(0);
const blocks = useMemo(() => {
if (isStreaming) {
- if (children === '') {
+ if (smoothedText === '') {
incrementalState.current = createIncrementalState();
+ prevTextLenRef.current = 0;
return [];
}
- const input = trimStreamingArtifacts(children);
+ const input = trimStreamingArtifacts(smoothedText);
return parseMarkdownIncremental(input, incrementalState.current);
}
return parseMarkdown(children);
- }, [children, isStreaming]);
+ }, [smoothedText, children, isStreaming]);
- return (
+ // Build the streaming cursor for this render pass.
+ // The boundary is where "old" text ends and "new" text begins.
+ const cursor: StreamingCursor = {
+ offset: 0,
+ boundary: prevTextLenRef.current,
+ active: isStreaming,
+ };
+
+ const rendered = (
<div
role="document"
ref={ref}
@@ -733,10 +951,17 @@ export function XDSMarkdown({
density,
headingLevelStart,
onLinkClick,
+ cursor,
),
)}
</div>
);
+
+ // After rendering, update the boundary for the next pass.
+ // cursor.offset now holds the total character count of the rendered tree.
+ prevTextLenRef.current = cursor.offset;
+
+ return rendered;
}
XDSMarkdown.displayName = 'XDSMarkdown';
diff --git a/packages/core/src/Markdown/incremental.test.ts b/packages/core/src/Markdown/incremental.test.ts
index 8b9d6b2402..cca4cd2b12 100644
--- a/packages/core/src/Markdown/incremental.test.ts
+++ b/packages/core/src/Markdown/incremental.test.ts
@@ -1,5 +1,10 @@
import {describe, it, expect} from 'vitest';
-import {parseMarkdown, parseMarkdownIncremental, createIncrementalState} from './parser';
+import {
+ parseMarkdown,
+ parseMarkdownIncremental,
+ createIncrementalState,
+ trimStreamingArtifacts,
+} from './parser';
import type {BlockNode} from './parser';
function simulateStreaming(fullText: string, chunkSize = 10) {
@@ -36,7 +41,8 @@ describe('parseMarkdownIncremental', () => {
it('code fences prevent false settlement', () => {
const state = createIncrementalState();
- const input = '```javascript\nconst x = 1;\n\n// still in code\nconsole.log(x);';
+ 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);
@@ -93,7 +99,8 @@ describe('parseMarkdownIncremental', () => {
it('unclosed fence keeps everything unsettled', () => {
const state = createIncrementalState();
- const input = '# Title\n\n```python\ndef foo():\n pass\n\n# still inside fence';
+ const input =
+ '# Title\n\n```python\ndef foo():\n pass\n\n# still inside fence';
parseMarkdownIncremental(input, state);
expect(state.settledBlocks).toHaveLength(0);
});
@@ -146,7 +153,10 @@ describe('parseMarkdownIncremental', () => {
const cachedBlocks = state.settledBlocks;
// Second call: only unsettled tail changed
- parseMarkdownIncremental('# Title\n\nParagraph\n\nStill typing more', state);
+ 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);
});
@@ -157,3 +167,359 @@ describe('parseMarkdownIncremental', () => {
expect(state.settledText).toBe('# Hello');
});
});
+
+describe('trimStreamingArtifacts', () => {
+ it('trims trailing unclosed bold markers', () => {
+ expect(trimStreamingArtifacts('Hello **')).toBe('Hello ');
+ expect(trimStreamingArtifacts('Hello *')).toBe('Hello ');
+ expect(trimStreamingArtifacts('Hello ***')).toBe('Hello ');
+ });
+
+ it('keeps unclosed mid-line bold as plain text', () => {
+ // Mid-line ** with content after → kept as-is. The parser renders
+ // it as plain text, which is better than hiding content.
+ expect(trimStreamingArtifacts('Hello **bold')).toBe('Hello **bold');
+ expect(trimStreamingArtifacts('Hello **bo')).toBe('Hello **bo');
+ // Trailing ** with no content → still trimmed
+ expect(trimStreamingArtifacts('Hello **')).toBe('Hello ');
+ });
+
+ it('keeps unclosed mid-line italic as plain text', () => {
+ expect(trimStreamingArtifacts('Hello *ital')).toBe('Hello *ital');
+ expect(trimStreamingArtifacts('Hello *')).toBe('Hello ');
+ });
+
+ it('preserves complete bold+italic in same line', () => {
+ expect(trimStreamingArtifacts('Hello **bold** and *italic*')).toBe(
+ 'Hello **bold** and *italic*',
+ );
+ });
+
+ it('keeps unclosed bold after closed bold as plain text', () => {
+ expect(trimStreamingArtifacts('Hello **done** and **open')).toBe(
+ 'Hello **done** and **open',
+ );
+ });
+
+ it('preserves closed bold markers', () => {
+ expect(trimStreamingArtifacts('Hello **world**')).toBe('Hello **world**');
+ });
+
+ it('trims trailing unclosed backticks', () => {
+ expect(trimStreamingArtifacts('Hello `')).toBe('Hello ');
+ expect(trimStreamingArtifacts('Hello ```')).toBe('Hello ');
+ });
+
+ it('preserves closed inline code', () => {
+ expect(trimStreamingArtifacts('Hello `code`')).toBe('Hello `code`');
+ });
+
+ it('trims trailing unclosed strikethrough', () => {
+ expect(trimStreamingArtifacts('Hello ~~')).toBe('Hello ');
+ expect(trimStreamingArtifacts('Hello ~')).toBe('Hello ');
+ });
+
+ it('trims unclosed mid-line strikethrough', () => {
+ expect(trimStreamingArtifacts('Hello ~~struck')).toBe('Hello ');
+ expect(trimStreamingArtifacts('Hello ~~s')).toBe('Hello ');
+ });
+
+ it('preserves closed strikethrough', () => {
+ expect(trimStreamingArtifacts('Hello ~~struck~~ more')).toBe(
+ 'Hello ~~struck~~ more',
+ );
+ });
+
+ it('trims unclosed link text', () => {
+ expect(trimStreamingArtifacts('Hello [link text')).toBe('Hello ');
+ expect(trimStreamingArtifacts('Hello [link')).toBe('Hello ');
+ });
+
+ it('preserves closed links', () => {
+ expect(trimStreamingArtifacts('Hello [text](url)')).toBe(
+ 'Hello [text](url)',
+ );
+ });
+
+ it('trims unclosed image alt', () => {
+ expect(trimStreamingArtifacts('Hello ![alt')).toBe('Hello ');
+ });
+
+ it('operates only on the last line', () => {
+ expect(trimStreamingArtifacts('Line 1\nHello **')).toBe('Line 1\nHello ');
+ expect(trimStreamingArtifacts('Line 1\n**bold** done\nHello *')).toBe(
+ 'Line 1\n**bold** done\nHello ',
+ );
+ });
+
+ it('handles empty input', () => {
+ expect(trimStreamingArtifacts('')).toBe('');
+ });
+
+ it('handles input with no artifacts', () => {
+ expect(trimStreamingArtifacts('Just plain text')).toBe('Just plain text');
+ });
+});
+
+describe('streaming structural suppression', () => {
+ it('suppresses bare list markers in unsettled zone', () => {
+ const state = createIncrementalState();
+ // Paragraph followed by incomplete list item
+ const input = 'Some text\n\n- ';
+ const blocks = parseMarkdownIncremental(input, state);
+ // Should NOT produce a list with an empty item
+ const hasList = blocks.some(b => b.type === 'list');
+ expect(hasList).toBe(false);
+ });
+
+ it('renders list items once text arrives', () => {
+ const state = createIncrementalState();
+ const input = 'Some text\n\n- First item';
+ const blocks = parseMarkdownIncremental(input, state);
+ const list = blocks.find(b => b.type === 'list');
+ expect(list).toBeDefined();
+ if (list?.type === 'list') {
+ expect(list.items).toHaveLength(1);
+ }
+ });
+
+ it('suppresses incomplete table header without separator', () => {
+ const state = createIncrementalState();
+ // Table header without separator row
+ const input = 'Intro\n\n| Col1 | Col2 |';
+ const blocks = parseMarkdownIncremental(input, state);
+ const hasTable = blocks.some(b => b.type === 'table');
+ expect(hasTable).toBe(false);
+ });
+
+ it('suppresses table separator without data rows', () => {
+ const state = createIncrementalState();
+ const input = 'Intro\n\n| Col1 | Col2 |\n| --- | --- |';
+ const blocks = parseMarkdownIncremental(input, state);
+ // Should suppress: header + separator but no data rows yet
+ // Actually this is a valid table with 0 data rows — parser may render it.
+ // The key test is that we don't show partial pipe syntax.
+ });
+
+ it('renders complete table once rows arrive', () => {
+ const state = createIncrementalState();
+ const input = 'Intro\n\n| Col1 | Col2 |\n| --- | --- |\n| a | b |';
+ const blocks = parseMarkdownIncremental(input, state);
+ const table = blocks.find(b => b.type === 'table');
+ expect(table).toBeDefined();
+ if (table?.type === 'table') {
+ expect(table.rows).toHaveLength(1);
+ }
+ });
+
+ it('suppresses ordered list marker without content', () => {
+ const state = createIncrementalState();
+ const input = 'Intro\n\n1. ';
+ const blocks = parseMarkdownIncremental(input, state);
+ const hasList = blocks.some(b => b.type === 'list');
+ expect(hasList).toBe(false);
+ });
+
+ it('no suppression for complete list items', () => {
+ const state = createIncrementalState();
+ const input = 'Intro\n\n- Complete item\n- Another item';
+ const blocks = parseMarkdownIncremental(input, state);
+ const list = blocks.find(b => b.type === 'list');
+ expect(list).toBeDefined();
+ if (list?.type === 'list') {
+ expect(list.items).toHaveLength(2);
+ }
+ });
+
+ it('character-by-character streaming never produces bare list markers', () => {
+ const fullText = 'Hello world\n\n- Item one\n- Item two\n- Item three';
+ const state = createIncrementalState();
+ for (let i = 1; i <= fullText.length; i++) {
+ const blocks = parseMarkdownIncremental(fullText.slice(0, i), state);
+ for (const block of blocks) {
+ if (block.type === 'list') {
+ for (const item of block.items) {
+ // Every rendered list item should have non-empty content
+ const firstChild = item.children[0];
+ if (firstChild?.type === 'paragraph') {
+ const textContent = firstChild.children
+ .map(c => (c.type === 'text' ? c.content : ''))
+ .join('')
+ .trim();
+ expect(textContent.length).toBeGreaterThan(0);
+ }
+ }
+ }
+ }
+ }
+ });
+});
+
+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 {
+ let text = '';
+ for (const block of blocks) {
+ switch (block.type) {
+ case 'heading':
+ case 'paragraph':
+ text += extractInlineText(block.children);
+ break;
+ case 'codeblock':
+ text += block.content;
+ break;
+ case 'blockquote':
+ text += extractVisibleText(block.children);
+ break;
+ case 'list':
+ for (const item of block.items) {
+ text += extractVisibleText(item.children);
+ }
+ break;
+ case 'table':
+ for (const h of block.headers) text += extractInlineText(h.children);
+ for (const row of block.rows)
+ for (const cell of row) text += extractInlineText(cell.children);
+ break;
+ }
+ }
+ return text;
+ }
+
+ function extractInlineText(nodes: import('./parser').InlineNode[]): string {
+ let text = '';
+ for (const node of nodes) {
+ switch (node.type) {
+ case 'text':
+ text += node.content;
+ break;
+ case 'code':
+ text += node.content;
+ break;
+ case 'bold':
+ case 'italic':
+ case 'strikethrough':
+ case 'link':
+ text += extractInlineText(node.children);
+ break;
+ case 'image':
+ text += node.alt;
+ break;
+ case 'break':
+ text += '\n';
+ break;
+ }
+ }
+ return text;
+ }
+
+ function streamCharByChar(fullText: string): {snapshots: BlockNode[][]; visibleTexts: string[]} {
+ const state = createIncrementalState();
+ const snapshots: BlockNode[][] = [];
+ const visibleTexts: string[] = [];
+ for (let i = 1; i <= fullText.length; i++) {
+ const trimmed = trimStreamingArtifacts(fullText.slice(0, i));
+ const blocks = parseMarkdownIncremental(trimmed, state);
+ snapshots.push(blocks);
+ visibleTexts.push(extractVisibleText(blocks));
+ }
+ return {snapshots, visibleTexts};
+ }
+
+ it('bold text appears progressively during streaming', () => {
+ const text = 'Hello **bold text** and more';
+ const {visibleTexts} = streamCharByChar(text);
+ // Content should never completely disappear — we should never hide
+ // 20+ chars of content just because of unclosed markers
+ const nonEmpty = visibleTexts.filter(t => t.length > 0);
+ for (const visible of nonEmpty) {
+ // At minimum "Hello" should always be visible once it appears
+ if (visible.length >= 5) {
+ expect(visible.startsWith('Hello')).toBe(true);
+ }
+ }
+ // Text may briefly shrink when ** becomes formatting (markers removed
+ // from visible text) — that's expected and correct.
+ // Final result should have the full text (without raw markers)
+ expect(visibleTexts[visibleTexts.length - 1]).toBe('Hello bold text and more');
+ });
+
+ it('never shows raw * during italic streaming', () => {
+ const text = 'Hello *italic text* and more';
+ const {visibleTexts} = streamCharByChar(text);
+ for (const visible of visibleTexts) {
+ // A lone * that's not part of a word is raw syntax
+ expect(visible).not.toMatch(/(?:^|\s)\*(?:\s|$)/);
+ }
+ });
+
+ it('never shows raw ~~ during strikethrough streaming', () => {
+ const text = 'Hello ~~struck~~ and more';
+ const {visibleTexts} = streamCharByChar(text);
+ for (const visible of visibleTexts) {
+ expect(visible).not.toContain('~~');
+ }
+ });
+
+ it('never shows raw [ during link streaming', () => {
+ const text = 'Visit [our site](https://example.com) for info';
+ const {visibleTexts} = streamCharByChar(text);
+ for (const visible of visibleTexts) {
+ expect(visible).not.toContain('[');
+ expect(visible).not.toContain('](');
+ }
+ });
+
+ it('never shows raw ![ during image streaming', () => {
+ const text = 'See ![alt text](https://img.png) here';
+ const {visibleTexts} = streamCharByChar(text);
+ for (const visible of visibleTexts) {
+ expect(visible).not.toContain('![');
+ }
+ });
+
+ it('table rows render incrementally after header established', () => {
+ const text = '| A | B |\n| --- | --- |\n| r1a | r1b |\n| r2a | r2b |\n| r3a | r3b |';
+ const state = createIncrementalState();
+ let maxRows = 0;
+ // Stream by line to see rows appear incrementally
+ const lines = text.split('\n');
+ for (let lineCount = 1; lineCount <= lines.length; lineCount++) {
+ const input = lines.slice(0, lineCount).join('\n');
+ const trimmed = trimStreamingArtifacts(input);
+ const blocks = parseMarkdownIncremental(trimmed, state);
+ const table = blocks.find(b => b.type === 'table');
+ if (table?.type === 'table') {
+ maxRows = Math.max(maxRows, table.rows.length);
+ }
+ }
+ // Should have seen rows accumulate, not all at once
+ expect(maxRows).toBe(3);
+ });
+
+ it('complex mixed content char-by-char never shows raw syntax', () => {
+ const text = [
+ '## Heading',
+ '',
+ 'A paragraph with **bold**, *italic*, and `code`.',
+ '',
+ '- List item **one**',
+ '- List item [two](http://two.com)',
+ '- List item ~~three~~',
+ '',
+ '| Col | Val |',
+ '| --- | --- |',
+ '| **a** | *b* |',
+ ].join('\n');
+
+ const {visibleTexts} = streamCharByChar(text);
+ for (const visible of visibleTexts) {
+ // Links and images should never show raw syntax
+ expect(visible).not.toContain('](');
+ expect(visible).not.toContain('![');
+ }
+ });
+});
diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.ts
index 0be02ae5bc..375b167499 100644
--- a/packages/core/src/Markdown/parser.ts
+++ b/packages/core/src/Markdown/parser.ts
@@ -25,7 +25,12 @@ export type BlockNode =
| {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: 'table';
+ headers: TableCellNode[];
+ alignments: TableAlignment[];
+ rows: TableCellNode[][];
+ }
| {type: 'hr'}
| {type: 'image'; src: string; alt: string};
@@ -89,7 +94,11 @@ export function parseInline(text: string): InlineNode[] {
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)});
+ nodes.push({
+ type: 'image',
+ src: text.slice(altClose + 2, srcClose),
+ alt: text.slice(i + 2, altClose),
+ });
i = srcClose + 1;
continue;
}
@@ -102,7 +111,11 @@ export function parseInline(text: string): InlineNode[] {
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))});
+ nodes.push({
+ type: 'link',
+ href: text.slice(textClose + 2, urlClose),
+ children: parseInline(text.slice(i + 1, textClose)),
+ });
i = urlClose + 1;
continue;
}
@@ -120,8 +133,19 @@ export function parseInline(text: string): InlineNode[] {
// 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))}]});
+ 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;
}
@@ -139,8 +163,14 @@ export function parseInline(text: string): InlineNode[] {
// 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))});
+ if (
+ closeIndex !== -1 &&
+ (!isUnderscore || !isWordChar(text[closeIndex + 2]))
+ ) {
+ nodes.push({
+ type: 'bold',
+ children: parseInline(text.slice(i + 2, closeIndex)),
+ });
i = closeIndex + 2;
continue;
}
@@ -151,7 +181,10 @@ export function parseInline(text: string): InlineNode[] {
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))});
+ nodes.push({
+ type: 'strikethrough',
+ children: parseInline(text.slice(i + 2, closeIndex)),
+ });
i = closeIndex + 2;
continue;
}
@@ -164,8 +197,15 @@ export function parseInline(text: string): InlineNode[] {
// 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))});
+ 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;
}
@@ -258,27 +298,58 @@ function splitTableRow(line: string): string[] {
}
while (end > start && line[end - 1] === ' ') end--;
if (end > start && line[end - 1] === '|') end--;
- return line.slice(start, end).split('|').map(segment => segment.trim());
+ 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;
- });
+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)})));
+ 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};
+ return {
+ node: {type: 'table', headers, alignments, rows},
+ nextIndex: rowIndex,
+ };
}
-function parseList(lines: string[], startIndex: number, ordered: boolean): {node: BlockNode; nextIndex: number} {
+function parseList(
+ lines: string[],
+ startIndex: number,
+ ordered: boolean,
+): {node: BlockNode; nextIndex: number} {
const items: ListItemNode[] = [];
const baseIndent = getIndent(lines[startIndex]);
const itemPattern = ordered
@@ -308,13 +379,19 @@ function parseList(lines: string[], startIndex: number, ordered: boolean): {node
// Collect sub-content (nested items or continuation lines)
const subLines: string[] = [];
- while (index < lines.length && lines[index].trim() !== '' && getIndent(lines[index]) > baseIndent) {
+ 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 minSubIndent = Math.min(
+ ...subLines.map(subLine => getIndent(subLine)),
+ );
const deindented = subLines.map(subLine => subLine.slice(minSubIndent));
itemText += '\n' + deindented.join('\n');
}
@@ -335,7 +412,10 @@ export function parseMarkdown(input: string): BlockNode[] {
while (index < lines.length) {
const line = lines[index];
- if (line.trim() === '') { index++; continue; }
+ if (line.trim() === '') {
+ index++;
+ continue;
+ }
// --- Fenced code block ---
const fenceMatch = line.match(/^(`{3,}|~{3,})(\w*)/);
@@ -356,7 +436,11 @@ export function parseMarkdown(input: string): BlockNode[] {
// --- 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])});
+ blocks.push({
+ type: 'heading',
+ level: headingMatch[1].length as 1 | 2 | 3 | 4 | 5 | 6,
+ children: parseInline(headingMatch[2]),
+ });
index++;
continue;
}
@@ -377,7 +461,11 @@ export function parseMarkdown(input: string): BlockNode[] {
}
// --- Table (with or without leading pipe) ---
- if (index + 1 < lines.length && line.includes('|') && isTableSeparator(lines[index + 1])) {
+ if (
+ index + 1 < lines.length &&
+ line.includes('|') &&
+ isTableSeparator(lines[index + 1])
+ ) {
const tableResult = parseTable(lines, index);
blocks.push(tableResult.node);
index = tableResult.nextIndex;
@@ -387,11 +475,17 @@ export function parseMarkdown(input: string): BlockNode[] {
// --- Blockquote ---
if (line.startsWith('> ') || line === '>') {
const quoteLines: string[] = [];
- while (index < lines.length && (lines[index].startsWith('> ') || lines[index] === '>')) {
+ while (
+ index < lines.length &&
+ (lines[index].startsWith('> ') || lines[index] === '>')
+ ) {
quoteLines.push(lines[index].replace(/^> ?/, ''));
index++;
}
- blocks.push({type: 'blockquote', children: parseMarkdown(quoteLines.join('\n'))});
+ blocks.push({
+ type: 'blockquote',
+ children: parseMarkdown(quoteLines.join('\n')),
+ });
continue;
}
@@ -414,11 +508,18 @@ export function parseMarkdown(input: string): BlockNode[] {
// --- Paragraph ---
const paraLines: string[] = [line];
index++;
- while (index < lines.length && !isBlockStart(lines[index]) && lines[index].trim() !== '') {
+ while (
+ index < lines.length &&
+ !isBlockStart(lines[index]) &&
+ lines[index].trim() !== ''
+ ) {
paraLines.push(lines[index]);
index++;
}
- blocks.push({type: 'paragraph', children: parseInline(paraLines.join('\n'))});
+ blocks.push({
+ type: 'paragraph',
+ children: parseInline(paraLines.join('\n')),
+ });
}
return blocks;
}
@@ -483,10 +584,20 @@ export function trimStreamingArtifacts(input: string): string {
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)
+ // Find the last unclosed [ or ![ (link/image start)
const lastBracket = tail.lastIndexOf('[');
- if (lastBracket !== -1 && !tail.slice(lastBracket).includes('])')) {
- tail = tail.slice(0, lastBracket);
+ if (lastBracket !== -1) {
+ const afterBracket = tail.slice(lastBracket);
+ // A closed link/image has ](...) somewhere after the [
+ const hasClose = afterBracket.includes('](') && afterBracket.includes(')');
+ if (!hasClose) {
+ // Also trim a preceding `!` for images
+ const trimTo =
+ lastBracket > 0 && tail[lastBracket - 1] === '!'
+ ? lastBracket - 1
+ : lastBracket;
+ tail = tail.slice(0, trimTo);
+ }
}
// Find trailing unclosed backticks
@@ -503,16 +614,26 @@ export function trimStreamingArtifacts(input: string): string {
}
// Find trailing unclosed bold/italic markers (*)
+ // First check trailing stars (no content after them yet):
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);
+ if (stars <= 3) {
+ const opener = tail.lastIndexOf('*'.repeat(stars), end - 1);
+ if (opener === -1) {
+ tail = tail.slice(0, end);
+ }
+ }
}
// Find trailing unclosed strikethrough (~~)
if (tail.length >= 2 && tail.endsWith('~~')) {
- tail = tail.slice(0, -2);
+ // Check if there's an opener before these closing ~~
+ const opener = tail.lastIndexOf('~~', tail.length - 3);
+ if (opener === -1) {
+ tail = tail.slice(0, -2);
+ }
} else if (tail.endsWith('~')) {
// Single trailing ~ after content — might be start of ~~
const secondLast = tail.length - 2;
@@ -521,9 +642,97 @@ export function trimStreamingArtifacts(input: string): string {
}
}
+ // Check for unclosed ~~ mid-line: e.g. "Hello ~~struck"
+ // Count ~~ occurrences — if odd, the last one is unclosed.
+ {
+ let count = 0;
+ let searchFrom = 0;
+ const positions: number[] = [];
+ while (true) {
+ const idx = tail.indexOf('~~', searchFrom);
+ if (idx === -1) break;
+ positions.push(idx);
+ count++;
+ searchFrom = idx + 2;
+ }
+ if (count % 2 === 1) {
+ // Odd number of ~~ — the last one is unclosed, trim from it
+ tail = tail.slice(0, positions[positions.length - 1]);
+ }
+ }
+
return prefix + tail;
}
+/**
+ * Trim trailing lines from the unsettled zone that look like the start of
+ * a structural block but aren't complete yet. This prevents flashes of
+ * partial syntax like bare `-` bullets or incomplete table headers.
+ *
+ * Only trims the minimal set of clearly-incomplete patterns:
+ * 1. Bare list markers (`- `, `1. `) with no content after them
+ * 2. A lone table header line without its separator row
+ * 3. Empty trailing lines
+ *
+ * Once a table is established (header + separator exist), new data rows
+ * render immediately — no suppression.
+ */
+function trimUnsettledStructural(text: string): string {
+ const lines = text.split('\n');
+
+ // Walk backwards, but only trim clearly-incomplete trailing lines
+ while (lines.length > 0) {
+ const last = lines[lines.length - 1];
+ const trimmed = last.trim();
+
+ // Empty trailing lines — safe to drop
+ if (trimmed === '') {
+ lines.pop();
+ continue;
+ }
+
+ // Bare list marker with no content: "- " or "1. " (just whitespace after marker)
+ if (/^ {0,9}[-*+] $/.test(last) || /^ {0,9}\d+\. $/.test(last)) {
+ lines.pop();
+ continue;
+ }
+
+ // Table: only suppress if this is a lone header without a separator.
+ // If the line has `|` and the line before it is NOT a separator,
+ // and THIS line is not a separator, and there's no established table
+ // above (header + separator pair), hold it back.
+ if (trimmed.includes('|') && !isTableSeparator(last)) {
+ // Is there a separator anywhere above that would make this part of
+ // an established table? Walk up to find header+separator pair.
+ let tableEstablished = false;
+ for (let i = lines.length - 2; i >= 1; i--) {
+ if (isTableSeparator(lines[i]) && lines[i - 1].includes('|')) {
+ tableEstablished = true;
+ break;
+ }
+ }
+ if (!tableEstablished) {
+ // Lone pipe line — could be a table header waiting for separator
+ lines.pop();
+ continue;
+ }
+ }
+
+ // Separator line without a header above it
+ if (isTableSeparator(last)) {
+ if (lines.length < 2 || !lines[lines.length - 2].includes('|')) {
+ lines.pop();
+ continue;
+ }
+ }
+
+ // This line looks complete — stop trimming
+ break;
+ }
+
+ return lines.join('\n');
+}
+
export function parseMarkdownIncremental(
input: string,
state: IncrementalState,
@@ -546,14 +755,18 @@ export function parseMarkdownIncremental(
}
const settledText = lines.slice(0, boundary).join('\n');
- const unsettledText = lines.slice(boundary).join('\n').trim();
+ const unsettledRaw = lines.slice(boundary).join('\n').trim();
+ const unsettledText = trimUnsettledStructural(unsettledRaw);
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)) {
+ } 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);
diff --git a/packages/core/src/hooks/useXDSStreamingText.test.ts b/packages/core/src/hooks/useXDSStreamingText.test.ts
index 46bceb5063..f2ea1ce310 100644
--- a/packages/core/src/hooks/useXDSStreamingText.test.ts
+++ b/packages/core/src/hooks/useXDSStreamingText.test.ts
@@ -107,4 +107,54 @@ describe('useXDSStreamingText', () => {
expect(result.current.length).toBeGreaterThan(0);
});
+
+ it('advances monotonically without stalls or backwards jumps', () => {
+ const targetText = 'Hello **world**, this is `code` and [a link](http://example.com).';
+ const {result} = renderHook(() =>
+ useXDSStreamingText(targetText, true),
+ );
+
+ expect(result.current).toBe('');
+
+ // Fire many animation frames — the revealed length should only increase
+ const lengths: number[] = [0];
+ for (let i = 0; i < 50; i++) {
+ if (rafCallbacks.length > 0) {
+ const cb = rafCallbacks.pop()!;
+ act(() => cb(performance.now() + i * 20));
+ }
+ const len = result.current.length;
+ expect(len).toBeGreaterThanOrEqual(lengths[lengths.length - 1]);
+ lengths.push(len);
+ }
+
+ // Should have made progress (not stuck at 0)
+ expect(lengths[lengths.length - 1]).toBeGreaterThan(0);
+
+ // Should never have gone backwards
+ for (let i = 1; i < lengths.length; i++) {
+ expect(lengths[i]).toBeGreaterThanOrEqual(lengths[i - 1]);
+ }
+ });
+
+ it('does not stall on markdown syntax characters', () => {
+ // Text with lots of markdown syntax that previously caused stalls
+ const targetText = '- **bold** and *italic* with `code` and [link](url) and ~~strike~~';
+ const {result} = renderHook(() =>
+ useXDSStreamingText(targetText, true),
+ );
+
+ // Fire enough frames to drain the entire text
+ for (let i = 0; i < 100; i++) {
+ if (rafCallbacks.length > 0) {
+ const cb = rafCallbacks.pop()!;
+ act(() => cb(performance.now() + i * 60));
+ }
+ }
+
+ // With enough frames and time elapsed, should have revealed everything
+ // (or close to it — the hook drains charsPerTick per tickMs)
+ expect(result.current.length).toBeGreaterThan(targetText.length * 0.5);
+ });
+
});
diff --git a/packages/core/src/hooks/useXDSStreamingText.ts b/packages/core/src/hooks/useXDSStreamingText.ts
index 67bdab3ce5..e75e00e951 100644
--- a/packages/core/src/hooks/useXDSStreamingText.ts
+++ b/packages/core/src/hooks/useXDSStreamingText.ts
@@ -39,22 +39,8 @@ export interface UseStreamingTextOptions {
speed?: StreamingTextSpeed;
}
-// Characters that are safe word/syntax boundaries for slicing
-const BOUNDARY_PATTERN = /[\s,.;:!?)\]}>]/;
-
-// Markdown syntax markers to avoid slicing inside.
-const PARTIAL_SYNTAX_PATTERNS = [
- /\*{1,2}$/, // partial bold/italic: * or **
- /_{1,2}$/, // partial bold/italic: _ or __
- /~{1,2}$/, // partial strikethrough: ~ or ~~
- /`{1,3}$/, // partial inline code or fence
- /\[(?:[^\]]*)$/, // unclosed link text: [text
- /!\[(?:[^\]]*)$/, // unclosed image alt: ![alt
- /\]\([^)]*$/, // unclosed link url: ](url
-];
-
// Fallback values when no XDSTheme provider is present
-const FALLBACK_TICK_MS = 12;
+const FALLBACK_TICK_MS = 50;
const FALLBACK_TICK_MS_FAST = 8;
/**
@@ -70,7 +56,7 @@ function parseDuration(value: string): number | null {
}
const CHARS_PER_TICK = {
- natural: 2,
+ natural: 10,
fast: 4,
instant: Infinity,
} as const;
@@ -152,40 +138,7 @@ export function useXDSStreamingText(
const currentLen = displayedLenRef.current;
if (currentLen < target.length) {
- // Scale chars with backlog to avoid falling behind
- const backlog = target.length - currentLen;
- const scaledChars =
- backlog > 200
- ? Math.max(charsPerTick, Math.ceil(backlog * 0.15))
- : backlog > 80
- ? Math.max(charsPerTick, Math.ceil(backlog * 0.08))
- : charsPerTick;
-
- let nextLen = Math.min(currentLen + scaledChars, target.length);
-
- // Snap to a word/punctuation boundary
- if (nextLen < target.length) {
- const searchWindow = target.slice(nextLen, nextLen + 12);
- const boundaryOffset = searchWindow.search(BOUNDARY_PATTERN);
- if (boundaryOffset >= 0 && boundaryOffset <= 8) {
- nextLen = nextLen + boundaryOffset + 1;
- }
- }
-
- nextLen = Math.min(nextLen, target.length);
-
- // Back up if we'd slice inside a markdown syntax marker
- const candidate = target.slice(0, nextLen);
- for (const pattern of PARTIAL_SYNTAX_PATTERNS) {
- const match = candidate.match(pattern);
- if (match && match.index != null) {
- nextLen = match.index;
- break;
- }
- }
-
- // Never go backwards
- nextLen = Math.max(nextLen, currentLen);
+ const nextLen = Math.min(currentLen + charsPerTick, target.length);
displayedLenRef.current = nextLen;
setDisplayedLen(nextLen);