The Open Standard for Generative UI
import { useThread, type ToolActivity } from "@openuidev/react-headless";
import clsx from "clsx";
import { ChevronRight } from "lucide-react";
import {
useCallback,
useEffect,
useId,
useLayoutEffect,
useRef,
useState,
type ReactNode,
} from "react";
import { Mascot } from "../AgentInterface/components/Mascot";
import { MarkDownRenderer } from "../MarkDownRenderer";
import { TimelineEntry } from "../_shared/tool-renderer/TimelineEntry";
import type { ToolDetailedViewPanel } from "../_shared/tool-renderer/ToolActivityRenderer";
import { isToolRunning } from "./ToolCallPrimitives";
import { TIMELINE_GLYPH, ThinkingGlyph, toolIcon } from "./ToolGlyphs";
import { toolLabel, useToolLabels } from "./toolLabels";
/**
* One display row of the timeline: a tool activity, or a thinking-text step
* (prose the model emitted alongside its tool calls), in run order.
*/
export type TimelineStep =
{ type: "text"; id: string; text: string } | { type: "activity"; activity: ToolActivity };
const stepKey = (step: TimelineStep) =>
step.type === "text" ? `text-${step.id}` : step.activity.id;
/**
* A thinking-text step as a timeline row: brain glyph and label, expanding into
* the prose. Same markup and classes as {@link TimelineToolCard}'s row, so the
* two line up and share styles.
*/
const ThoughtRow = ({
text,
live,
open,
onOpenChange,
}: {
text: string;
/** This is the step the run is on right now. */
live: boolean;
open: boolean;
onOpenChange: (open: boolean) => void;
}) => {
const triggerId = useId();
const panelId = useId();
return (
<div className="openui-tool-call openui-tool-call--thought">
<button
type="button"
id={triggerId}
className="openui-tool-call__title-row"
aria-expanded={open}
aria-controls={panelId}
onClick={() => onOpenChange(!open)}
>
<span className="openui-tool-call__icon-wrapper">
<ThinkingGlyph {...TIMELINE_GLYPH} animate={live} className="openui-tool-call__icon" />
</span>
<span
className={clsx("openui-tool-call__name", { "openui-tool-call__name--shimmer": live })}
>
{live ? "Thinking" : "Thought it through"}
</span>
<ChevronRight size={14} className="openui-tool-call__chevron" />
</button>
{open && (
<div
id={panelId}
role="region"
aria-labelledby={triggerId}
className="openui-tool-call__content"
>
<MarkDownRenderer
textMarkdown={text}
className="openui-tool-call-timeline__text-step-body"
/>
</div>
)}
</div>
);
};
const TimelineStepRow = ({
step,
isLast,
live,
detailedViewPanel,
forceDefault,
open,
onOpenChange,
}: {
step: TimelineStep;
isLast: boolean;
/** The newest step while the run is live: shown in progress whatever its status. */
live: boolean;
detailedViewPanel?: ToolDetailedViewPanel;
forceDefault: boolean;
open: boolean;
onOpenChange: (open: boolean) => void;
}) => {
if (step.type === "text") {
return <ThoughtRow text={step.text} live={live} open={open} onOpenChange={onOpenChange} />;
}
return (
<TimelineEntry
activity={step.activity}
isLast={isLast}
inProgress={live || undefined}
detailedViewPanel={detailedViewPanel}
forceDefault={forceDefault}
open={open}
onOpenChange={onOpenChange}
/>
);
};
/**
* What the collapsed header shows for the step in progress: its glyph and label,
* animated for as long as the step holds the header (server-side tools can
* finish before the reveal reaches them, so the status alone isn't enough).
*/
const LiveStepSummary = ({ step }: { step: TimelineStep }) => {
const labels = useToolLabels();
if (step.type === "text") {
return (
<>
<span className="openui-behind-the-scenes__glyph">
<ThinkingGlyph {...TIMELINE_GLYPH} animate />
</span>
<span className="openui-behind-the-scenes__toggle-label openui-behind-the-scenes__toggle-label--shimmer">
Thinking
</span>
</>
);
}
const { activity } = step;
const Glyph = toolIcon(activity.toolName, activity.status);
const label = activity.statusMessage ?? toolLabel(activity.status, activity.toolName, labels);
return (
<>
<span className="openui-behind-the-scenes__glyph">
<Glyph {...TIMELINE_GLYPH} animate />
</span>
<span className="openui-behind-the-scenes__toggle-label openui-behind-the-scenes__toggle-label--shimmer">
{label}
</span>
</>
);
};
/**
* The timeline's header in its "Working" state, on its own: the mascot and a
* shimmering label. The thread shows it from the moment a message is sent
* until a tool call or the answer arrives, and it sits exactly where the
* timeline's header will, so the hand-over doesn't move anything.
*/
export const TimelineWorkingIndicator = () => (
<div className="openui-behind-the-scenes">
<div
className="openui-behind-the-scenes__toggle openui-behind-the-scenes__toggle--static"
role="status"
>
<span className="openui-behind-the-scenes__ticker">
<span className="openui-behind-the-scenes__ticker-item">
<span className="openui-behind-the-scenes__glyph">
<Mascot size={28} className="openui-behind-the-scenes__mascot" />
</span>
<span className="openui-behind-the-scenes__toggle-label openui-behind-the-scenes__toggle-label--shimmer">
Working
</span>
</span>
</span>
</div>
</div>
);
/** Keep in sync with the ticker animation duration in toolCall.scss. */
const TICKER_SLIDE_MS = 320;
/**
* One line of header content. When `itemKey` changes, the previous line slides
* up and out while the new one slides up into place.
*/
const HeaderTicker = ({ itemKey, children }: { itemKey: string; children: ReactNode }) => {
const [leaving, setLeaving] = useState<{ key: string; node: ReactNode } | null>(null);
const last = useRef({ key: itemKey, node: children });
useEffect(() => {
if (last.current.key === itemKey) return;
setLeaving(last.current);
const t = setTimeout(() => setLeaving(null), TICKER_SLIDE_MS);
return () => clearTimeout(t);
}, [itemKey]);
// Remember what is on screen now, so the next change can slide it out.
useEffect(() => {
last.current = { key: itemKey, node: children };
});
return (
<span className="openui-behind-the-scenes__ticker">
{leaving && (
<span
key={`out-${leaving.key}`}
className="openui-behind-the-scenes__ticker-item openui-behind-the-scenes__ticker-item--out"
aria-hidden="true"
>
{leaving.node}
</span>
)}
<span
key={itemKey}
className={clsx("openui-behind-the-scenes__ticker-item", {
"openui-behind-the-scenes__ticker-item--in": leaving,
})}
>
{children}
</span>
</span>
);
};
// How long each step holds the header before the next one slides in.
const REVEAL_INTERVAL = 1000;
const NO_FADE: { top: boolean; bottom: boolean } = { top: false, bottom: false };
// scrollHeight and clientHeight are both rounded, and rows have fractional
// heights (line-height on a 14px body), so a list that fits can still report a
// pixel or two of overflow. Only a gap wider than that — and, per edge, a real
// scroll offset — counts, or a short run fades an edge it never scrolls past.
const OVERFLOW_SLACK = 8;
const EDGE_SLACK = 4;
/** Visually hidden but available to screen readers. */
const VISUALLY_HIDDEN = {
position: "absolute",
width: 1,
height: 1,
overflow: "hidden",
clipPath: "inset(50%)",
whiteSpace: "nowrap",
border: 0,
padding: 0,
margin: -1,
} as const;
/**
* The "Working / Behind the scenes" timeline, driven by {@link ToolActivity}[]
* from `useToolActivities`.
*
* - **Header.** Collapsed while a run is live, it shows the step in progress
* (its animated glyph and label), and each new step slides the previous one
* up and out. Otherwise it shows the mascot with "Working" or "Behind the
* scenes".
* - **List.** Expanding shows every revealed step as rows in one card. One row
* is open at a time.
*
* Steps are revealed one by one at a readable pace, the run counts as live
* across the tool-result → first-token gap (`awaitingResponse`), and "running"
* is read from each activity's status rather than an `isThinking` prop.
*
* (Animations are CSS-only — framer-motion is intentionally not a dependency.)
*
* @category Components
*/
export function ToolCallTimeline({
activities,
steps,
isLast = false,
detailedViewPanel,
forceDefault = false,
awaitingResponse = false,
}: {
activities: ToolActivity[];
/** Ordered display rows interleaving thinking text with tool activities */
steps?: TimelineStep[];
isLast?: boolean;
detailedViewPanel?: ToolDetailedViewPanel;
/** Render every row as the raw default card (e.g. so matched tools' raw
* request/response stay inspectable here while their rich preview renders elsewhere). */
forceDefault?: boolean;
/** Keep the run "live" across the tool-result → first-token gap instead of
* settling the instant the last result lands. */
awaitingResponse?: boolean;
}) {
const displaySteps: TimelineStep[] =
steps ?? activities.map((activity) => ({ type: "activity", activity }));
// "Thinking" while the last activity is still running (or its results are in
// but the response hasn't started), on the live message, and the thread is
// actually running — so a closed-args call with no result stops showing
// "Working" once the run ends.
const isThreadRunning = useThread((s) => s.isRunning);
const labels = useToolLabels();
const thinking =
isThreadRunning &&
isLast &&
activities.length > 0 &&
(isToolRunning(activities[activities.length - 1]!.status) || awaitingResponse);
// Collapsed by default; the header carries the live step instead.
const [expanded, setExpanded] = useState(false);
// The one open row in the list, by step key.
const [openStep, setOpenStep] = useState<string | null>(null);
// Live message reveals from the first step; historical reveals them all so
// it never animates "Working" on mount.
const [revealedCount, setRevealedCount] = useState(() =>
isLast ? 1 : Math.max(displaySteps.length, 1),
);
// Reset on each run edge: a rising `thinking` restarts the reveal and
// collapses the list; a falling `thinking` reveals everything.
const prevThinking = useRef(thinking);
useEffect(() => {
if (!prevThinking.current && thinking) {
setRevealedCount(1);
setExpanded(false);
setOpenStep(null);
followRef.current = true;
} else if (prevThinking.current && !thinking) {
setRevealedCount(displaySteps.length);
}
prevThinking.current = thinking;
}, [thinking, displaySteps.length]);
// The items list is height-capped (see toolCall.scss) and scrolls
// internally. While the run is live, SMOOTHLY follow the newest row as
// content streams in — unless the user scrolled up to read an earlier one.
const itemsRef = useRef<HTMLDivElement | null>(null);
const followRef = useRef(true);
const distanceFromBottom = (el: HTMLElement) => el.scrollHeight - el.scrollTop - el.clientHeight;
const [fade, setFade] = useState(NO_FADE);
const measureEdges = useCallback(() => {
const el = itemsRef.current;
const next =
el && el.scrollHeight - el.clientHeight > OVERFLOW_SLACK
? { top: el.scrollTop > EDGE_SLACK, bottom: distanceFromBottom(el) > EDGE_SLACK }
: NO_FADE;
setFade((prev) => (prev.top === next.top && prev.bottom === next.bottom ? prev : next));
}, []);
// Measured on every render of THIS component, which covers rows streaming in —
// but a row expanding or collapsing changes the list's height too, and so
// does the list opening. Observing the element covers those: its box is
// content-sized until the cap, so it changes on the way in and back out.
const observerRef = useRef<ResizeObserver | null>(null);
const attachItems = useCallback(
(el: HTMLDivElement | null) => {
itemsRef.current = el;
observerRef.current?.disconnect();
observerRef.current = null;
if (!el || typeof ResizeObserver === "undefined") return;
const observer = new ResizeObserver(() => measureEdges());
observer.observe(el);
observerRef.current = observer;
},
[measureEdges],
);
useEffect(() => () => observerRef.current?.disconnect(), []);
useLayoutEffect(() => {
measureEdges();
});
const handleItemsScroll = useCallback(() => {
const el = itemsRef.current;
if (el && distanceFromBottom(el) < 24) followRef.current = true;
measureEdges();
}, [measureEdges]);
const handleItemsWheel = useCallback((e: React.WheelEvent) => {
if (e.deltaY < 0) followRef.current = false;
}, []);
const handleItemsTouchMove = useCallback(() => {
const el = itemsRef.current;
if (el && distanceFromBottom(el) >= 24) followRef.current = false;
}, []);
useLayoutEffect(() => {
if (!thinking || !expanded || !followRef.current) return;
const el = itemsRef.current;
if (!el || distanceFromBottom(el) < 1) return;
const reduceMotion =
typeof window !== "undefined" &&
window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
el.scrollTo({ top: el.scrollHeight, behavior: reduceMotion ? "auto" : "smooth" });
});
// Advance the reveal once the current step is ready — an activity whose args
// have closed (left "streaming"); text steps are always ready. Only the live
// message reveals incrementally.
const revealingStep = displaySteps[revealedCount - 1];
const currentReady =
!revealingStep || revealingStep.type === "text"
? true
: revealingStep.activity.status !== "streaming";
useEffect(() => {
if (isLast && revealedCount < displaySteps.length && currentReady) {
const t = setTimeout(() => setRevealedCount((c) => c + 1), REVEAL_INTERVAL);
return () => clearTimeout(t);
}
return undefined;
}, [isLast, displaySteps.length, revealedCount, currentReady]);
// Robustness: once the thread stops running, reveal everything. The
// incremental reveal only advances while `isLast`, so a run that ends
// mid-reveal (or a timeline that mounted after `thinking` already fell)
// would otherwise stay stuck showing "Working". This is independent of the
// rising/falling `thinking` edge, so it settles regardless of mount timing.
useEffect(() => {
if (!isThreadRunning && revealedCount < displaySteps.length) {
setRevealedCount(displaySteps.length);
}
}, [isThreadRunning, revealedCount, displaySteps.length]);
// Guard the array that is actually indexed below. `steps` is caller-supplied
// and can be empty even when `activities` is not, and `??` keeps an empty
// array rather than falling back to `activities`.
if (activities.length === 0 || displaySteps.length === 0) return null;
const revealing = revealedCount < displaySteps.length;
const working = thinking || revealing;
const current = displaySteps[Math.min(revealedCount - 1, displaySteps.length - 1)]!;
// Collapsed while live, the header shows the newest revealed step until the
// run settles; open, the list shows it instead.
const liveStep = working && !expanded ? current : null;
// Persistent live announcement reflecting the current step's status — driven by
// the same fallback the primitives use so SRs hear status changes as content
// updates (the header ticker remounts its line and never announces on its own).
const liveLabel =
current.type === "text"
? current.text
: (current.activity.statusMessage ??
toolLabel(current.activity.status, current.activity.toolName, labels));
// Once settled, surface a failure count on the toggle so errors aren't hidden
// behind a collapsed "Behind the scenes".
const failedCount = working ? 0 : activities.filter((a) => a.status === "error").length;
const toggleLabel = working
? "Working"
: failedCount > 0
? `Behind the scenes · ${failedCount} failed`
: "Behind the scenes";
return (
<div
className={clsx("openui-behind-the-scenes", {
// While working, the mascot in this row stands in for the thread loader.
"openui-behind-the-scenes--working": working,
// Once the run is over, the header steps back (see toolCall.scss).
"openui-behind-the-scenes--settled": !working,
})}
>
<div role="status" aria-live="polite" style={VISUALLY_HIDDEN}>
{liveLabel}
</div>
<button
className="openui-behind-the-scenes__toggle"
type="button"
aria-expanded={expanded}
onClick={() => setExpanded((open) => !open)}
>
<HeaderTicker itemKey={liveStep ? stepKey(liveStep) : "summary"}>
{liveStep ? (
<LiveStepSummary step={liveStep} />
) : (
<>
<span className="openui-behind-the-scenes__glyph">
<Mascot size={28} className="openui-behind-the-scenes__mascot" />
</span>
<span
className={clsx("openui-behind-the-scenes__toggle-label", {
"openui-behind-the-scenes__toggle-label--shimmer": working,
})}
>
{toggleLabel}
</span>
</>
)}
</HeaderTicker>
{/* Points right while collapsed and turns down when open (see toolCall.scss). */}
<ChevronRight size={16} className="openui-behind-the-scenes__toggle-icon" />
</button>
<div
className={clsx("openui-behind-the-scenes__collapse", {
"openui-behind-the-scenes__collapse--open": expanded,
})}
inert={!expanded}
>
<div className="openui-behind-the-scenes__collapse-inner">
<div
className={clsx("openui-behind-the-scenes__items", {
"openui-behind-the-scenes__items--fade-top": fade.top,
"openui-behind-the-scenes__items--fade-bottom": fade.bottom,
})}
ref={attachItems}
onScroll={handleItemsScroll}
onWheel={handleItemsWheel}
onTouchMove={handleItemsTouchMove}
>
{/* Keyed per step, so each new row plays its fade-in once, on mount. */}
{displaySteps.slice(0, revealedCount).map((step, idx) => {
const key = stepKey(step);
const newest = idx === revealedCount - 1;
return (
<div key={key} className="openui-behind-the-scenes__item">
<TimelineStepRow
step={step}
isLast={isLast && newest}
live={working && newest}
detailedViewPanel={detailedViewPanel}
forceDefault={forceDefault}
open={openStep === key}
onOpenChange={(open) => setOpenStep(open ? key : null)}
/>
</div>
);
})}
</div>
</div>
</div>
</div>
);
}