Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

bugfix: large streaming Markdown rendering delay (#234)

harshil-2096f810bb1791c8
diff --git a/packages/frontend/package.json b/packages/frontend/package.json
index f73c48f4f..c892c273a 100644
--- a/packages/frontend/package.json
+++ b/packages/frontend/package.json
@@ -24,7 +24,7 @@
"@assistant-ui/core": "0.2.22",
"@assistant-ui/react": "^0.14.24",
"@assistant-ui/store": "0.2.21",
- "@truefoundry/assistant-ui-runtime": "0.1.14",
+ "@truefoundry/assistant-ui-runtime": "0.1.15",
"@truefoundry/trueforge-sdk": "workspace:*",
"@truefoundry/trueforge-ui": "workspace:*",
"monaco-editor": "^0.52.0",
diff --git a/packages/trueforge-ui-sdk/docs/compatibility.md b/packages/trueforge-ui-sdk/docs/compatibility.md
index 07fa0085b..a557e3638 100644
--- a/packages/trueforge-ui-sdk/docs/compatibility.md
+++ b/packages/trueforge-ui-sdk/docs/compatibility.md
@@ -21,7 +21,7 @@ Install once at the app root.
| ----------------------------------- | ------------- |
| `@assistant-ui/core` | `^0.2.22` |
| `@assistant-ui/react` | `^0.14.24` |
-| `@truefoundry/assistant-ui-runtime` | `0.1.13` |
+| `@truefoundry/assistant-ui-runtime` | `0.1.15` |
| `truefoundry-gateway-sdk` | `^0.4.0-rc.6` |
| `lucide-react` | `^0.562.0` |
diff --git a/packages/trueforge-ui-sdk/example/package.json b/packages/trueforge-ui-sdk/example/package.json
index 1d0263a82..bd0e629e1 100644
--- a/packages/trueforge-ui-sdk/example/package.json
+++ b/packages/trueforge-ui-sdk/example/package.json
@@ -12,7 +12,7 @@
"dependencies": {
"@assistant-ui/core": "^0.2.22",
"@assistant-ui/react": "^0.14.24",
- "@truefoundry/assistant-ui-runtime": "0.1.14",
+ "@truefoundry/assistant-ui-runtime": "0.1.15",
"@truefoundry/trueforge-ui": "link:..",
"react": "^19.2.4",
"react-dom": "^19.2.4",
diff --git a/packages/trueforge-ui-sdk/example/yarn.lock b/packages/trueforge-ui-sdk/example/yarn.lock
index f7f5903b9..76dc00f8d 100644
--- a/packages/trueforge-ui-sdk/example/yarn.lock
+++ b/packages/trueforge-ui-sdk/example/yarn.lock
@@ -1425,10 +1425,10 @@
"@tailwindcss/oxide" "4.3.3"
tailwindcss "4.3.3"
-"@truefoundry/[email protected]":
- version "0.1.14"
- resolved "https://registry.yarnpkg.com/@truefoundry/assistant-ui-runtime/-/assistant-ui-runtime-0.1.14.tgz#c77b2f41ae260b965c16d72dc1b9f73ddde66813"
- integrity sha512-xdFob3v6KdhUVFrDuw1OAcX6o8lsnT+kQAo82gzCgXbg3YvdIs4cDWRswZdCI83FriRieYtMc8kZPjrRysJSkQ==
+"@truefoundry/[email protected]":
+ version "0.1.15"
+ resolved "https://registry.yarnpkg.com/@truefoundry/assistant-ui-runtime/-/assistant-ui-runtime-0.1.15.tgz#9acfd809a1364d2a9b58c48ddc28ff67fb1ee1bd"
+ integrity sha512-WHbQJ0pEoVNYJ5dt99powKqPqLQejpOEYX5jsLkmZMLwty1fgGYgflovXo0StD2VUAblklstL9vpwu/pqMMh/g==
dependencies:
"@assistant-ui/core" "^0.2.22"
"@assistant-ui/store" "^0.2.21"
diff --git a/packages/trueforge-ui-sdk/package.json b/packages/trueforge-ui-sdk/package.json
index fbe703474..a9ea31e22 100644
--- a/packages/trueforge-ui-sdk/package.json
+++ b/packages/trueforge-ui-sdk/package.json
@@ -93,7 +93,7 @@
"@openuidev/react-headless": "^0.9.4",
"@openuidev/react-lang": "^0.2.9",
"@openuidev/react-ui": "^0.13.2",
- "@truefoundry/assistant-ui-runtime": "0.1.14",
+ "@truefoundry/assistant-ui-runtime": "0.1.15",
"clsx": "^2.1.1",
"lucide-react": "^0.562.0",
"monaco-editor": "^0.56.0",
diff --git a/packages/trueforge-ui-sdk/src/atoms/Markdown.tsx b/packages/trueforge-ui-sdk/src/atoms/Markdown.tsx
index 792231411..a3b8f63a8 100644
--- a/packages/trueforge-ui-sdk/src/atoms/Markdown.tsx
+++ b/packages/trueforge-ui-sdk/src/atoms/Markdown.tsx
@@ -1,6 +1,7 @@
'use client';
import type { ComponentType, ReactNode } from 'react';
+import { useMemo, useRef } from 'react';
import ReactMarkdown, { type Components } from 'react-markdown';
import remarkGfm from 'remark-gfm';
@@ -16,6 +17,13 @@ export function preloadMarkdownOpenUI(): Promise<unknown> {
return import('./OpenUiFenceBlock.js');
}
+/**
+ * Prism cost grows with the code body. While the final fence is still open and changing, render
+ * it as plain code above this size; closed fences remain highlighted and are not repeatedly
+ * downgraded. The active fence is highlighted once when its closing delimiter arrives.
+ */
+export const LARGE_STREAMING_FENCE_CHARS = 8 * 1024;
+
export type MarkdownProps = {
content: string;
isStreaming?: boolean;
@@ -28,8 +36,27 @@ export type MarkdownProps = {
className?: string;
};
+/**
+ * Body of the final unmatched fenced block while streaming, or null when every fence is closed.
+ * Used so only the growing fence skips Prism — completed large fences stay highlighted.
+ */
+export function getActiveStreamingFenceCode(content: string): string | null {
+ const re = /^(`{3,})([^\n]*)\n?/gm;
+ const markers: Array<{ after: number }> = [];
+ let match: RegExpExecArray | null;
+ while ((match = re.exec(content)) !== null) {
+ markers.push({ after: match.index + match[0].length });
+ }
+ if (markers.length % 2 === 0) return null;
+ const open = markers[markers.length - 1];
+ if (open == null) return null;
+ return content.slice(open.after).replace(/\n$/, '');
+}
+
function makeComponents(opts: {
isStreaming?: boolean;
+ /** Latest unmatched fence body; read via ref so `components` identity stays stable across growth. */
+ getActiveFenceCode: () => string | null;
darkTheme: boolean;
fileDownloadBaseUrl?: string;
onDownloadArtifact?: (path: string, filename: string) => Promise<void>;
@@ -41,6 +68,7 @@ function makeComponents(opts: {
}): Components {
const {
isStreaming,
+ getActiveFenceCode,
darkTheme,
fileDownloadBaseUrl,
onDownloadArtifact,
@@ -86,11 +114,34 @@ function makeComponents(opts: {
);
}
+ // Only the unmatched growing fence skips Prism; closed fences stay highlighted.
+ const activeFenceCode = getActiveFenceCode();
+ const isActiveOversizedFence =
+ isStreaming === true &&
+ activeFenceCode != null &&
+ code === activeFenceCode &&
+ code.length > LARGE_STREAMING_FENCE_CHARS;
+
+ if (isActiveOversizedFence) {
+ return (
+ <pre
+ className={cn(
+ 'aui-syntax-highlighter my-2 max-w-full min-w-0 overflow-x-auto whitespace-pre-wrap break-words rounded-md',
+ )}
+ data-testid="aui-plain-streaming-fence"
+ >
+ <code className={cn(className, 'whitespace-pre-wrap break-words')}>{code}</code>
+ </pre>
+ );
+ }
+
return <SyntaxHighlighter code={code} language={language} darkTheme={darkTheme} />;
},
};
}
+const REMARK_PLUGINS = [remarkGfm];
+
export function Markdown({
content,
isStreaming,
@@ -106,23 +157,42 @@ export function Markdown({
const SandboxArtifactDownload = useSlot('SandboxArtifactDownload');
const SyntaxHighlighter = useSlot('SyntaxHighlighter');
- const components = makeComponents({
- isStreaming,
- darkTheme,
- fileDownloadBaseUrl,
- onDownloadArtifact,
- readOnly,
- OpenUiFenceBlock,
- SandboxArtifactDownload,
- SyntaxHighlighter,
- inlineCodeClassName: classNames.inlineCode,
- });
+ // Ref keeps `components` stable while the active fence grows so completed Prism trees do not remount.
+ const activeFenceCodeRef = useRef<string | null>(null);
+ activeFenceCodeRef.current = isStreaming === true ? getActiveStreamingFenceCode(content) : null;
+
+ const components = useMemo(
+ () =>
+ makeComponents({
+ isStreaming,
+ getActiveFenceCode: () => activeFenceCodeRef.current,
+ darkTheme,
+ fileDownloadBaseUrl,
+ onDownloadArtifact,
+ readOnly,
+ OpenUiFenceBlock,
+ SandboxArtifactDownload,
+ SyntaxHighlighter,
+ inlineCodeClassName: classNames.inlineCode,
+ }),
+ [
+ isStreaming,
+ darkTheme,
+ fileDownloadBaseUrl,
+ onDownloadArtifact,
+ readOnly,
+ OpenUiFenceBlock,
+ SandboxArtifactDownload,
+ SyntaxHighlighter,
+ classNames.inlineCode,
+ ],
+ );
return (
<div
className={cn('aui-markdown markdown-body min-w-0 max-w-full overflow-x-clip', classNames.markdown, className)}
>
- <ReactMarkdown remarkPlugins={[remarkGfm]} components={components}>
+ <ReactMarkdown remarkPlugins={REMARK_PLUGINS} components={components}>
{content}
</ReactMarkdown>
</div>
diff --git a/packages/trueforge-ui-sdk/src/atoms/SyntaxHighlighter.tsx b/packages/trueforge-ui-sdk/src/atoms/SyntaxHighlighter.tsx
index 65ffbef43..ad1f30f5f 100644
--- a/packages/trueforge-ui-sdk/src/atoms/SyntaxHighlighter.tsx
+++ b/packages/trueforge-ui-sdk/src/atoms/SyntaxHighlighter.tsx
@@ -1,6 +1,15 @@
'use client';
-import { Children, cloneElement, isValidElement, useCallback, useState, type ReactNode } from 'react';
+import {
+ Children,
+ cloneElement,
+ isValidElement,
+ memo,
+ useCallback,
+ useState,
+ type ComponentType,
+ type ReactNode,
+} from 'react';
import { Prism as PrismHighlighter } from 'react-syntax-highlighter';
import { oneDark, oneLight } from 'react-syntax-highlighter/dist/esm/styles/prism';
@@ -31,7 +40,7 @@ function applyLineNumberClassName(children: ReactNode, className: string | undef
});
}
-export function SyntaxHighlighter({ code, language, darkTheme, className, showLineNumbers }: SyntaxHighlighterProps) {
+function SyntaxHighlighterImpl({ code, language, darkTheme, className, showLineNumbers }: SyntaxHighlighterProps) {
const classNames = useOptionalContentClassNames();
const style = darkTheme ? oneDark : oneLight;
const [copied, setCopied] = useState(false);
@@ -96,6 +105,8 @@ export function SyntaxHighlighter({ code, language, darkTheme, className, showLi
);
}
+export const SyntaxHighlighter: ComponentType<SyntaxHighlighterProps> = memo(SyntaxHighlighterImpl);
+
declare module '../theme/SlotsProvider.js' {
interface AtomSlots {
SyntaxHighlighter: typeof SyntaxHighlighter;
diff --git a/packages/trueforge-ui-sdk/src/atoms/ThreadShell.tsx b/packages/trueforge-ui-sdk/src/atoms/ThreadShell.tsx
index dc78708c1..b03d3d2b2 100644
--- a/packages/trueforge-ui-sdk/src/atoms/ThreadShell.tsx
+++ b/packages/trueforge-ui-sdk/src/atoms/ThreadShell.tsx
@@ -34,7 +34,7 @@ export const ThreadViewportShell = forwardRef<HTMLDivElement, ThreadViewportShel
ref={ref}
data-slot="aui_thread-viewport"
className={cn(
- 'relative flex min-h-0 min-w-0 flex-1 flex-col overflow-x-hidden overflow-y-auto overscroll-contain scroll-smooth',
+ 'relative flex min-h-0 min-w-0 flex-1 flex-col overflow-x-hidden overflow-y-auto overscroll-contain',
className,
)}
{...rest}
diff --git a/packages/trueforge-ui-sdk/src/containers/AssistantTextContainer.tsx b/packages/trueforge-ui-sdk/src/containers/AssistantTextContainer.tsx
index ff8387ce5..583be9724 100644
--- a/packages/trueforge-ui-sdk/src/containers/AssistantTextContainer.tsx
+++ b/packages/trueforge-ui-sdk/src/containers/AssistantTextContainer.tsx
@@ -8,8 +8,9 @@ import {
type TextMessagePart,
} from '@assistant-ui/react';
import { useTrueFoundryDownloadSandboxFile } from '@truefoundry/assistant-ui-runtime';
-import { useCallback, useRef } from 'react';
+import { useCallback, useMemo, useRef } from 'react';
+import { MARKDOWN_SMOOTH_BACKLOG_CHARS, useThrottledMarkdownText } from '../hooks/useThrottledMarkdownText.js';
import { useSlot } from '../theme/SlotsProvider.js';
import { useToasterOptional } from './ToasterContainer.js';
@@ -36,15 +37,42 @@ export function AssistantTextContainer() {
const downloadRef = useRef({ downloadSandboxFile, toaster });
downloadRef.current = { downloadSandboxFile, toaster };
const partState = useAuiState(s => s.part as MessagePartState & (TextMessagePart | ReasoningMessagePart));
- const smoothedPart = useSmooth(partState, {
- drainMs: 300,
- maxCharIntervalMs: 6,
- maxCharsPerFrame: 32,
- minCommitMs: 48,
+
+ // Preserve the typewriter effect while it keeps pace. If its visible prefix falls too far
+ // behind the raw stream, latch this part into bounded latest-prefix snapshots instead of
+ // animating an ever-growing queue. We intentionally do not re-enable useSmooth for this part:
+ // its private cursor still points at the old prefix and could visibly rewind the message.
+ const pacedModeRef = useRef(false);
+ const smoothedPart = useSmooth(
+ partState,
+ pacedModeRef.current
+ ? false
+ : {
+ drainMs: 150,
+ maxCharIntervalMs: 4,
+ maxCharsPerFrame: 128,
+ minCommitMs: 48,
+ },
+ );
+
+ const networkComplete = partState.status?.type !== 'running';
+ const smoothLag = partState.text.length - smoothedPart.text.length;
+ if (!pacedModeRef.current && !networkComplete && smoothLag >= MARKDOWN_SMOOTH_BACKLOG_CHARS) {
+ pacedModeRef.current = true;
+ }
+ const usePacedMode = pacedModeRef.current;
+
+ const pacedText = useThrottledMarkdownText(partState.text, {
+ enabled: usePacedMode,
+ isComplete: networkComplete,
});
- const text = smoothedPart.text;
- // true while network stream is active OR while reveal is still catching up
- const isStreaming = smoothedPart.status?.type === 'running';
+
+ const text = usePacedMode ? pacedText : smoothedPart.text;
+ // true while network stream is active OR while reveal/paced commit is still catching up
+ const isStreaming = usePacedMode
+ ? !networkComplete || text !== partState.text
+ : smoothedPart.status?.type === 'running';
+
const handleDownloadArtifact = useCallback(async (path: string) => {
const { downloadSandboxFile, toaster } = downloadRef.current;
try {
@@ -58,5 +86,9 @@ export function AssistantTextContainer() {
}
}, []);
- return <Markdown content={text} isStreaming={isStreaming} onDownloadArtifact={handleDownloadArtifact} />;
+ // Skip markdown re-parse when a raw SSE tick did not advance the committed display text.
+ return useMemo(
+ () => <Markdown content={text} isStreaming={isStreaming} onDownloadArtifact={handleDownloadArtifact} />,
+ [Markdown, text, isStreaming, handleDownloadArtifact],
+ );
}
diff --git a/packages/trueforge-ui-sdk/src/hooks/useThrottledMarkdownText.ts b/packages/trueforge-ui-sdk/src/hooks/useThrottledMarkdownText.ts
new file mode 100644
index 000000000..a3b4a6be9
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/hooks/useThrottledMarkdownText.ts
@@ -0,0 +1,89 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Maximum tolerated gap between the raw stream and the typewriter reveal.
+ * Beyond this point, animating every queued character delays the response noticeably, so the
+ * container switches to paced snapshots of the latest raw prefix.
+ */
+export const MARKDOWN_SMOOTH_BACKLOG_CHARS = 4 * 1024;
+
+/**
+ * Limits catch-up rendering to roughly 10 updates per second: frequent enough to keep streamed
+ * text responsive, while leaving enough main-thread time for full-document Markdown parsing and
+ * syntax highlighting to finish before the next snapshot.
+ */
+export const LARGE_MARKDOWN_THROTTLE_MS = 100;
+
+/**
+ * Provides bounded latest-prefix snapshots after the typewriter reveal falls too far behind.
+ *
+ * Enabling the hook immediately catches up to the current raw prefix, then coalesces subsequent
+ * stream updates to one commit per `throttleMs`. Completion always bypasses the timer so the final
+ * document is exact. While disabled, the hook mirrors `text` and stays ready for a monotonic
+ * transition into catch-up mode.
+ */
+export function useThrottledMarkdownText(
+ text: string,
+ {
+ isComplete,
+ enabled,
+ throttleMs = LARGE_MARKDOWN_THROTTLE_MS,
+ }: { isComplete: boolean; enabled: boolean; throttleMs?: number },
+): string {
+ const [committed, setCommitted] = useState(text);
+ const lastCommittedRef = useRef(text);
+ const lastCommitAtRef = useRef(Date.now());
+ const pendingRef = useRef(text);
+ const wasEnabledRef = useRef(enabled);
+
+ useEffect(() => {
+ pendingRef.current = text;
+
+ const commit = (value: string) => {
+ // A stale timer must never replace a newer visible prefix with an older one.
+ if (value.length < lastCommittedRef.current.length && value !== lastCommittedRef.current) {
+ return;
+ }
+ lastCommittedRef.current = value;
+ lastCommitAtRef.current = Date.now();
+ setCommitted(value);
+ };
+
+ if (!enabled) {
+ wasEnabledRef.current = false;
+ lastCommittedRef.current = text;
+ lastCommitAtRef.current = Date.now();
+ setCommitted(text);
+ return;
+ }
+
+ // Clear the accumulated reveal backlog once; only future growth is throttled.
+ if (!wasEnabledRef.current) {
+ wasEnabledRef.current = true;
+ commit(text);
+ return;
+ }
+
+ if (lastCommittedRef.current === text) return;
+
+ if (isComplete) {
+ commit(text);
+ return;
+ }
+
+ const elapsed = Date.now() - lastCommitAtRef.current;
+ if (elapsed >= throttleMs) {
+ commit(text);
+ return;
+ }
+
+ const id = setTimeout(() => {
+ commit(pendingRef.current);
+ }, throttleMs - elapsed);
+ return () => clearTimeout(id);
+ }, [text, isComplete, enabled, throttleMs]);
+
+ return enabled ? committed : text;
+}
diff --git a/packages/trueforge-ui-sdk/test/atoms/Markdown.test.tsx b/packages/trueforge-ui-sdk/test/atoms/Markdown.test.tsx
index da7540c73..b1634b914 100644
--- a/packages/trueforge-ui-sdk/test/atoms/Markdown.test.tsx
+++ b/packages/trueforge-ui-sdk/test/atoms/Markdown.test.tsx
@@ -1,12 +1,26 @@
// @vitest-environment jsdom
import { render, screen, waitFor } from '@testing-library/react';
+import { useEffect } from 'react';
import { describe, expect, it } from 'vitest';
-import { Markdown } from '@/atoms/Markdown.js';
+import { LARGE_STREAMING_FENCE_CHARS, Markdown, getActiveStreamingFenceCode } from '@/atoms/Markdown.js';
+import type { SyntaxHighlighterProps } from '@/atoms/SyntaxHighlighter.js';
+import { SlotsProvider } from '@/theme/SlotsProvider.js';
// @openuidev mocks are in testSetup.ts; they make OpenUiFenceBlock render
// a simple div with data-testid="aui-openui-renderer" synchronously.
+describe('getActiveStreamingFenceCode', () => {
+ it('returns null when every fence is closed', () => {
+ expect(getActiveStreamingFenceCode('```js\nconst x = 1;\n```\n\ndone')).toBeNull();
+ });
+
+ it('returns the body of the final unmatched fence', () => {
+ const body = 'x'.repeat(100);
+ expect(getActiveStreamingFenceCode(`intro\n\n\`\`\`json\n${body}`)).toBe(body);
+ });
+});
+
describe('Markdown', () => {
it('renders basic markdown formatting', () => {
render(<Markdown content="**bold** text" />);
@@ -29,4 +43,68 @@ describe('Markdown', () => {
// react-syntax-highlighter renders the code as text nodes inside the fence block.
expect(screen.getByText(/const x = 1/)).toBeInTheDocument();
});
+
+ it('keeps Prism for small streaming fences', () => {
+ render(<Markdown content={'```json\n{"a":1}\n```'} isStreaming />);
+ expect(screen.queryByTestId('aui-plain-streaming-fence')).not.toBeInTheDocument();
+ expect(screen.getByTestId('aui-syntax-highlighter')).toBeInTheDocument();
+ });
+
+ it('keeps Prism for large closed fences while the message is still streaming', () => {
+ const huge = 'x'.repeat(LARGE_STREAMING_FENCE_CHARS + 1);
+ render(<Markdown content={`\`\`\`json\n${huge}\n\`\`\`\n\nmore text`} isStreaming />);
+ expect(screen.queryByTestId('aui-plain-streaming-fence')).not.toBeInTheDocument();
+ expect(screen.getByTestId('aui-syntax-highlighter')).toBeInTheDocument();
+ });
+
+ it('falls back to a plain pre only for the active unmatched oversized fence', () => {
+ const closed = 'c'.repeat(LARGE_STREAMING_FENCE_CHARS + 1);
+ const open = 'o'.repeat(LARGE_STREAMING_FENCE_CHARS + 1);
+ render(<Markdown content={`\`\`\`json\n${closed}\n\`\`\`\n\n\`\`\`json\n${open}`} isStreaming />);
+ expect(screen.getByTestId('aui-plain-streaming-fence')).toBeInTheDocument();
+ expect(screen.getByTestId('aui-syntax-highlighter')).toBeInTheDocument();
+ expect(screen.getByTestId('aui-plain-streaming-fence')).toHaveTextContent(open.slice(0, 32));
+ });
+
+ it('highlights large fences once streaming finishes', () => {
+ const huge = 'x'.repeat(LARGE_STREAMING_FENCE_CHARS + 1);
+ render(<Markdown content={`\`\`\`json\n${huge}\n\`\`\``} isStreaming={false} />);
+ expect(screen.queryByTestId('aui-plain-streaming-fence')).not.toBeInTheDocument();
+ expect(screen.getByTestId('aui-syntax-highlighter')).toBeInTheDocument();
+ });
+
+ it('does not remount a completed code block when later markdown is appended', () => {
+ let mountCount = 0;
+ function TrackingHighlighter({ code, language }: SyntaxHighlighterProps) {
+ useEffect(() => {
+ mountCount += 1;
+ }, []);
+ return (
+ <pre data-testid="aui-syntax-highlighter" data-language={language}>
+ {code}
+ </pre>
+ );
+ }
+
+ const closedBody = 'const completed = true;';
+ const prefix = `\`\`\`js\n${closedBody}\n\`\`\`\n\n`;
+
+ const { rerender } = render(
+ <SlotsProvider overrides={{ SyntaxHighlighter: TrackingHighlighter }}>
+ <Markdown content={`${prefix}growing`} isStreaming />
+ </SlotsProvider>,
+ );
+
+ expect(screen.getByTestId('aui-syntax-highlighter')).toHaveTextContent(closedBody);
+ expect(mountCount).toBe(1);
+
+ rerender(
+ <SlotsProvider overrides={{ SyntaxHighlighter: TrackingHighlighter }}>
+ <Markdown content={`${prefix}growing more text after the fence`} isStreaming />
+ </SlotsProvider>,
+ );
+
+ expect(screen.getByTestId('aui-syntax-highlighter')).toHaveTextContent(closedBody);
+ expect(mountCount).toBe(1);
+ });
});
diff --git a/packages/trueforge-ui-sdk/test/atoms/ThreadShell.test.tsx b/packages/trueforge-ui-sdk/test/atoms/ThreadShell.test.tsx
index f476b8d1b..cbac3f538 100644
--- a/packages/trueforge-ui-sdk/test/atoms/ThreadShell.test.tsx
+++ b/packages/trueforge-ui-sdk/test/atoms/ThreadShell.test.tsx
@@ -30,6 +30,8 @@ describe('ThreadViewportShell', () => {
const viewport = screen.getByTestId('viewport');
expect(viewport).toHaveAttribute('data-slot', 'aui_thread-viewport');
+ // CSS smooth scroll fights assistant-ui autoScroll and causes bounce on large streams.
+ expect(viewport.className).not.toMatch(/\bscroll-smooth\b/);
expect(viewport.firstElementChild).toHaveClass('min-h-full', 'justify-center', 'pb-4');
expect(viewport).toHaveTextContent('Welcome');
diff --git a/packages/trueforge-ui-sdk/test/containers/AssistantTextContainer.test.tsx b/packages/trueforge-ui-sdk/test/containers/AssistantTextContainer.test.tsx
index 24edc83f9..cf3f0830e 100644
--- a/packages/trueforge-ui-sdk/test/containers/AssistantTextContainer.test.tsx
+++ b/packages/trueforge-ui-sdk/test/containers/AssistantTextContainer.test.tsx
@@ -5,12 +5,14 @@ import {
useExternalStoreRuntime,
type ThreadMessageLike,
} from '@assistant-ui/react';
-import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
import { trueFoundryExtras } from '@truefoundry/assistant-ui-runtime';
+import { useState } from 'react';
import { describe, expect, it, vi } from 'vitest';
import type { MarkdownProps } from '@/atoms/Markdown.js';
import { AssistantMessageContainer } from '@/containers/AssistantMessageContainer.js';
+import { LARGE_MARKDOWN_THROTTLE_MS, MARKDOWN_SMOOTH_BACKLOG_CHARS } from '@/hooks/useThrottledMarkdownText.js';
import { SlotsProvider } from '@/theme/SlotsProvider.js';
import { RuntimeHarness } from './RuntimeHarness.js';
@@ -65,6 +67,116 @@ describe('AssistantTextContainer', () => {
expect(screen.getByTestId('artifact-download-handler')).toHaveTextContent('function');
});
+ describe('lag-triggered markdown pacing', () => {
+ it('shows finished small markdown immediately without paced throttling', () => {
+ const commits: string[] = [];
+
+ function TrackingMarkdown({ content }: MarkdownProps) {
+ commits.push(content);
+ return <div data-testid="smooth-markdown">{content}</div>;
+ }
+
+ render(
+ <RuntimeHarness messages={[{ role: 'assistant', content: 'hello world' }]} isRunning={false}>
+ <SlotsProvider overrides={{ Markdown: TrackingMarkdown }}>
+ <ThreadPrimitive.Messages>{() => <AssistantMessageContainer />}</ThreadPrimitive.Messages>
+ </SlotsProvider>
+ </RuntimeHarness>,
+ );
+
+ expect(commits[commits.length - 1]).toBe('hello world');
+ expect(commits[commits.length - 1]!.length).toBeLessThan(MARKDOWN_SMOOTH_BACKLOG_CHARS);
+ });
+
+ it('latches paced mode after a smooth backlog and flushes on completion', async () => {
+ vi.useFakeTimers({
+ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'],
+ });
+
+ try {
+ const commits: string[] = [];
+
+ // Long mixed markdown so a running dump creates an immediate smooth backlog.
+ const line = (i: number) =>
+ i % 40 === 0 ? `\`\`\`js\nconst block_${i} = ${i};\n\`\`\`` : `Paragraph line ${i} with some filler text.`;
+ const base = Array.from({ length: 200 }, (_, i) => line(i)).join('\n');
+ expect(base.length).toBeGreaterThan(MARKDOWN_SMOOTH_BACKLOG_CHARS);
+
+ let setContent!: (value: string) => void;
+ let setRunning!: (value: boolean) => void;
+
+ function TrackingMarkdown({ content }: MarkdownProps) {
+ commits.push(content);
+ return <div data-testid="paced-markdown">{content.length}</div>;
+ }
+
+ function Case() {
+ const [content, setContentState] = useState(base);
+ const [isRunning, setIsRunningState] = useState(true);
+ setContent = setContentState;
+ setRunning = setIsRunningState;
+
+ const messages: ThreadMessageLike[] = [
+ {
+ id: 'assistant-large-md',
+ role: 'assistant',
+ content: [{ type: 'text', text: content }],
+ },
+ ];
+
+ const runtime = useExternalStoreRuntime({
+ messages,
+ isRunning,
+ convertMessage: message => message,
+ onNew: async () => {},
+ });
+
+ return (
+ <AssistantRuntimeProvider runtime={runtime}>
+ <SlotsProvider overrides={{ Markdown: TrackingMarkdown }}>
+ <ThreadPrimitive.Messages>{() => <AssistantMessageContainer />}</ThreadPrimitive.Messages>
+ </SlotsProvider>
+ </AssistantRuntimeProvider>
+ );
+ }
+
+ render(<Case />);
+
+ // Running dump starts with empty smooth cursor → backlog ≥ 4KB → paced seed to latest.
+ expect(commits[commits.length - 1]).toBe(base);
+ const afterLatchCommits = commits.length;
+
+ const grown = `${base}\nextra-${'x'.repeat(64)}`;
+ await act(async () => {
+ vi.advanceTimersByTime(10);
+ setContent(grown);
+ await Promise.resolve();
+ });
+
+ // Inside the throttle window — display must not advance yet.
+ expect(commits[commits.length - 1]).toBe(base);
+ expect(commits.length).toBe(afterLatchCommits);
+
+ await act(async () => {
+ vi.advanceTimersByTime(LARGE_MARKDOWN_THROTTLE_MS);
+ await Promise.resolve();
+ });
+ expect(commits[commits.length - 1]).toBe(grown);
+
+ const finalText = `${grown}\nDONE`;
+ await act(async () => {
+ setContent(finalText);
+ setRunning(false);
+ await Promise.resolve();
+ });
+
+ expect(commits[commits.length - 1]).toBe(finalText);
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+ });
+
it('downloads an artifact through the turn that produced the message', async () => {
const downloadSandboxFile = vi.fn(async () => new Blob(['hello harness']));
const anchorClick = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {});
diff --git a/packages/trueforge-ui-sdk/test/hooks/useThrottledMarkdownText.test.ts b/packages/trueforge-ui-sdk/test/hooks/useThrottledMarkdownText.test.ts
new file mode 100644
index 000000000..e64243055
--- /dev/null
+++ b/packages/trueforge-ui-sdk/test/hooks/useThrottledMarkdownText.test.ts
@@ -0,0 +1,89 @@
+'use client';
+
+// @vitest-environment jsdom
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { LARGE_MARKDOWN_THROTTLE_MS, useThrottledMarkdownText } from '@/hooks/useThrottledMarkdownText.js';
+
+describe('useThrottledMarkdownText', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('mirrors text immediately when pacing is disabled', () => {
+ const { result, rerender } = renderHook(
+ ({ text }) => useThrottledMarkdownText(text, { enabled: false, isComplete: false }),
+ { initialProps: { text: 'hello' } },
+ );
+
+ expect(result.current).toBe('hello');
+ rerender({ text: 'hello world' });
+ expect(result.current).toBe('hello world');
+ });
+
+ it('seeds immediately with the latest raw text when pacing activates', () => {
+ const { result, rerender } = renderHook(
+ ({ text, enabled }) => useThrottledMarkdownText(text, { enabled, isComplete: false }),
+ { initialProps: { text: 'smooth prefix', enabled: false } },
+ );
+
+ const jumped = `smooth prefix${'x'.repeat(100)}`;
+ rerender({ text: jumped, enabled: true });
+ expect(result.current).toBe(jumped);
+ });
+
+ it('holds rapid updates inside the throttle window when enabled', () => {
+ const { result, rerender } = renderHook(
+ ({ text }) =>
+ useThrottledMarkdownText(text, {
+ enabled: true,
+ isComplete: false,
+ throttleMs: LARGE_MARKDOWN_THROTTLE_MS,
+ }),
+ { initialProps: { text: 'a'.repeat(100) } },
+ );
+
+ const first = result.current;
+
+ act(() => {
+ vi.advanceTimersByTime(10);
+ });
+ rerender({ text: 'a'.repeat(200) });
+ expect(result.current).toBe(first);
+
+ act(() => {
+ vi.advanceTimersByTime(LARGE_MARKDOWN_THROTTLE_MS);
+ });
+ expect(result.current).toBe('a'.repeat(200));
+ });
+
+ it('never rewinds the committed prefix while paced', () => {
+ const { result, rerender } = renderHook(
+ ({ text }) => useThrottledMarkdownText(text, { enabled: true, isComplete: false }),
+ { initialProps: { text: 'abcdef' } },
+ );
+
+ expect(result.current).toBe('abcdef');
+ rerender({ text: 'abc' });
+ expect(result.current).toBe('abcdef');
+ });
+
+ it('flushes the exact final text when the stream completes', () => {
+ const { result, rerender } = renderHook(
+ ({ text, isComplete }) => useThrottledMarkdownText(text, { enabled: true, isComplete }),
+ { initialProps: { text: 'partial', isComplete: false } },
+ );
+
+ act(() => {
+ vi.advanceTimersByTime(10);
+ });
+ rerender({ text: 'partial final document', isComplete: true });
+
+ expect(result.current).toBe('partial final document');
+ });
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 184ffb89a..bad15286e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -58,8 +58,8 @@ importers:
specifier: 0.2.21
'@truefoundry/assistant-ui-runtime':
- specifier: 0.1.14
+ specifier: 0.1.15
'@truefoundry/trueforge-sdk':
specifier: workspace:*
version: link:../sdk
@@ -331,8 +331,8 @@ importers:
specifier: ^0.13.2
'@truefoundry/assistant-ui-runtime':
- specifier: 0.1.14
+ specifier: 0.1.15
'@truefoundry/trueforge-sdk':
specifier: workspace:*
version: link:../sdk
@@ -3359,8 +3359,8 @@ packages:
'@types/react-dom':
optional: true
- '@truefoundry/[email protected]':
- resolution: {integrity: sha512-xdFob3v6KdhUVFrDuw1OAcX6o8lsnT+kQAo82gzCgXbg3YvdIs4cDWRswZdCI83FriRieYtMc8kZPjrRysJSkQ==}
+ '@truefoundry/[email protected]':
+ resolution: {integrity: sha512-WHbQJ0pEoVNYJ5dt99powKqPqLQejpOEYX5jsLkmZMLwty1fgGYgflovXo0StD2VUAblklstL9vpwu/pqMMh/g==}
peerDependencies:
'@types/react': '*'
react: ^18 || ^19
@@ -10311,7 +10311,7 @@ snapshots:
'@types/react': 19.2.17
'@types/react-dom': 19.2.3(@types/[email protected])
dependencies:
'@assistant-ui/store': 0.2.21(@assistant-ui/[email protected](@types/[email protected])([email protected]))(@types/[email protected])([email protected])
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 116c72e22..4a6bd4275 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -16,7 +16,7 @@ allowBuilds:
# Silence peer mismatches between trueforge-ui peers and the versions we pin.
peerDependencyRules:
allowedVersions:
- '@truefoundry/assistant-ui-runtime': '0.1.14'
+ '@truefoundry/assistant-ui-runtime': '0.1.15'
# One Context module for assistant-ui (avoids "requires an AuiProvider").
overrides: