, not

: inline content can // include block-level nodes (images, custom inline components), and a //

would reparent them, desyncing SSR markup from the hydrated DOM. // Block spacing comes from token-based StyleX margins, so the rendered // appearance is unchanged. role="paragraph" re-exposes the paragraph // role in the accessibility tree (a pure ARIA hint — it does not trigger // the parser's block-child reparenting) so prose semantics are preserved // without the

composition hazard. Consumers who want a real

// element can still pass components={{paragraph: 'p'}}. return

{paraChildren}

; } case 'code': { // Track codeblock content in cursor for accurate character counting cursor.offset += node.value.length; const language = getMarkdownAstLegacyCodeLanguage(node) ?? 'plaintext'; const CodeBlockComp = components?.code; if (CodeBlockComp) { return ; } const fallback =

; const proposal = getMarkdownFenceProposal(node); if (proposal == null) { return fallback; } const renderer = getMarkdownExtensionRenderer(preparedPlugins, proposal.node); if (renderer == null) { return fallback; } try { const rendered = renderer.render({ node: proposal.node }); if (rendered == null || typeof rendered === 'boolean') { return fallback; } return {rendered} ; } catch (error) { reportMarkdownPluginFailure(proposal.node.plugin, 'render', error); return fallback; } } case 'math': { cursor.offset += node.value.length; const MathComp = components?.math; if (MathComp == null) { return

{`$$${node.value}$$`}

; } return ; } case 'blockquote': { const BlockquoteComp = components?.blockquote; if (BlockquoteComp) { const bqC = node.children.map((c, i) => renderBlock(c, i, node.children.length, density, headingLevelStart, onLinkClick, cursor, citationCtx, contentWidthValue, contentAlign, linkComponent, inlinePlugins, components, preparedPlugins, t)); return {bqC}; } return

{node.children.map((c, i) => renderBlock(c, i, node.children.length, density, headingLevelStart, onLinkClick, cursor, citationCtx, contentWidthValue, contentAlign, linkComponent, inlinePlugins, components, preparedPlugins, t))}

; } case 'list': { // Detect task lists: all items have a checked state const isTaskList = node.children.length > 0 && node.children.every(item => item.checked != null); if (isTaskList) { // Extract labels from task items — render as rich inline content const checkedValues = node.children.map((item, i) => ({ item, key: `task-${i}` })).filter(({ item }) => item.checked).map(({ key }) => key); return

{node.children.map((item, i) => { const firstChild = item.children[0]; const isInline = item.children.length === 1 && firstChild?.type === 'paragraph'; const label = isInline ? <> {firstChild.children.map((c, j) => renderInline(c, j, onLinkClick, cursor, citationCtx, linkComponent, inlinePlugins, components, preparedPlugins))} : <> {item.children.map((c, j) => renderBlock(c, j, item.children.length, density, headingLevelStart, onLinkClick, cursor, citationCtx, contentWidthValue, contentAlign, linkComponent, inlinePlugins, components, preparedPlugins, t))} ; return ; })}

; } return

{node.children.map((item, i) => { const firstChild = item.children[0]; 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 label = isInline ? <> {firstChild.children.map((c, j) => renderInline(c, j, onLinkClick, cursor, citationCtx, linkComponent, inlinePlugins, components, preparedPlugins))} : <> {item.children.map((c, j) => renderBlock(c, j, item.children.length, density, headingLevelStart, onLinkClick, cursor, citationCtx, contentWidthValue, contentAlign, linkComponent, inlinePlugins, components, preparedPlugins, t))} ; return ; })}

