🌊 refactor: Share Canonical Chat Streaming Effects (#18203)
Some checks are pending
Backend Unit Tests / Build packages (push) Waiting to run
Backend Unit Tests / Codegraph select (push) Waiting to run
Backend Unit Tests / TypeScript type checks (push) Blocked by required conditions
Backend Unit Tests / Circular dependency checks (push) Waiting to run
Backend Unit Tests / Tests: api (shard 1/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 2/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 3/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: data-provider (push) Blocked by required conditions
Backend Unit Tests / Tests: data-schemas (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 1/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 2/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 3/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 4/4) (push) Blocked by required conditions
Backend Unit Tests / backend (push) Blocked by required conditions
Channel Gateway / gateway (push) Waiting to run
Codegraph E2E Vote Gate / Gate (push) Waiting to run
Codegraph E2E Votes / vote (shard 1/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 10/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 2/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 3/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 4/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 5/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 6/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 7/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 8/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 9/10) (push) Waiting to run
Docker Dev Branch Images Build / publish (push) Waiting to run
Frontend Unit Tests / Client build recovery regression (push) Waiting to run
Frontend Unit Tests / Codegraph select (push) Waiting to run
Frontend Unit Tests / Build packages (push) Waiting to run
Frontend Unit Tests / TypeScript type checks (client) (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/chat (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/client (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 1/2) (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 2/2) (push) Blocked by required conditions
Frontend Unit Tests / Vite build verification (push) Blocked by required conditions
Frontend Unit Tests / frontend (push) Blocked by required conditions
Playwright E2E Tests / Codegraph select (push) Waiting to run
Playwright E2E Tests / Shard timings (push) Waiting to run
Playwright E2E Tests / e2e () (push) Blocked by required conditions
Playwright E2E Tests / MCP list_changed (replica count 1) (push) Blocked by required conditions
Playwright E2E Tests / MCP list_changed (replica count 2) (push) Blocked by required conditions
Playwright E2E Tests / MCP Apps (browser and server) (push) Waiting to run
Playwright E2E Tests / e2e (push) Blocked by required conditions
Playwright Shard Timings / Record shard timings (push) Waiting to run

Move the existing streaming fade engine into @librechat/chat and its waiting-dot, cursor and fade styles into the shared client stylesheet.

Use the effective host smoothing policy consistently in Markdown, including nested subagent content, while preserving optional renderer callbacks and raw fallback behavior.
This commit is contained in:
Marco Beretta 2026-11-16 06:18:42 +01:00 • committed by GitHub
parent 2d2eced9b7
commit 2cdbb59160
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 838 additions and 613 deletions

View file

@ -2,6 +2,7 @@ import { useCallback, useMemo } from 'react';
import { useAtomValue, useSetAtom } from 'jotai';
import { useToastContext } from '@librechat/client';
import { dataService } from 'librechat-data-provider';
import { AnimatedText } from '@librechat/chat/components';
import { setDefaultMessagePartsHost, pendingSteersByConvoId } from '@librechat/chat/react';
import {
liveAppliedSteerFamily,
@ -44,7 +45,6 @@ import ToolIcon, { getToolIconType } from '~/components/Chat/Messages/Content/To
import { getToolCallAttachments } from '~/components/Chat/Messages/Content/toolCallAttachment';
import ProgressText from '~/components/Chat/Messages/Content/ProgressText';
import ToolCallInfo from '~/components/Chat/Messages/Content/ToolCallInfo';
import { AnimatedText } from '~/components/Chat/Messages/Content/animate';
import useSmoothStreaming from '~/hooks/Messages/useSmoothStreaming';
import { ptcTraceByToolCallId, ptcTraceKey } from '~/hooks/SSE/ptc';
import { sandboxStartingByToolCallId } from '~/hooks/SSE/sandbox';

View file

@ -1,9 +1,8 @@
import React, { memo, useRef, useEffect } from 'react';
import { FADE_HYDRATION_THRESHOLD } from '@librechat/chat/components';
import { getRemarkPlugins, getRehypePlugins, getMarkdownComponents } from './markdownConfig';
import { useMessagePartsHost } from '~/Providers/MessagePartsHostContext';
import useSmoothStreaming from '~/hooks/Messages/useSmoothStreaming';
import MarkdownErrorBoundary from './MarkdownErrorBoundary';
import { FADE_HYDRATION_THRESHOLD } from './animate';
import MarkdownBlocks from './MarkdownBlocks';
import { useRehypeModules } from './rehype';
@ -13,7 +12,7 @@ type TContentProps = {
};
const Markdown = memo(function Markdown({ content = '', isLatestMessage }: TContentProps) {
const { useMessage, useLaTeXParsing } = useMessagePartsHost();
const { useMessage, useLaTeXParsing, useSmoothStreaming } = useMessagePartsHost();
const { isSubmitting = false } = useMessage();
const smoothStreaming = useSmoothStreaming();
const LaTeXParsing = useLaTeXParsing();

View file

@ -1,11 +1,12 @@
import React, { memo, useMemo, useState, useLayoutEffect } from 'react';
import ReactMarkdown from 'react-markdown';
import { createMarkdownSplitter } from '@librechat/chat';
import { createFadePlugin } from '@librechat/chat/components';
import type { MarkdownSplitter } from '@librechat/chat';
import type { Options } from 'react-markdown';
import type { PluggableList } from 'unified';
import type { ElementType } from 'react';
import { ArtifactProvider, CodeBlockProvider } from '~/Providers';
import { createFadePlugin } from './animate';
type SharedProps = {
remarkPlugins: PluggableList;
@ -54,7 +55,10 @@ const MarkdownBlock = memo(
[animate],
);
const blockRehypePlugins = useMemo(
() => (fade == null ? rehypePlugins : [...rehypePlugins, fade.plugin]),
() =>
fade == null
? rehypePlugins
: [...rehypePlugins, fade.plugin satisfies NonNullable<Options['rehypePlugins']>[number]],
[fade, rehypePlugins],
);
useLayoutEffect(() => {

View file

@ -1,19 +1,19 @@
import React from 'react';
import { RecoilRoot } from 'recoil';
import { useAtomValue } from 'jotai';
import { activeSubagentPanel } from '@librechat/chat/react';
import { SubagentConversation } from '@librechat/chat/components';
import { Constants, ContentTypes } from 'librechat-data-provider';
import { fireEvent, render, screen } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { activeSubagentPanel, MessagePartsHostProvider } from '@librechat/chat/react';
import type { TAgentsMap, TAttachment } from 'librechat-data-provider';
import type { ActiveSubagentPanel } from '@librechat/chat/react';
import { appMessagePartsHost } from '~/Providers/MessagePartsHostContext';
import { AgentsMapContext } from '~/Providers/AgentsMapContext';
import { MessageContext } from '~/Providers/MessageContext';
import { ShareContext } from '~/Providers/ShareContext';
import { ChatSurfaceHarness } from 'test/harness';
import SubagentCall from '../SubagentCall';
import '~/Providers/MessagePartsHostContext';
import '~/Providers/SubagentsHostContext';
import '~/components/Chat/Messages/hosts';
@ -32,7 +32,7 @@ function renderCard(ui: React.ReactElement, share?: { isSharedConvo?: boolean; s
return null;
};
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
render(
const rendered = render(
<RecoilRoot>
<QueryClientProvider client={queryClient}>
<ChatSurfaceHarness>
@ -54,7 +54,7 @@ function renderCard(ui: React.ReactElement, share?: { isSharedConvo?: boolean; s
</QueryClientProvider>
</RecoilRoot>,
);
return { getSelection: () => selection };
return { ...rendered, getSelection: () => selection };
}
describe('app subagent call adapter', () => {
@ -127,6 +127,44 @@ describe('app subagent call adapter', () => {
);
});
it.each([
[true, 'running'],
[false, 'running'],
[true, 'cancelled'],
[true, 'completed'],
] as const)('uses the effective host fade policy in a child (%s, %s)', (smooth, status) => {
const host = { ...appMessagePartsHost, useSmoothStreaming: () => smooth };
const { container } = renderCard(
<MessagePartsHostProvider host={host}>
<SubagentConversation
conversationId="live-child"
author={{ name: 'Child', icon: null }}
parentAuthor={{ name: 'Parent', icon: null }}
turns={[
{
taskId: 'live-task',
trigger: { kind: 'parent_dispatch', summary: '', createdAt: '2026-11-14T12:00:00Z' },
activity: {
title: 'Child',
status,
items: [],
messageId: 'live-child-message',
content: [{ type: ContentTypes.TEXT, text: 'Child streaming words' }],
},
},
]}
/>
</MessagePartsHostProvider>,
);
expect(container).toHaveTextContent('Child streaming words');
expect(container.querySelectorAll('[data-lc-fade]').length > 0).toBe(
smooth && status === 'running',
);
expect(container.querySelector('.result-streaming') !== null).toBe(
!smooth && status === 'running',
);
});
it('keeps a shared detached card closed when the share host has no persisted activity', () => {
const output = JSON.stringify({
background_task_id: 'task-1',

View file

@ -1,13 +1,9 @@
import React from 'react';
import ReactMarkdown from 'react-markdown';
import { render } from '@testing-library/react';
import type { ComponentProps } from 'react';
import type { FadePlugin } from '../animate';
import {
splitWords,
beginRun,
endRun,
classifyValue,
createFadeState,
createFadePlugin,
AnimatedText,
FADE_DURATION_MS,
@ -15,6 +11,13 @@ import {
FADE_STAGGER_MAX_MS,
FADE_HYDRATION_THRESHOLD,
} from '../animate';
import {
splitWords,
beginRun,
endRun,
classifyValue,
createFadeState,
} from '../../../../../../../packages/chat/src/components/fade';
let nowSpy: jest.SpyInstance<number, []>;
let mockedNow = 0;
@ -146,8 +149,13 @@ describe('classifyValue', () => {
describe('createFadePlugin', () => {
const renderMarkdown = (fade: FadePlugin, content: string) => (
/** @ts-ignore */
<ReactMarkdown rehypePlugins={[fade.plugin]}>{content}</ReactMarkdown>
<ReactMarkdown
rehypePlugins={
[fade.plugin] satisfies NonNullable<ComponentProps<typeof ReactMarkdown>['rehypePlugins']>
}
>
{content}
</ReactMarkdown>
);
it('wraps words in fade spans on first render, including inline formatting', () => {

View file

@ -1,440 +1,9 @@
import { memo, useRef, Fragment, useLayoutEffect } from 'react';
import type { Root, Element, ElementContent } from 'hast';
import type { CSSProperties } from 'react';
import type { Plugin } from 'unified';
/** Must match the animation duration on `[data-lc-fade]` in style.css */
export const FADE_DURATION_MS = 250;
export const FADE_STAGGER_MS = 25;
export const FADE_STAGGER_MAX_MS = 250;
/**
* Text already longer than this when animation starts is hydrated/resumed
* content (reconnected stream, conversation switch, follow-up turn), not a
* fresh delta — that content becomes the baseline instead of re-fading. The
* markdown path evaluates this against the whole message when its `animate`
* gate flips on; `AnimatedText` evaluates it against its own first text.
*/
export const FADE_HYDRATION_THRESHOLD = 120;
type FadeEntry = { at: number; delay: number };
type PendingRun = {
prevCount: number;
additions: Map<number, FadeEntry>;
now: number;
};
export type FadeState = {
/** Total characters classified during the last committed run; parts below this offset are not new */
prevCount: number;
/** Parts still mid-animation, keyed by start offset, so re-renders replay identical props */
active: Map<number, FadeEntry>;
/** True until the first run commits; used for the hydration baseline decision */
firstRun: boolean;
/** Staged result of the latest render, published to the fields above on commit */
pending: PendingRun | null;
};
type FadeRun = {
state: FadeState;
now: number;
count: number;
newIndex: number;
/** Baseline mode: classify everything as already seen (hydrated first run) */
suppress: boolean;
additions: Map<number, FadeEntry>;
};
export type FadeSegment = {
start: number;
value: string;
animated: boolean;
delay: number;
};
const WORD_REGEX = /\S+\s*/g;
const NON_WHITESPACE_REGEX = /\S/;
/**
* Scripts written without word-delimiting spaces: Thai, Lao, Myanmar, Khmer,
* Tibetan, CJK ideographs/kana, Hangul, and CJK compatibility ideographs.
* Whitespace splitting yields one ever-growing part for these, which would
* stop fading once its window expires, so they go through Intl.Segmenter.
*/
const SPACELESS_REGEX =
/[\u0E00-\u0EFF\u0F00-\u0FFF\u1000-\u109F\u1780-\u17FF\u2E80-\u9FFF\uAC00-\uD7AF\uF900-\uFAFF]/;
let wordSegmenter: Intl.Segmenter | null | undefined;
let graphemeSegmenter: Intl.Segmenter | null | undefined;
function createSegmenter(granularity: 'word' | 'grapheme'): Intl.Segmenter | null {
return typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function'
? new Intl.Segmenter(undefined, { granularity })
: null;
}
function getWordSegmenter(): Intl.Segmenter | null {
if (wordSegmenter === undefined) {
wordSegmenter = createSegmenter('word');
}
return wordSegmenter;
}
function getGraphemeSegmenter(): Intl.Segmenter | null {
if (graphemeSegmenter === undefined) {
graphemeSegmenter = createSegmenter('grapheme');
}
return graphemeSegmenter;
}
function pushSegmentedParts(parts: string[], token: string): void {
const segmenter = getWordSegmenter();
if (segmenter == null) {
parts.push(token);
return;
}
const trailing = /\s+$/.exec(token);
const word = trailing == null ? token : token.slice(0, trailing.index);
for (const segment of segmenter.segment(word)) {
parts.push(segment.segment);
}
if (trailing != null) {
parts.push(trailing[0]);
}
}
/**
* Splits text into word parts, each a non-whitespace run plus its trailing
* whitespace, with whitespace-only runs kept as separate parts. Scripts
* without word-delimiting spaces (CJK) are further split via Intl.Segmenter.
* Concatenating the result always reproduces the input exactly.
*/
export function splitWords(value: string): string[] {
const parts: string[] = [];
WORD_REGEX.lastIndex = 0;
let index = 0;
let match: RegExpExecArray | null;
while ((match = WORD_REGEX.exec(value)) !== null) {
if (match.index > index) {
parts.push(value.slice(index, match.index));
}
const token = match[0];
if (SPACELESS_REGEX.test(token)) {
pushSegmentedParts(parts, token);
} else {
parts.push(token);
}
index = match.index + token.length;
}
if (index < value.length) {
parts.push(value.slice(index));
}
return parts;
}
export function createFadeState(): FadeState {
return { prevCount: 0, active: new Map(), firstRun: true, pending: null };
}
export function beginRun(state: FadeState, suppress = false): FadeRun {
return {
state,
now: performance.now(),
count: 0,
newIndex: 0,
suppress,
additions: new Map(),
};
}
/**
* Stages the run's result on the state without publishing it. Classification
* never mutates committed state during render, so a render that React
* abandons (concurrent interruption, StrictMode double-render) leaves no
* trace; only {@link commitRun} — called after the render commits — publishes.
*/
export function stageRun(run: FadeRun): void {
run.state.pending = { prevCount: run.count, additions: run.additions, now: run.now };
}
/** Publishes the staged run: baseline offset, new animations, pruned entries. */
export function commitRun(state: FadeState): void {
const pending = state.pending;
if (pending == null) {
return;
}
state.pending = null;
state.firstRun = false;
state.prevCount = pending.prevCount;
for (const [start, entry] of pending.additions) {
state.active.set(start, entry);
}
for (const [start, entry] of state.active) {
if (pending.now - entry.at >= entry.delay + FADE_DURATION_MS) {
state.active.delete(start);
}
}
}
/** Stages and immediately commits — for callers without a commit phase. */
export function endRun(run: FadeRun): void {
stageRun(run);
commitRun(run.state);
}
/**
* Classifies one text value into fade segments, advancing the run's
* document-order character offset. A part is animated when it starts past the
* last committed run's total offset (newly streamed) or when it is still
* within its animation window from an earlier run — in which case it replays
* identical animation props so React leaves the in-flight CSS animation
* untouched. Committed state is only read here; new animations are recorded
* on the run and published by {@link commitRun}.
*/
export function classifyValue(run: FadeRun, value: string): FadeSegment[] {
const { state, now } = run;
const segments: FadeSegment[] = [];
for (const part of splitWords(value)) {
const start = run.count;
run.count += part.length;
if (run.suppress || !NON_WHITESPACE_REGEX.test(part)) {
segments.push({ start, value: part, animated: false, delay: 0 });
continue;
}
if (start >= state.prevCount) {
const staged = run.additions.get(start);
const delay = staged?.delay ?? Math.min(run.newIndex * FADE_STAGGER_MS, FADE_STAGGER_MAX_MS);
run.newIndex += 1;
run.additions.set(start, staged ?? { at: now, delay });
segments.push({ start, value: part, animated: true, delay });
continue;
}
const entry = state.active.get(start);
if (entry != null && now - entry.at < entry.delay + FADE_DURATION_MS) {
segments.push({ start, value: part, animated: true, delay: entry.delay });
continue;
}
segments.push({ start, value: part, animated: false, delay: 0 });
}
return segments;
}
const SKIP_TAGS = new Set([
'code',
'pre',
'svg',
'math',
'annotation',
'script',
'style',
'artifact',
'citation',
'composite-citation',
'highlighted-text',
'mcp-ui-resource',
'mcp-ui-carousel',
]);
function isSkippedElement(node: Element): boolean {
if (SKIP_TAGS.has(node.tagName)) {
return true;
}
const className = node.properties?.className;
if (Array.isArray(className)) {
return className.some((name) => typeof name === 'string' && name.startsWith('katex'));
}
return typeof className === 'string' && className.startsWith('katex');
}
function toContent(segment: FadeSegment): ElementContent {
if (!NON_WHITESPACE_REGEX.test(segment.value)) {
return { type: 'text', value: segment.value };
}
const properties: Element['properties'] = {};
if (segment.animated) {
properties.dataLcFade = '';
if (segment.delay > 0) {
properties.style = `--lc-delay:${segment.delay}ms`;
}
}
return {
type: 'element',
tagName: 'span',
properties,
children: [{ type: 'text', value: segment.value }],
};
}
function transformElement(run: FadeRun, element: Element): void {
const next: ElementContent[] = [];
for (const child of element.children) {
if (child.type === 'text') {
for (const segment of classifyValue(run, child.value)) {
next.push(toContent(segment));
}
continue;
}
if (child.type === 'element' && !isSkippedElement(child)) {
transformElement(run, child);
}
next.push(child);
}
element.children = next;
}
export type FadePlugin = {
plugin: Plugin<[], Root>;
/** Publish the latest render's staged classification; call after React commits. */
commit: () => void;
};
/**
* Creates a per-renderer rehype plugin that wraps newly streamed words in
* one-shot CSS fade spans (`[data-lc-fade]`). New-text detection uses
* document-order character offsets held in the factory closure, so text that
* was already visible in a previous render mounts as a bare span and never
* re-animates, even when markdown re-parsing restructures the tree. Pass
* `hydrated: true` for renderers created while previously accumulated content
* is already showing (resumed stream, conversation switch, follow-up turn):
* their first run becomes the baseline without animating. Classification is
* staged during render and must be published via `commit()` after React
* commits (a layout effect), so abandoned renders leave no trace. Create one
* instance per streaming renderer and drop it (plain plugin array) once the
* stream ends so the settled message renders without wrapper spans.
*/
export function createFadePlugin(hydrated = false): FadePlugin {
const state = createFadeState();
const plugin: Plugin<[], Root> = function rehypeFade() {
return (tree: Root) => {
const run = beginRun(state, hydrated && state.firstRun);
for (const child of tree.children) {
if (child.type === 'element' && !isSkippedElement(child)) {
transformElement(run, child);
}
}
stageRun(run);
};
};
return { plugin, commit: () => commitRun(state) };
}
const DELAY_VAR = '--lc-delay';
const WHITESPACE_REGEX = /\s/;
const PREFIX_PROBE_LENGTH = 32;
/**
* Longest trailing run kept unsettled. Bounds per-token work when the last
* word never reaches whitespace (CJK, Thai, unspaced Hangul, URLs). Only
* settled, non-animated text is cut, and it renders as plain text on both
* sides of the cut, so a cut inside a part is invisible.
*/
const MAX_UNSETTLED_LENGTH = 64;
/**
* Moves a cut offset in `tail` back to a grapheme-cluster boundary, so emoji
* modifier, flag, ZWJ and combining sequences stay whole. `tail` starts at the
* committed settled boundary, which is itself a cluster boundary, and is
* bounded by the cap, so segmenting it stays proportional to the unsettled text.
* Without a grapheme segmenter there is no safe cut, so the cap is not applied.
*/
function glyphBoundary(tail: string, index: number): number {
const segmenter = getGraphemeSegmenter();
if (index <= 0 || segmenter == null) {
return 0;
}
let boundary = 0;
for (const segment of segmenter.segment(tail)) {
if (segment.index > index) {
break;
}
boundary = segment.index;
}
return boundary;
}
/** Offset of the last whitespace-delimited word, which appended text can still extend. */
function lastWordStart(value: string): number {
let index = value.length;
while (index > 0 && WHITESPACE_REGEX.test(value[index - 1])) {
index -= 1;
}
while (index > 0 && !WHITESPACE_REGEX.test(value[index - 1])) {
index -= 1;
}
return index;
}
/**
* Whether `text` still extends the settled `prefix`. Probes only the prefix's
* head and the region at its boundary so the per-token check stays constant
* rather than rescanning the whole accumulated prefix; an append-only stream
* always passes, and a rewrite that shifts or replaces text fails a probe. The
* settled region is always rendered from the current text, so a rewrite that
* slips past the probes can only affect fade timing, never the characters shown.
*/
function extendsPrefix(text: string, prefix: string): boolean {
if (text.length < prefix.length) {
return false;
}
const probe = Math.min(PREFIX_PROBE_LENGTH, prefix.length);
const boundary = prefix.length - probe;
return (
text.startsWith(prefix.slice(0, probe)) && text.startsWith(prefix.slice(boundary), boundary)
);
}
/**
* Plain-text counterpart of the rehype plugin for non-markdown streamed text
* (reasoning). Renders words in fade spans keyed by character offset; only
* render this while the text is actively streaming and render the raw string
* once settled. Classification is append-only: the leading run of parts that
* finished fading collapses into a single committed text node and is never
* re-split, so each streamed token costs work proportional to the unsettled
* tail rather than the accumulated text. The settled boundary never passes a
* word that is still fading, and stops before the last word (which appended
* text can still extend) unless that word outgrows MAX_UNSETTLED_LENGTH.
*/
export const AnimatedText = memo(function AnimatedText({ text }: { text: string }) {
const stateRef = useRef<FadeState | null>(null);
const settledRef = useRef('');
if (stateRef.current == null) {
stateRef.current = createFadeState();
}
const state = stateRef.current;
const settledLength = extendsPrefix(text, settledRef.current) ? settledRef.current.length : 0;
const settled = text.slice(0, settledLength);
const tail = text.slice(settledLength);
const suppress = state.firstRun && text.length > FADE_HYDRATION_THRESHOLD;
const run = beginRun(state, suppress);
run.count = settledLength;
const segments = classifyValue(run, tail);
stageRun(run);
const limit = Math.max(
settledLength + lastWordStart(tail),
settledLength + glyphBoundary(tail, tail.length - MAX_UNSETTLED_LENGTH),
);
const firstAnimated = segments.find((segment) => segment.animated);
const nextSettledLength = Math.min(limit, firstAnimated?.start ?? limit);
useLayoutEffect(() => {
commitRun(state);
settledRef.current = text.slice(0, nextSettledLength);
});
return (
<>
{settled}
{segments.map((segment) => {
if (!segment.animated) {
return <Fragment key={segment.start}>{segment.value}</Fragment>;
}
const style =
segment.delay > 0 ? ({ [DELAY_VAR]: `${segment.delay}ms` } as CSSProperties) : undefined;
return (
<span key={segment.start} data-lc-fade="" style={style}>
{segment.value}
</span>
);
})}
</>
);
});
AnimatedText.displayName = 'AnimatedText';
export {
AnimatedText,
createFadePlugin,
FADE_DURATION_MS,
FADE_STAGGER_MS,
FADE_STAGGER_MAX_MS,
FADE_HYDRATION_THRESHOLD,
} from '@librechat/chat/components';
export type { FadePlugin } from '@librechat/chat/components';

View file

@ -1414,48 +1414,6 @@ html {
}
}
/* Pre-response dot: enters on the streamed-text fade curve, then breathes
on opacity — replaces the legacy scale throb so waiting and text arrival
share one motion language.
Custom CSS exception: this indicator is a `::after` pseudo-element on the
`.result-thinking` hook, shown only while an ancestor carries `.submitting`
and the hook itself is `:empty`. No `@librechat/client` primitive can
express "render only while an ancestor is in state X and I have no
children" — a component would have to own that state, which the streaming
markdown path deliberately keeps in the DOM so the dot costs no React
renders per token. Scoped to the one selector, colored from
`--text-primary` so both themes follow, and disabled under
prefers-reduced-motion. */
@keyframes lc-dot-breathe {
0%,
100% {
opacity: 1;
}
50% {
opacity: 0.3;
}
}
.submitting .result-thinking:empty:last-child:after {
animation:
lc-fade-in 250ms ease-out both,
lc-dot-breathe 1.5s ease-in-out 250ms infinite;
background-color: rgb(var(--text-primary));
border-radius: 50%;
content: ' ';
display: block;
height: 0.75rem;
position: absolute;
top: -0.6875rem;
width: 0.75rem;
}
@media (prefers-reduced-motion: reduce) {
.submitting .result-thinking:empty:last-child:after {
animation: none;
}
}
.avatar-stroke {
position: relative;
}
@ -1522,115 +1480,6 @@ html {
--tw-shadow-colored: inset 0 0 0 0 1px var(--tw-shadow-color);
}
.result-streaming > :not(ol):not(ul):not(pre):last-child:after,
.result-streaming > pre:last-child code:after {
display: inline-block;
content: '⬤';
width: 0.75rem;
height: 0.75rem;
font-family:
system-ui,
Inter,
Söhne Circle,
-apple-system,
Segoe UI,
Roboto,
Ubuntu,
Cantarell,
Noto Sans,
sans-serif;
line-height: normal;
margin-inline-start: 0.25rem;
vertical-align: middle;
font-size: 0.5rem;
}
@supports (selector(:has(*))) {
.result-streaming > :is(ul, ol):last-child > li:last-child:not(:has(> :is(ul, ol, pre))):after {
content: '⬤';
font-family:
system-ui,
Inter,
Söhne Circle,
-apple-system,
Segoe UI,
Roboto,
Ubuntu,
Cantarell,
Noto Sans,
sans-serif;
line-height: normal;
margin-inline-start: 0.25rem;
vertical-align: middle;
font-size: 0.5rem;
display: inline-block;
width: 0.75rem;
height: 0.75rem;
}
}
@supports not (selector(:has(*))) {
.result-streaming > ol:last-child > li:last-child:after,
.result-streaming > ul:last-child > li:last-child:after {
content: '⬤';
font-family:
system-ui,
Inter,
Söhne Circle,
-apple-system,
Segoe UI,
Roboto,
Ubuntu,
Cantarell,
Noto Sans,
sans-serif;
line-height: normal;
margin-inline-start: 0.25rem;
vertical-align: middle;
font-size: 0.5rem;
display: inline-block;
width: 0.75rem;
height: 0.75rem;
}
.result-streaming > ol:last-child > li:last-child > :is(ul, ol, pre) ~ :after,
.result-streaming > ul:last-child > li:last-child > :is(ul, ol, pre) ~ :after {
display: none;
}
.result-streaming > ol:last-child > li:last-child > pre:last-child code:after,
.result-streaming > ul:last-child > li:last-child > pre:last-child code:after {
display: inline-block;
}
}
/* Remove cursors when streaming is complete */
.result-streaming:not(.submitting) :is(ul, ol) li:after {
display: none !important;
}
/* Smooth streaming: one-shot fade-in on newly streamed words.
Duration must match FADE_DURATION_MS in Chat/Messages/Content/animate.tsx */
@keyframes lc-fade-in {
from {
opacity: 0;
}
to {
opacity: 1;
}
}
[data-lc-fade] {
animation: lc-fade-in 250ms ease-out both;
animation-delay: var(--lc-delay, 0ms);
}
@media (prefers-reduced-motion: reduce) {
[data-lc-fade] {
animation: none;
}
}
/* Ordered Listing */
.prose :where(ol[type='A']):not(:where([class~='not-prose'] *)) {
list-style-type: upper-alpha;

View file

@ -1,4 +1,5 @@
import { expect, test } from '@playwright/test';
import type { Page } from '@playwright/test';
import {
MOCK_ENDPOINTS,
NEW_CHAT_PATH,
@ -36,6 +37,45 @@ test.describe('streaming markdown blocks', () => {
await expect(assistantMessage).toContainText('日本語');
});
const checkStreamingFade = async (page: Page, reducedMotion: 'no-preference' | 'reduce') => {
await page.emulateMedia({ reducedMotion });
await page.goto(NEW_CHAT_PATH, { timeout: 10_000 });
await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);
expect((await sendMessage(page, 'E2E_STREAMING_MARKDOWN_REPLY')).ok()).toBeTruthy();
const message = messagesView(page).locator('.message-render').last();
await expect(page.getByRole('button', { name: 'Stop generating' })).toBeVisible();
if (reducedMotion === 'reduce') {
await expect(message.locator('.result-streaming')).toBeVisible();
await expect(message.locator('[data-lc-fade]')).toHaveCount(0);
} else {
await expect(message.locator('[data-lc-fade]').first()).toBeAttached();
await expect(message.locator('.result-streaming')).toHaveCount(0);
expect(
await message
.locator('[data-lc-fade]')
.first()
.evaluate((element) => getComputedStyle(element).animationName),
).toBe('lc-fade-in');
}
await expect(message.getByText('E2E streaming markdown final paragraph.')).toBeVisible({
timeout: 60_000,
});
await expect(page.getByRole('button', { name: 'Stop generating' })).toHaveCount(0);
await expect(message.locator('[data-lc-fade], .result-streaming')).toHaveCount(0);
};
test('respects normal motion for streaming fade and cursor @scenario:streaming-fade-no-preference', async ({
page,
}) => {
await checkStreamingFade(page, 'no-preference');
});
test('respects reduced motion for streaming fade and cursor @scenario:streaming-fade-reduce', async ({
page,
}) => {
await checkStreamingFade(page, 'reduce');
});
test('isolates markdown blocks across concurrent conversations @scenario:concurrent-streams-keep-message-blocks-isolated', async ({
page,
context,

View file

@ -265,11 +265,6 @@
"count": 1
}
},
"client/src/components/Chat/Messages/Content/animate.tsx": {
"shadcn/no-inline-styles": {
"count": 1
}
},
"client/src/components/Chat/Messages/Content/verticals.tsx": {
"shadcn/no-inline-styles": {
"count": 1

74
package-lock.json generated
View file

@ -43249,6 +43249,7 @@
"@tanstack/react-query": "^4.28.0",
"@testing-library/jest-dom": "^5.16.5",
"@testing-library/react": "^14.0.0",
"@types/hast": "^3.0.4",
"@types/jest": "^29.5.2",
"@types/react": "^18.2.11",
"babel-plugin-replace-ts-export-assignment": "^0.0.2",
@ -43275,6 +43276,7 @@
"rimraf": "^6.1.3",
"tsdown": "0.22.2",
"typescript": "^5.9.3",
"unified": "^11.0.5",
"uuid": "^11.1.1"
},
"peerDependencies": {
@ -43282,6 +43284,7 @@
"@librechat/client": "*",
"@radix-ui/react-dialog": "^1.1.23",
"@tanstack/react-query": "^4.28.0",
"@types/hast": "^3.0.4",
"framer-motion": "^12.40.0",
"jotai": "^2.12.5",
"librechat-data-provider": "*",
@ -43298,6 +43301,7 @@
"react-dnd": "^16.0.1",
"react-dnd-html5-backend": "^16.0.1",
"react-dom": "^18.2.0 || ^19.1.0",
"unified": "^11.0.5",
"uuid": "^11.1.1"
}
},
@ -43645,6 +43649,19 @@
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/chat/node_modules/@types/hast": {
"version": "3.0.4",
"resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz",
"integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==",
"dependencies": {
"@types/unist": "*"
}
},
"packages/chat/node_modules/@types/unist": {
"version": "3.0.3",
"resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz",
"integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q=="
},
"packages/chat/node_modules/get-tsconfig": {
"version": "5.0.0-beta.5",
"resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-5.0.0-beta.5.tgz",
@ -43825,6 +43842,63 @@
}
}
},
"packages/chat/node_modules/unified": {
"version": "11.0.5",
"resolved": "https://registry.npmjs.org/unified/-/unified-11.0.5.tgz",
"integrity": "sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==",
"dependencies": {
"@types/unist": "^3.0.0",
"bail": "^2.0.0",
"devlop": "^1.0.0",
"extend": "^3.0.0",
"is-plain-obj": "^4.0.0",
"trough": "^2.0.0",
"vfile": "^6.0.0"
},
"funding": {
"type": "opencollective",
"url": "https://opencollective.com/unified"
}
},
"packages/chat/node_modules/unist-util-stringify-position": {
"version": "4.0.0",
"resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz",
"integrity": "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==",
"dependencies": {
"@types/unist": "^3.0.0"
},
"funding": {
"type": "opencollective",
"url": "https://opencollective.com/unified"
}
},
"packages/chat/node_modules/vfile": {
"version": "6.0.2",
"resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.2.tgz",
"integrity": "sha512-zND7NlS8rJYb/sPqkb13ZvbbUoExdbi4w3SfRrMq6R3FvnLQmmfpajJNITuuYm6AZ5uao9vy4BAos3EXBPf2rg==",
"dependencies": {
"@types/unist": "^3.0.0",
"unist-util-stringify-position": "^4.0.0",
"vfile-message": "^4.0.0"
},
"funding": {
"type": "opencollective",
"url": "https://opencollective.com/unified"
}
},
"packages/chat/node_modules/vfile-message": {
"version": "4.0.2",
"resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-4.0.2.tgz",
"integrity": "sha512-jRDZ1IMLttGj41KcZvlrYAaI3CfqpLpfpf+Mfig13viT6NKvRzWZ+lXz0Y5D60w6uJIBAOGq9mSHf0gktF0duw==",
"dependencies": {
"@types/unist": "^3.0.0",
"unist-util-stringify-position": "^4.0.0"
},
"funding": {
"type": "opencollective",
"url": "https://opencollective.com/unified"
}
},
"packages/client": {
"name": "@librechat/client",
"version": "0.4.85",

View file

@ -62,6 +62,7 @@
"@librechat/client": "*",
"@radix-ui/react-dialog": "^1.1.23",
"@tanstack/react-query": "^4.28.0",
"@types/hast": "^3.0.4",
"framer-motion": "^12.40.0",
"jotai": "^2.12.5",
"librechat-data-provider": "*",
@ -78,6 +79,7 @@
"react-dnd": "^16.0.1",
"react-dnd-html5-backend": "^16.0.1",
"react-dom": "^18.2.0 || ^19.1.0",
"unified": "^11.0.5",
"uuid": "^11.1.1"
},
"dependencies": {
@ -94,6 +96,7 @@
"@tanstack/react-query": "^4.28.0",
"@testing-library/jest-dom": "^5.16.5",
"@testing-library/react": "^14.0.0",
"@types/hast": "^3.0.4",
"@types/jest": "^29.5.2",
"@types/react": "^18.2.11",
"babel-plugin-replace-ts-export-assignment": "^0.0.2",
@ -120,6 +123,7 @@
"rimraf": "^6.1.3",
"tsdown": "0.22.2",
"typescript": "^5.9.3",
"unified": "^11.0.5",
"uuid": "^11.1.1"
}
}

View file

@ -16,6 +16,16 @@ export type {
ToolRenderProps,
} from './components/Part';
export {
AnimatedText,
createFadePlugin,
FADE_DURATION_MS,
FADE_STAGGER_MS,
FADE_STAGGER_MAX_MS,
FADE_HYDRATION_THRESHOLD,
} from './components/fade';
export type { FadePlugin } from './components/fade';
/** Composer: the chat input, its controls and the steering queue. */
export { default as BrowserAudio } from './components/composer/Audio';
export type { BrowserAudioProps } from './components/composer/Audio';

View file

@ -0,0 +1,444 @@
/// <reference lib="es2022.intl" />
import { memo, useRef, Fragment, useLayoutEffect } from 'react';
import type { CSSProperties, NamedExoticComponent } from 'react';
import type { Root, Element, ElementContent } from 'hast';
import type { Plugin } from 'unified';
/** Must match the animation duration on `[data-lc-fade]` in @librechat/client theme/parts.css */
export const FADE_DURATION_MS = 250;
export const FADE_STAGGER_MS = 25;
export const FADE_STAGGER_MAX_MS = 250;
/**
* Text already longer than this when animation starts is hydrated/resumed
* content (reconnected stream, conversation switch, follow-up turn), not a
* fresh delta; that content becomes the baseline instead of re-fading. The
* markdown path evaluates this against the whole message when its `animate`
* gate flips on; `AnimatedText` evaluates it against its own first text.
*/
export const FADE_HYDRATION_THRESHOLD = 120;
type FadeEntry = { at: number; delay: number };
type PendingRun = {
prevCount: number;
additions: Map<number, FadeEntry>;
now: number;
};
export type FadeState = {
/** Total characters classified during the last committed run; parts below this offset are not new */
prevCount: number;
/** Parts still mid-animation, keyed by start offset, so re-renders replay identical props */
active: Map<number, FadeEntry>;
/** True until the first run commits; used for the hydration baseline decision */
firstRun: boolean;
/** Staged result of the latest render, published to the fields above on commit */
pending: PendingRun | null;
};
type FadeRun = {
state: FadeState;
now: number;
count: number;
newIndex: number;
/** Baseline mode: classify everything as already seen (hydrated first run) */
suppress: boolean;
additions: Map<number, FadeEntry>;
};
export type FadeSegment = {
start: number;
value: string;
animated: boolean;
delay: number;
};
const WORD_REGEX = /\S+\s*/g;
const NON_WHITESPACE_REGEX = /\S/;
/**
* Scripts written without word-delimiting spaces: Thai, Lao, Myanmar, Khmer,
* Tibetan, CJK ideographs/kana, Hangul, and CJK compatibility ideographs.
* Whitespace splitting yields one ever-growing part for these, which would
* stop fading once its window expires, so they go through Intl.Segmenter.
*/
const SPACELESS_REGEX =
/[\u0E00-\u0EFF\u0F00-\u0FFF\u1000-\u109F\u1780-\u17FF\u2E80-\u9FFF\uAC00-\uD7AF\uF900-\uFAFF]/;
let wordSegmenter: Intl.Segmenter | null | undefined;
let graphemeSegmenter: Intl.Segmenter | null | undefined;
function createSegmenter(granularity: 'word' | 'grapheme'): Intl.Segmenter | null {
return typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function'
? new Intl.Segmenter(undefined, { granularity })
: null;
}
function getWordSegmenter(): Intl.Segmenter | null {
if (wordSegmenter === undefined) {
wordSegmenter = createSegmenter('word');
}
return wordSegmenter;
}
function getGraphemeSegmenter(): Intl.Segmenter | null {
if (graphemeSegmenter === undefined) {
graphemeSegmenter = createSegmenter('grapheme');
}
return graphemeSegmenter;
}
function pushSegmentedParts(parts: string[], token: string): void {
const segmenter = getWordSegmenter();
if (segmenter == null) {
parts.push(token);
return;
}
const trailing = /\s+$/.exec(token);
const word = trailing == null ? token : token.slice(0, trailing.index);
for (const segment of segmenter.segment(word)) {
parts.push(segment.segment);
}
if (trailing != null) {
parts.push(trailing[0]);
}
}
/**
* Splits text into word parts, each a non-whitespace run plus its trailing
* whitespace, with whitespace-only runs kept as separate parts. Scripts
* without word-delimiting spaces (CJK) are further split via Intl.Segmenter.
* Concatenating the result always reproduces the input exactly.
*/
export function splitWords(value: string): string[] {
const parts: string[] = [];
WORD_REGEX.lastIndex = 0;
let index = 0;
let match: RegExpExecArray | null;
while ((match = WORD_REGEX.exec(value)) !== null) {
if (match.index > index) {
parts.push(value.slice(index, match.index));
}
const token = match[0];
if (SPACELESS_REGEX.test(token)) {
pushSegmentedParts(parts, token);
} else {
parts.push(token);
}
index = match.index + token.length;
}
if (index < value.length) {
parts.push(value.slice(index));
}
return parts;
}
export function createFadeState(): FadeState {
return { prevCount: 0, active: new Map(), firstRun: true, pending: null };
}
export function beginRun(state: FadeState, suppress = false): FadeRun {
return {
state,
now: performance.now(),
count: 0,
newIndex: 0,
suppress,
additions: new Map(),
};
}
/**
* Stages the run's result on the state without publishing it. Classification
* never mutates committed state during render, so a render that React
* abandons (concurrent interruption, StrictMode double-render) leaves no
* trace; only {@link commitRun}, called after the render commits, publishes.
*/
export function stageRun(run: FadeRun): void {
run.state.pending = { prevCount: run.count, additions: run.additions, now: run.now };
}
/** Publishes the staged run: baseline offset, new animations, pruned entries. */
export function commitRun(state: FadeState): void {
const pending = state.pending;
if (pending == null) {
return;
}
state.pending = null;
state.firstRun = false;
state.prevCount = pending.prevCount;
for (const [start, entry] of pending.additions) {
state.active.set(start, entry);
}
for (const [start, entry] of state.active) {
if (pending.now - entry.at >= entry.delay + FADE_DURATION_MS) {
state.active.delete(start);
}
}
}
/** Stages and immediately commits, for callers without a commit phase. */
export function endRun(run: FadeRun): void {
stageRun(run);
commitRun(run.state);
}
/**
* Classifies one text value into fade segments, advancing the run's
* document-order character offset. A part is animated when it starts past the
* last committed run's total offset (newly streamed) or when it is still
* within its animation window from an earlier run, in which case it replays
* identical animation props so React leaves the in-flight CSS animation
* untouched. Committed state is only read here; new animations are recorded
* on the run and published by {@link commitRun}.
*/
export function classifyValue(run: FadeRun, value: string): FadeSegment[] {
const { state, now } = run;
const segments: FadeSegment[] = [];
for (const part of splitWords(value)) {
const start = run.count;
run.count += part.length;
if (run.suppress || !NON_WHITESPACE_REGEX.test(part)) {
segments.push({ start, value: part, animated: false, delay: 0 });
continue;
}
if (start >= state.prevCount) {
const staged = run.additions.get(start);
const delay = staged?.delay ?? Math.min(run.newIndex * FADE_STAGGER_MS, FADE_STAGGER_MAX_MS);
run.newIndex += 1;
run.additions.set(start, staged ?? { at: now, delay });
segments.push({ start, value: part, animated: true, delay });
continue;
}
const entry = state.active.get(start);
if (entry != null && now - entry.at < entry.delay + FADE_DURATION_MS) {
segments.push({ start, value: part, animated: true, delay: entry.delay });
continue;
}
segments.push({ start, value: part, animated: false, delay: 0 });
}
return segments;
}
const SKIP_TAGS = new Set([
'code',
'pre',
'svg',
'math',
'annotation',
'script',
'style',
'artifact',
'citation',
'composite-citation',
'highlighted-text',
'mcp-ui-resource',
'mcp-ui-carousel',
]);
function isSkippedElement(node: Element): boolean {
if (SKIP_TAGS.has(node.tagName)) {
return true;
}
const className = node.properties?.className;
if (Array.isArray(className)) {
return className.some((name) => typeof name === 'string' && name.startsWith('katex'));
}
return typeof className === 'string' && className.startsWith('katex');
}
function toContent(segment: FadeSegment): ElementContent {
if (!NON_WHITESPACE_REGEX.test(segment.value)) {
return { type: 'text', value: segment.value };
}
const properties: Element['properties'] = {};
if (segment.animated) {
properties.dataLcFade = '';
if (segment.delay > 0) {
properties.style = `--lc-delay:${segment.delay}ms`;
}
}
return {
type: 'element',
tagName: 'span',
properties,
children: [{ type: 'text', value: segment.value }],
};
}
function transformElement(run: FadeRun, element: Element): void {
const next: ElementContent[] = [];
for (const child of element.children) {
if (child.type === 'text') {
for (const segment of classifyValue(run, child.value)) {
next.push(toContent(segment));
}
continue;
}
if (child.type === 'element' && !isSkippedElement(child)) {
transformElement(run, child);
}
next.push(child);
}
element.children = next;
}
export type FadePlugin = {
plugin: Plugin<[], Root>;
/** Publish the latest render's staged classification; call after React commits. */
commit: () => void;
};
/**
* Creates a per-renderer rehype plugin that wraps newly streamed words in
* one-shot CSS fade spans (`[data-lc-fade]`). New-text detection uses
* document-order character offsets held in the factory closure, so text that
* was already visible in a previous render mounts as a bare span and never
* re-animates, even when markdown re-parsing restructures the tree. Pass
* `hydrated: true` for renderers created while previously accumulated content
* is already showing (resumed stream, conversation switch, follow-up turn):
* their first run becomes the baseline without animating. Classification is
* staged during render and must be published via `commit()` after React
* commits (a layout effect), so abandoned renders leave no trace. Create one
* instance per streaming renderer and drop it (plain plugin array) once the
* stream ends so the settled message renders without wrapper spans.
*/
export function createFadePlugin(hydrated = false): FadePlugin {
const state = createFadeState();
const plugin: Plugin<[], Root> = function rehypeFade() {
return (tree: Root) => {
const run = beginRun(state, hydrated && state.firstRun);
for (const child of tree.children) {
if (child.type === 'element' && !isSkippedElement(child)) {
transformElement(run, child);
}
}
stageRun(run);
};
};
return { plugin, commit: () => commitRun(state) };
}
const WHITESPACE_REGEX = /\s/;
const PREFIX_PROBE_LENGTH = 32;
/**
* Longest trailing run kept unsettled. Bounds per-token work when the last
* word never reaches whitespace (CJK, Thai, unspaced Hangul, URLs). Only
* settled, non-animated text is cut, and it renders as plain text on both
* sides of the cut, so a cut inside a part is invisible.
*/
const MAX_UNSETTLED_LENGTH = 64;
/**
* Moves a cut offset in `tail` back to a grapheme-cluster boundary, so emoji
* modifier, flag, ZWJ and combining sequences stay whole. `tail` starts at the
* committed settled boundary, which is itself a cluster boundary, and is
* bounded by the cap, so segmenting it stays proportional to the unsettled text.
* Without a grapheme segmenter there is no safe cut, so the cap is not applied.
*/
function glyphBoundary(tail: string, index: number): number {
const segmenter = getGraphemeSegmenter();
if (index <= 0 || segmenter == null) {
return 0;
}
let boundary = 0;
for (const segment of segmenter.segment(tail)) {
if (segment.index > index) {
break;
}
boundary = segment.index;
}
return boundary;
}
/** Offset of the last whitespace-delimited word, which appended text can still extend. */
function lastWordStart(value: string): number {
let index = value.length;
while (index > 0 && WHITESPACE_REGEX.test(value[index - 1])) {
index -= 1;
}
while (index > 0 && !WHITESPACE_REGEX.test(value[index - 1])) {
index -= 1;
}
return index;
}
/**
* Whether `text` still extends the settled `prefix`. Probes only the prefix's
* head and the region at its boundary so the per-token check stays constant
* rather than rescanning the whole accumulated prefix; an append-only stream
* always passes, and a rewrite that shifts or replaces text fails a probe. The
* settled region is always rendered from the current text, so a rewrite that
* slips past the probes can only affect fade timing, never the characters shown.
*/
function extendsPrefix(text: string, prefix: string): boolean {
if (text.length < prefix.length) {
return false;
}
const probe = Math.min(PREFIX_PROBE_LENGTH, prefix.length);
const boundary = prefix.length - probe;
return (
text.startsWith(prefix.slice(0, probe)) && text.startsWith(prefix.slice(boundary), boundary)
);
}
/**
* Plain-text counterpart of the rehype plugin for non-markdown streamed text
* (reasoning). Renders words in fade spans keyed by character offset; only
* render this while the text is actively streaming and render the raw string
* once settled. Classification is append-only: the leading run of parts that
* finished fading collapses into a single committed text node and is never
* re-split, so each streamed token costs work proportional to the unsettled
* tail rather than the accumulated text. The settled boundary never passes a
* word that is still fading, and stops before the last word (which appended
* text can still extend) unless that word outgrows MAX_UNSETTLED_LENGTH.
*/
export const AnimatedText: NamedExoticComponent<{ text: string }> = memo(function AnimatedText({
text,
}: {
text: string;
}) {
const stateRef = useRef<FadeState | null>(null);
const settledRef = useRef('');
if (stateRef.current == null) {
stateRef.current = createFadeState();
}
const state = stateRef.current;
const settledLength = extendsPrefix(text, settledRef.current) ? settledRef.current.length : 0;
const settled = text.slice(0, settledLength);
const tail = text.slice(settledLength);
const suppress = state.firstRun && text.length > FADE_HYDRATION_THRESHOLD;
const run = beginRun(state, suppress);
run.count = settledLength;
const segments = classifyValue(run, tail);
stageRun(run);
const limit = Math.max(
settledLength + lastWordStart(tail),
settledLength + glyphBoundary(tail, tail.length - MAX_UNSETTLED_LENGTH),
);
const firstAnimated = segments.find((segment) => segment.animated);
const nextSettledLength = Math.min(limit, firstAnimated?.start ?? limit);
useLayoutEffect(() => {
commitRun(state);
settledRef.current = text.slice(0, nextSettledLength);
});
return (
<>
{settled}
{segments.map((segment) => {
if (!segment.animated) {
return <Fragment key={segment.start}>{segment.value}</Fragment>;
}
const style =
segment.delay > 0 ? ({ '--lc-delay': `${segment.delay}ms` } as CSSProperties) : undefined;
return (
<span key={segment.start} data-lc-fade="" style={style}>
{segment.value}
</span>
);
})}
</>
);
});
AnimatedText.displayName = 'AnimatedText';

View file

@ -0,0 +1,22 @@
/** @jest-environment jsdom */
import { render } from '@testing-library/react';
import { MessagePartsHostProvider } from '@librechat/chat/react';
import { AnimatedText, ThinkingContent } from '@librechat/chat/components';
import { createMessagePartsHost } from '../src/__fixtures__/partsHost';
test('a consumer supplies the canonical effect and settles without fade wrappers', () => {
const host = createMessagePartsHost({
renderStreamingText: (text) => <AnimatedText text={text} />,
});
const view = (animate: boolean) => (
<MessagePartsHostProvider host={host}>
<ThinkingContent animate={animate}>Checking the manifest</ThinkingContent>
</MessagePartsHostProvider>
);
const { container, rerender } = render(view(true));
expect(container.querySelectorAll('[data-lc-fade]')).toHaveLength(3);
expect(container.textContent).toBe('Checking the manifest');
rerender(view(false));
expect(container.querySelector('[data-lc-fade]')).toBeNull();
expect(container.textContent).toBe('Checking the manifest');
});

View file

@ -439,3 +439,154 @@
transparent
);
}
/* Pre-response dot: enters on the streamed-text fade curve, then breathes
on opacity, replacing the legacy scale throb so waiting and text arrival
share one motion language.
Custom CSS exception: this indicator is a `::after` pseudo-element on the
`.result-thinking` hook, shown only while an ancestor carries `.submitting`
and the hook itself is `:empty`. No `@librechat/client` primitive can
express "render only while an ancestor is in state X and I have no
children"; a component would have to own that state, which the streaming
markdown path deliberately keeps in the DOM so the dot costs no React
renders per token. Scoped to the one selector, colored from
`--text-primary` so both themes follow, and disabled under
prefers-reduced-motion. */
@keyframes lc-dot-breathe {
0%,
100% {
opacity: 1;
}
50% {
opacity: 0.3;
}
}
.submitting .result-thinking:empty:last-child:after {
animation:
lc-fade-in 250ms ease-out both,
lc-dot-breathe 1.5s ease-in-out 250ms infinite;
background-color: rgb(var(--text-primary));
border-radius: 50%;
content: ' ';
display: block;
height: 0.75rem;
position: absolute;
top: -0.6875rem;
width: 0.75rem;
}
@media (prefers-reduced-motion: reduce) {
.submitting .result-thinking:empty:last-child:after {
animation: none;
}
}
.result-streaming > :not(ol):not(ul):not(pre):last-child:after,
.result-streaming > pre:last-child code:after {
display: inline-block;
content: '⬤';
width: 0.75rem;
height: 0.75rem;
font-family:
system-ui,
Inter,
Söhne Circle,
-apple-system,
Segoe UI,
Roboto,
Ubuntu,
Cantarell,
Noto Sans,
sans-serif;
line-height: normal;
margin-inline-start: 0.25rem;
vertical-align: middle;
font-size: 0.5rem;
}
@supports (selector(:has(*))) {
.result-streaming > :is(ul, ol):last-child > li:last-child:not(:has(> :is(ul, ol, pre))):after {
content: '⬤';
font-family:
system-ui,
Inter,
Söhne Circle,
-apple-system,
Segoe UI,
Roboto,
Ubuntu,
Cantarell,
Noto Sans,
sans-serif;
line-height: normal;
margin-inline-start: 0.25rem;
vertical-align: middle;
font-size: 0.5rem;
display: inline-block;
width: 0.75rem;
height: 0.75rem;
}
}
@supports not (selector(:has(*))) {
.result-streaming > ol:last-child > li:last-child:after,
.result-streaming > ul:last-child > li:last-child:after {
content: '⬤';
font-family:
system-ui,
Inter,
Söhne Circle,
-apple-system,
Segoe UI,
Roboto,
Ubuntu,
Cantarell,
Noto Sans,
sans-serif;
line-height: normal;
margin-inline-start: 0.25rem;
vertical-align: middle;
font-size: 0.5rem;
display: inline-block;
width: 0.75rem;
height: 0.75rem;
}
.result-streaming > ol:last-child > li:last-child > :is(ul, ol, pre) ~ :after,
.result-streaming > ul:last-child > li:last-child > :is(ul, ol, pre) ~ :after {
display: none;
}
.result-streaming > ol:last-child > li:last-child > pre:last-child code:after,
.result-streaming > ul:last-child > li:last-child > pre:last-child code:after {
display: inline-block;
}
}
/* Remove cursors when streaming is complete */
.result-streaming:not(.submitting) :is(ul, ol) li:after {
display: none !important;
}
/* Smooth streaming: one-shot fade-in on newly streamed words.
Duration must match FADE_DURATION_MS in packages/chat/src/components/fade.tsx */
@keyframes lc-fade-in {
from {
opacity: 0;
}
to {
opacity: 1;
}
}
[data-lc-fade] {
animation: lc-fade-in 250ms ease-out both;
animation-delay: var(--lc-delay, 0ms);
}
@media (prefers-reduced-motion: reduce) {
[data-lc-fade] {
animation: none;
}
}

View file

@ -203,3 +203,21 @@ describe('shared message body typography', () => {
expect(body).toMatch(/max-width:\s*none/);
});
});
describe('shared streaming effects', () => {
it.each(['result-thinking', 'result-streaming', 'data-lc-fade', 'lc-dot-breathe', 'lc-fade-in'])(
'ships %s in the package and removes the app duplicate',
(hook) => {
expect(parts).toContain(hook);
expect(appStyles).not.toContain(hook);
},
);
it('ships the fade and waiting-dot reduced-motion overrides', () => {
expect(reducedMotion).toContain('[data-lc-fade]');
expect(reducedMotion).toContain('.submitting .result-thinking:empty:last-child:after');
expect(parts).toContain('animation-delay: var(--lc-delay, 0ms)');
expect(parts).toContain('@supports not (selector(:has(*)))');
expect(parts).toContain('background-color: rgb(var(--text-primary))');
});
});