; } case 'table': { const colMinWidths = computeTableColumnMinWidths(node); const [header, ...rows] = node.children; return

{header?.children.map((h, i) => {h.children.map((c, j) => renderInline(c, j, onLinkClick, cursor, citationCtx, linkComponent, inlinePlugins, components, preparedPlugins))} )} {rows.map((row, i) => { const cells = row.children.map((cell, j) => {cell.children.map((c, k) => renderInline(c, k, onLinkClick, cursor, citationCtx, linkComponent, inlinePlugins, components, preparedPlugins))} ); return {cells} ; })}

; } case 'extension': { const renderer = getMarkdownExtensionRenderer(preparedPlugins, node); const fallbackText = node.source ?? markdownExtensionText(preparedPlugins, node); const fallback = wrapTextWithFade(fallbackText, cursor, index); let content: React.ReactNode = fallback; if (renderer != null) { try { const rendered = renderer.render({ node }); content = {rendered} ; } catch (error) { reportMarkdownPluginFailure(node.plugin, 'render', error); } } return

{content}

; } case 'thematicBreak': { const HrComp = components?.hr; if (HrComp) { return ; } return

; } case 'image': { const safeSrc = sanitizeMarkdownUrl(node.url); if (safeSrc == null) { return

[{node.alt}]

; } const ImageComp = components?.image; if (ImageComp) { return ; } return

; } } } // --------------------------------------------------------------------------- // Component // --------------------------------------------------------------------------- /** * Renders a markdown string as Astryx components. Supports streaming with * smooth fade-in animation via isStreaming. * * @example * ``` * * {'# Hello\n\nThis is **bold** and _italic_ text.\n\n- Item one\n- Item two'} * * ``` */ export function Markdown = readonly []>({ ref, children, display = 'block', density = 'default', headingLevelStart = 1, isStreaming = false, onLinkClick, sources, citationStyle = 'label', contentWidth = 680, contentAlign = 'start', components, plugins, inlinePlugins, autolink, xstyle, className, style, 'data-testid': testId, ...props }: MarkdownProps): React.ReactElement { const t = useTranslator(); const LinkComponent = useLinkComponent(); // Derive the set of source IDs for the parser (stable across renders when sources don't change) const sourceIds = useMemo(() => sources ? new Set(Object.keys(sources)) : undefined, [sources]); const preparedPlugins = useMemo(() => { if (plugins == null) { return undefined; } try { return prepareMarkdownPlugins(plugins); } catch (error) { reportMarkdownPluginFailure('configuration', 'transform', error); return undefined; } }, [plugins]); const syntaxPlugins = useStableMarkdownSyntaxEntries(preparedPlugins); const hasMathRenderer = components?.math != null; const legacyParseOptions = useMemo>>(() => ({ sourceIds, autolink, plugins: syntaxPlugins }), [sourceIds, autolink, syntaxPlugins]); const mathParseOptions = useMemo>>(() => ({ sourceIds, autolink, math: true, plugins: syntaxPlugins }), [sourceIds, autolink, syntaxPlugins]); // Smooth bursty streamed chunks into a steady character-by-character reveal. // When not streaming, the hook returns children unchanged (no-op). const smoothedText = useStreamingText(children, isStreaming); const incrementalStateRef = useRef>(createIncrementalState()); // Reset incremental cache when parser-affecting component options toggle — // cached settled blocks were parsed with the previous setting. const prevAutolinkRef = useRef(autolink); const prevMathRef = useRef(hasMathRenderer); if (prevAutolinkRef.current !== autolink || prevMathRef.current !== hasMathRenderer) { incrementalStateRef.current = createIncrementalState(); prevAutolinkRef.current = autolink; prevMathRef.current = hasMathRenderer; } const parsedBlocks = useMemo(() => { if (display === 'inline') { return []; } if (isStreaming) { if (smoothedText === '') { incrementalStateRef.current = createIncrementalState(); return []; } const options = hasMathRenderer ? mathParseOptions : legacyParseOptions; const input = trimStreamingArtifacts(smoothedText, options); return (hasMathRenderer ? parseMarkdownAstIncremental(input, incrementalStateRef.current, mathParseOptions) : parseMarkdownAstIncremental(input, incrementalStateRef.current, legacyParseOptions)).children; } return (hasMathRenderer ? parseMarkdownAst(children, mathParseOptions) : parseMarkdownAst(children, legacyParseOptions)).children; }, [display, smoothedText, children, isStreaming, hasMathRenderer, mathParseOptions, legacyParseOptions]); const transformSource = isStreaming ? trimStreamingArtifacts(smoothedText, hasMathRenderer ? mathParseOptions : legacyParseOptions) : children; const blocks = useMemo(() => applyMarkdownTransforms({ type: 'root', children: parsedBlocks }, preparedPlugins, transformSource, !isStreaming, 'block').children, [parsedBlocks, preparedPlugins, transformSource, isStreaming]); // Assign each top-level heading the slug that parseOutlineFromMarkdown // would derive for it, so Outline hash links built from the same source // always find a matching DOM id. Mirrors that function's traversal exactly: // top-level blocks only, one shared duplicate-numbering sequence. // NOTE: must stay above the `display === 'inline'` early return below — // hooks cannot be conditional. const headingIdMap = useMemo(() => { if (display === 'inline' || blocks.length === 0) { return undefined; } const map = new Map(); const counts = new Map(); for (const block of blocks) { if (block.type === 'heading') { const label = markdownAstText(block.children, node => markdownExtensionText(preparedPlugins, node)).trim(); map.set(block, uniqueSlug(slugify(label), counts)); } } return map; }, [display, blocks, preparedPlugins]); const parsedInlineNodes = useMemo(() => { if (display !== 'inline') { return []; } const options = hasMathRenderer ? mathParseOptions : legacyParseOptions; const input = isStreaming ? trimStreamingArtifacts(smoothedText, options) : children; return hasMathRenderer ? parseInlineAst(input, mathParseOptions) : parseInlineAst(input, legacyParseOptions); }, [display, smoothedText, children, isStreaming, hasMathRenderer, mathParseOptions, legacyParseOptions]); const inlineTransformSource = isStreaming ? trimStreamingArtifacts(smoothedText, hasMathRenderer ? mathParseOptions : legacyParseOptions) : children; const inlineNodes = useMemo(() => { if (display !== 'inline') { return []; } const transformed = applyMarkdownTransforms({ type: 'root', children: [{ type: 'paragraph', children: parsedInlineNodes }] }, preparedPlugins, inlineTransformSource, !isStreaming, 'inline'); const paragraph = transformed.children[0]; return paragraph?.type === 'paragraph' ? [...paragraph.children] : parsedInlineNodes; }, [display, parsedInlineNodes, preparedPlugins, inlineTransformSource, isStreaming]); // Track recent boundaries for stacked fade-in animation. // The number of spans needed = ceil(animationDuration / tickInterval). // useStreamingText ticks every ~tickMs, and the fade runs for // --duration-fast-max. We compute the span count dynamically so the // oldest span has just finished animating when it gets evicted. const { token } = useTheme(); const maxSpans = useMemo(() => { const duration = parseDuration(token('--duration-fast-max')) ?? 230; const tick = parseDuration(token('--duration-fast-min')); // Tick interval mirrors useStreamingText's timing: base / 10 const tickMs = tick != null ? Math.max(4, Math.round(tick / 10)) : 50; return Math.min(Math.ceil(duration / tickMs), 12); }, [token]); const prevBlocksRef = useRef>([]); const prevInlineNodesRef = useRef>([]); const boundariesRef = useRef([]); const smoothedLen = smoothedText.length; const boundaries = useMemo(() => { void smoothedLen; // dep trigger const prevLen = display === 'inline' ? countInlineTextLength(prevInlineNodesRef.current) : countBlockTextLength(prevBlocksRef.current); const next = computeBoundaries(boundariesRef.current, prevLen, maxSpans); boundariesRef.current = next; return next; }, [display, smoothedLen, maxSpans]); const cursor: StreamingCursor = { offset: 0, boundaries, active: isStreaming }; // Build citation context — numbers are assigned in encounter order during rendering. // This is recreated each render so numbering stays consistent with the AST. const citationCtx: CitationContext | null = sources ? { sources, numberMap: new Map(), nextNumber: 1, style: citationStyle } : null; if (display === 'inline') { const renderedInline = {inlineNodes.map((node, i) => renderInline(node, i, onLinkClick, cursor, citationCtx, LinkComponent, inlinePlugins, components, preparedPlugins))} ; // Store current inline nodes for next render's boundary calculation. prevInlineNodesRef.current = inlineNodes; prevBlocksRef.current = []; return renderedInline; } const rendered =

} // Consumer props first: what the component sets for itself — the // document role included — wins. {...props} role="document" data-testid={testId} {...mergeProps(themeProps('markdown', { density }), stylex.props(styles.root, xstyle), className, style)}> {blocks.map((block, i) => renderBlock(block, i, blocks.length, density, headingLevelStart, onLinkClick, cursor, citationCtx, contentWidth ? typeof contentWidth === 'number' ? `${contentWidth}px` : contentWidth : null, contentAlign, LinkComponent, inlinePlugins, components, preparedPlugins, t, headingIdMap))}

; // Store current blocks for next render's boundary calculation. // This ref write is safe under StrictMode: both invocations produce the same // blocks (same smoothedText → same useMemo result), so both write the same value. prevBlocksRef.current = blocks; prevInlineNodesRef.current = []; return rendered; } Markdown.displayName = 'Markdown';