Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

Open a conversation at the bottom, keep it still while a Bot writes, and add a rail of turns (#882)

Guido Vizosoab9855c19848
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b2a72a71..27745c6f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -122,6 +122,17 @@ for its default of thirty minutes, and `browserIdleMs: 0` (keep browsers open) w
of these settings now also reach the computers `computers.mode: sandbox` makes, which had none of
them.
+### A conversation opens at the bottom and stays still while a Bot writes
+
+Opening a conversation shows its newest messages at once, already at the bottom, instead of loading
+and then gliding down; a long one draws older messages as somebody scrolls up to them, without
+moving what they are reading. Charts, tables, cards and decisions a Bot draws grow in place while
+they stream, and no longer flash "not available" before they appear. A reply is revealed at a steady
+pace, and the view follows it until the person scrolls up or selects some of it, and picks it up
+again when they come back to the end or press the arrow. A rail beside a conversation has a mark
+per turn: hovering one previews what was asked and answered, and choosing it goes there. Nothing
+changes for a deployment.
+
### Generated interfaces use A2UI 1.0
With generative UI on, a Bot builds an interface from the A2UI 1.0 basic components instead of the
diff --git a/app/src/components/channels/channel-chat.tsx b/app/src/components/channels/channel-chat.tsx
index 43f187a1..317647c9 100644
--- a/app/src/components/channels/channel-chat.tsx
+++ b/app/src/components/channels/channel-chat.tsx
@@ -91,6 +91,48 @@ function sameActivity(
);
}
+/**
+ * Whether the transcript still waits behind the placeholder.
+ *
+ * A channel opened from the roster waits for its whole history: the stored thread (`restoring`) and
+ * its voice chats. A channel just started from the compose screen has no history; its first message
+ * is already in hand and shows at once, not after a voice-chat request with nothing in it.
+ *
+ * Exported for its tests.
+ */
+export function historyIsLoading({
+ restoring,
+ seeded,
+ voicePending,
+ voiceWaitedOut = false,
+}: {
+ restoring: boolean;
+ seeded: boolean;
+ voicePending: boolean;
+ /** The voice chats have had their `VOICE_WAIT_MS` since the thread came in. */
+ voiceWaitedOut?: boolean;
+}): boolean {
+ return restoring || (!seeded && voicePending && !voiceWaitedOut);
+}
+
+/**
+ * How long, once the thread is in, the conversation waits for its voice chats before showing
+ * without them. A slow or failing voice service must not hold up text chat; cards that arrive after
+ * this join the transcript where they belong.
+ */
+export const VOICE_WAIT_MS = 1500;
+
+/** Whether `VOICE_WAIT_MS` has passed since `waiting` became true. Reset whenever it is false. */
+function useWaitedOut(waiting: boolean, key: string): boolean {
+ const [waitedOut, setWaitedOut] = useState<string | null>(null);
+ useEffect(() => {
+ if (!waiting) return;
+ const timer = window.setTimeout(() => setWaitedOut(key), VOICE_WAIT_MS);
+ return () => window.clearTimeout(timer);
+ }, [waiting, key]);
+ return waiting && waitedOut === key;
+}
+
export function channelHistoryNotice({
restoring,
messageCount,
@@ -549,8 +591,24 @@ export function ChannelChat({
useActiveBot(runtimeAgentId);
const skillCommands = useSkillCommands(runtimeAgentId);
- const historyNotice = channelHistoryNotice({
+ /*
+ * History is the snapshot, the stored thread AND the voice archive. The transcript shows none of
+ * it until all three are in, so it lands once at the bottom instead of drawing the conversation
+ * and then splicing call cards into it; the notice waits for the same moment, so it appears in
+ * the commit that shows the history rather than a render later, shrinking the view under it.
+ */
+ const voiceWaitedOut = useWaitedOut(
+ !restoring && seed === null && voiceArchive.pending,
+ channel.id,
+ );
+ const historyLoading = historyIsLoading({
restoring,
+ seeded: seed !== null,
+ voicePending: voiceArchive.pending,
+ voiceWaitedOut,
+ });
+ const historyNotice = channelHistoryNotice({
+ restoring: historyLoading,
messageCount: agent.messages.length,
lastMessageAt: channel.lastMessageAt,
historyAvailability,
@@ -1091,7 +1149,7 @@ export function ChannelChat({
* above.
*/
queueWhileBusy
- restoring={restoring}
+ restoring={historyLoading}
/*
* The run, not the turn. Stop reaches a run through the core's abort controller, and that
* controller does not exist until `say` has finished waiting for the runtime agent — so
diff --git a/app/src/components/channels/chat-messages.ts b/app/src/components/channels/chat-messages.ts
index 88454bda..096cc5c3 100644
--- a/app/src/components/channels/chat-messages.ts
+++ b/app/src/components/channels/chat-messages.ts
@@ -320,8 +320,7 @@ function isReadableMessage(message: unknown): message is Readonly<Message> {
* row it builds is keyed on the id". `message.id` is keyed on harder and was checked nowhere: it
* becomes `VisibleChatItem.id`, which is DECLARED `string`, and downstream that one value is the
* React key, `MessageScrollerItem`'s `messageId`, the turn-grouping key `anchorRowIds` and `turnOf`
- * cut apart at the last colon, and the memo key `createFirstPaintDelays` hangs an entrance delay
- * off.
+ * cut apart at the last colon, and the key `openingStagger` hangs a row's entrance delay off.
*
* IT SURVIVED BECAUSE IT DOES NOT THROW — the same reason `readAttachmentMetadata` gives for its
* own fields having gone unchecked, and the claim there that `metadata` was "the last unchecked
@@ -419,7 +418,12 @@ export function toVisibleChatItems(
kind: "tool",
// One assistant message can carry multiple tool calls.
id: toolCall.id,
- toolCall,
+ /*
+ * A copy, not the agent's object: the client appends argument chunks to the call it
+ * already handed over, so a row comparing the call it drew with the next one would be
+ * comparing an object with itself and never see the arguments grow.
+ */
+ toolCall: { ...toolCall, function: { ...toolCall.function } },
...(results.has(toolCall.id)
? { result: results.get(toolCall.id) }
: {}),
diff --git a/app/src/components/channels/chat-transcript.tsx b/app/src/components/channels/chat-transcript.tsx
index 49379f6a..ba700277 100644
--- a/app/src/components/channels/chat-transcript.tsx
+++ b/app/src/components/channels/chat-transcript.tsx
@@ -1,9 +1,11 @@
import type { ActivityMessage, Message } from "@ag-ui/core";
import type { Attachment } from "@copilotkit/react-core/v2";
import {
+ useCopilotKit,
useRenderActivityMessage,
useRenderToolCall,
} from "@copilotkit/react-core/v2";
+import { useQuery } from "@tanstack/react-query";
import {
readConnectPrompt,
SHOW_APP_ACCESS_TOOL,
@@ -18,7 +20,10 @@ import {
} from "@tabler/icons-react";
import { motion, useReducedMotion } from "motion/react";
import {
+ createContext,
memo,
+ useCallback,
+ useContext,
useEffect,
useLayoutEffect,
useMemo,
@@ -26,6 +31,7 @@ import {
useState,
} from "react";
import { Streamdown } from "streamdown";
+import { ArgumentsArrivingContext } from "@/components/gallery/streaming";
import { Bubble, BubbleContent } from "@/components/ui/bubble";
import {
Dialog,
@@ -46,7 +52,6 @@ import {
MessageScrollerItem,
MessageScrollerProvider,
MessageScrollerViewport,
- useMessageScroller,
} from "@/components/ui/message-scroller";
import { Skeleton } from "@/components/ui/skeleton";
import { attachmentUrl } from "@/lib/channels/attachments";
@@ -66,7 +71,9 @@ import {
import { readTeamBotConsent } from "@/lib/team-bots";
import { cn } from "@/lib/utils";
import { VOICE_CHAT_ACTIVITY, type VoiceChatEntry } from "@/lib/voice/archive";
+import { deploymentCapabilitiesQueryOptions } from "@/lib/deployment/queries";
import { AppAccessCard } from "./app-access-card";
+import { isBrowserStep } from "./browser-activity";
import {
attachmentModality,
type SentAttachment,
@@ -74,15 +81,28 @@ import {
} from "./chat-messages";
import { splitChatOrigin } from "./chat-origin";
import type { QueuedMessage } from "./composer";
+import { FollowScroll, RESUME_PX, useFollowIntent } from "./follow-intent";
+import { LateRenderersContext, LateRenderersWatch } from "./late-renderers";
+import { usePacedReveal } from "./paced-reveal";
import { TeamBotConsentCard } from "./team-bot-consent";
import {
dropRepeatedAppCards,
groupToolSteps,
ToolActivity,
+ type ToolGroup,
type TranscriptItem,
useDrawnTool,
} from "./tool-activity";
-import { ToolRenderBoundary } from "./tool-boundary";
+import { ToolRenderBoundary, toolCallFinal } from "./tool-boundary";
+import { shouldDrawEarlier, useTranscriptPages } from "./transcript-pages";
+import { TranscriptRail } from "./transcript-rail";
+import {
+ AT_END_PX,
+ currentTurn,
+ isPersonSentMessage,
+ type Turn,
+ turnsOf,
+} from "./transcript-turns";
import { ToolLine } from "./tool-line";
import { VoiceChatCard } from "./voice-chat-card";
@@ -411,65 +431,116 @@ function Queued({
* alternative is threading a ref out through three components with no other reason to know a
* scroller exists.
*/
-function ScrollNewestQueuedIntoView({ newest }: { newest: string | null }) {
- const { scrollToEnd } = useMessageScroller();
-
+function ScrollNewestQueuedIntoView({
+ newest,
+ onQueued,
+}: {
+ newest: string | null;
+ onQueued: () => void;
+}) {
useEffect(() => {
if (newest === null) {
return;
}
- scrollToEnd();
- }, [newest, scrollToEnd]);
+ // Through the follow state, so the view is told to follow before it is sent to the end.
+ onQueued();
+ }, [newest, onQueued]);
return null;
}
/**
- * How many of the newest turns cascade when a channel is opened, and how far apart.
- *
- * The tail rather than the head: opening a channel lands you at the bottom, so these are the ones
- * actually on screen. Staggering from the top of a long history would spend the whole budget on
- * messages nobody can see and leave the visible ones arriving last.
+ * How many of the newest rows render in when a conversation opens, and how far apart.
*
- * Twelve at 40ms is 440ms of cascade before the last one starts. Past roughly half a second this
- * stops reading as settling and starts reading as waiting.
+ * The view has already landed at the bottom before the first paint, so these are the rows on
+ * screen; the stagger runs top of the screen first, newest last. Short on purpose: eight rows 30ms
+ * apart is a little over 200ms before the last one starts, which reads as the conversation
+ * appearing rather than as it loading. Older rows, above the fold, are simply there.
*/
-const FIRST_PAINT_STAGGER_COUNT = 12;
-const FIRST_PAINT_STAGGER_SECONDS = 0.04;
+const OPENING_STAGGER_COUNT = 8;
+const OPENING_STAGGER_MS = 30;
/**
- * Decide, once per message, whether it waits its turn.
+ * The opening stagger, decided once from the rows present when the conversation opens.
*
- * FROZEN PER ID ON PURPOSE. `delay` is a prop on a memoised component, so a value that changed
- * between renders would break the memo that makes the streaming path cheap — and worse, a message
- * whose delay changed could replay its entrance mid-stream. Each id is decided the first time it is
- * seen and never revisited.
+ * Applied as a CSS animation on the scroller's row wrapper, not on the memoised row inside it: the
+ * row's props stay the same and a streaming answer can never replay it, and a transform composites
+ * without moving the layout box the scroller just landed on. Exported for its tests.
+ */
+export function openingStagger(ids: readonly string[]): Map<string, string> {
+ const start = Math.max(0, ids.length - OPENING_STAGGER_COUNT);
+ return new Map(
+ ids
+ .slice(start)
+ .map((id, index) => [id, `${index * OPENING_STAGGER_MS}ms`] as const),
+ );
+}
+
+/** Where a turn jumped to from the rail sits below the top of the view. */
+const TURN_INSET_PX = 24;
+
+/**
+ * Since when a row mounting now is arriving live, rather than having been there when the
+ * conversation opened: null while it is not.
+ *
+ * A ref, not state: it is read once, at a row's first render, and setting it must not re-render
+ * anything. `ArrivalsLive` provides a fresh one with the scroller, so it is null for the commit that
+ * mounts the whole history and set to the time in the effect after it; every row mounted from then
+ * on is something that arrived while the person was here. The time is for a row that can say when
+ * what it shows happened (see `useArrivedLive`).
+ */
+const ArrivalsLiveContext = createContext<React.RefObject<
+ number | null
+> | null>(null);
+
+/*
+ * For rows drawn later but older than everything on screen: an earlier page added above as the
+ * reader scrolls up (`useTranscriptPages`). They are history, so they draw at rest.
+ */
+const AT_REST: React.RefObject<number | null> = { current: null };
+
+function ArrivalsLive({ children }: { children: React.ReactNode }) {
+ const live = useRef<number | null>(null);
+ useEffect(() => {
+ live.current = Date.now();
+ }, []);
+ return (
+ <ArrivalsLiveContext.Provider value={live}>
+ {children}
+ </ArrivalsLiveContext.Provider>
+ );
+}
+
+/**
+ * Whether this row arrived while the conversation was open, decided once at its first render (see
+ * `ArrivalsLiveContext`), so a reply streaming into it can never change the answer.
*
- * `settled` flips after the first render that has any items, which is NOT the first render: history
- * is restored asynchronously, so a channel's transcript is empty for a beat. Anything appearing
- * after that is a live turn and is given no delay at all.
+ * `happenedAt` is for a row that is late rather than new: a voice chat from before the conversation
+ * opened, when the voice service answered after the conversation was already showing. It mounts
+ * among rows on screen but is history, and draws at rest.
*/
-function createFirstPaintDelays() {
- const decided = new Map<string, number>();
- let settled = false;
+function useArrivedLive(happenedAt?: string): boolean {
+ const liveRef = useContext(ArrivalsLiveContext);
+ const [live] = useState(() => {
+ if (liveRef === null) return true;
+ const since = liveRef.current;
+ if (since === null) return false;
+ return happenedAt === undefined || !(Date.parse(happenedAt) < since);
+ });
+ return live;
+}
- return {
- settle() {
- settled = true;
- },
- delayFor(id: string, index: number, total: number): number {
- const known = decided.get(id);
- if (known !== undefined) {
- return known;
- }
- const offset = total - FIRST_PAINT_STAGGER_COUNT;
- const place = index - Math.max(0, offset);
- const delay =
- settled || place < 0 ? 0 : place * FIRST_PAINT_STAGGER_SECONDS;
- decided.set(id, delay);
- return delay;
- },
- };
+/**
+ * How Streamdown draws a Bot's message, decided once when the message mounts. History is finished
+ * text and takes the static renderer, which does no repair of half-written markdown; anything that
+ * arrived live, or was still streaming when the conversation opened, takes the streaming one and
+ * keeps it after it finishes, so the renderer never changes under the reader. Exported for its test.
+ */
+export function messageMode(
+ live: boolean,
+ streaming: boolean,
+): "static" | "streaming" {
+ return live || streaming ? "streaming" : "static";
}
/**
@@ -491,19 +562,20 @@ function createFirstPaintDelays() {
* accelerated and drops frames exactly when the main thread is busy, which here is while a reply is
* streaming.
*
- * STAGGERED ONLY ON THE FIRST PAINT OF A CHANNEL. A turn sent mid-conversation arrives alone and
- * must not wait behind anything, so `delay` is zero for it. Opening a channel is the one moment the
- * whole history mounts at once, and cascading the last few reads as the conversation settling
- * rather than as a page appearing all at once. `createFirstPaintDelays` decides which is which.
+ * ONLY FOR WHAT ARRIVES WHILE THE CONVERSATION IS OPEN. A row mounted with the history draws at
+ * rest here and takes the opening stagger instead (`openingStagger`); `ArrivalsLiveContext` says
+ * which is which, decided once at the row's first render so a streaming answer can never replay it.
*/
function Arriving({
children,
- delay = 0,
+ happenedAt,
}: {
children: React.ReactNode;
- delay?: number;
+ /** When what the row shows happened, if it can say; see `useArrivedLive`. */
+ happenedAt?: string;
}) {
const shouldReduceMotion = useReducedMotion();
+ const live = useArrivedLive(happenedAt);
return (
<motion.div
@@ -524,15 +596,16 @@ function Arriving({
* all outside a flex container.
*/
className="flex w-full flex-col"
- initial={{
- opacity: 0,
- // Reduced motion keeps the fade and drops the movement: gentler, not absent.
- transform: shouldReduceMotion ? "none" : "translateY(8px)",
- }}
+ initial={
+ live
+ ? {
+ opacity: 0,
+ // Reduced motion keeps the fade and drops the movement: gentler, not absent.
+ transform: shouldReduceMotion ? "none" : "translateY(8px)",
+ }
+ : false
+ }
transition={{
- // Reduced motion gets the fade with no queue: a cascade is movement too, just spread over
- // time, and somebody who asked for less of it should not wait for their history to arrive.
- delay: shouldReduceMotion ? 0 : delay,
duration: ENTRANCE_SECONDS,
ease: EASE_OUT,
}}
@@ -634,16 +707,24 @@ function ResponsibilityFiring({
*/
const TranscriptMessage = memo(function TranscriptMessage({
commandNames = "",
- delay,
role,
+ streaming = false,
text,
}: {
commandNames?: string;
- delay: number;
role: "user" | "assistant";
+ /* This is the Bot's reply still being written: the last row of a turn in flight. */
+ streaming?: boolean;
text: string;
}) {
const isUser = role === "user";
+ const live = useArrivedLive();
+ const [mode] = useState(() => messageMode(live, streaming));
+ // A person's message arrives whole; only a Bot's reply is paced.
+ const revealed = usePacedReveal(text, {
+ live: live && !isUser,
+ streaming,
+ });
/*
* Checked before anything else a person's message gets. A firing is not a person's message: the
* chip split, the end alignment and the bubble are all wrong for it, and each one of them would
@@ -654,7 +735,7 @@ const TranscriptMessage = memo(function TranscriptMessage({
return (
<MessageRow align="start">
<MessageContent>
- <Arriving delay={delay}>
+ <Arriving>
<RoutineFiring instruction={firing} />
</Arriving>
</MessageContent>
@@ -670,7 +751,7 @@ const TranscriptMessage = memo(function TranscriptMessage({
return (
<MessageRow align={align}>
<MessageContent>
- <Arriving delay={delay}>
+ <Arriving>
{/*
A Bot's message takes the whole column, not the width of its words: block content
inside it — a fenced code block, a table — should span the transcript rather than
@@ -721,7 +802,9 @@ const TranscriptMessage = memo(function TranscriptMessage({
* closing token arrives, so the answer visibly rewrites itself as it lands. This
* closes them for the duration.
*/
- <Streamdown components={markdownComponents}>{text}</Streamdown>
+ <Streamdown components={markdownComponents} mode={mode}>
+ {revealed}
+ </Streamdown>
)}
</BubbleContent>
</Bubble>
@@ -752,7 +835,6 @@ const ATTACHMENT_URL_PREFIX = attachmentUrl("");
*/
type AttachmentRowProps = {
attachments: readonly SentAttachment[];
- delay: number;
};
/**
@@ -778,9 +860,6 @@ export function sameAttachmentRow(
previous: AttachmentRowProps,
next: AttachmentRowProps,
): boolean {
- if (previous.delay !== next.delay) {
- return false;
- }
if (previous.attachments.length !== next.attachments.length) {
return false;
}
@@ -800,12 +879,11 @@ export function sameAttachmentRow(
export const TranscriptAttachments = memo(function TranscriptAttachments({
attachments,
- delay,
}: AttachmentRowProps) {
return (
<MessageRow align="end">
<MessageContent>
- <Arriving delay={delay}>
+ <Arriving>
<AttachmentTiles attachments={attachments} />
</Arriving>
</MessageContent>
@@ -1269,23 +1347,31 @@ function activityName(activityType: string): string {
* from re-rendering a mounted iframe.
*/
const TranscriptActivity = memo(function TranscriptActivity({
- delay,
message,
}: {
- delay: number;
message: ActivityMessage;
}) {
const { renderActivityMessage } = useRenderActivityMessage();
- const drawn =
- message.activityType === VOICE_CHAT_ACTIVITY ? (
- <VoiceChatCard call={message.content.call as VoiceChatEntry} />
- ) : (
- renderActivityMessage(message)
- );
+ /*
+ * Drawn before generative UI was switched on (a cold load: the capabilities answer or the runtime
+ * connection still on its way), an activity found no renderer. Read so it redraws when the
+ * renderers arrive, rather than staying blank until its own message next changes; see
+ * `LateRenderersWatch`, which the transcript mounts once for all of them.
+ */
+ useContext(LateRenderersContext);
+ const call =
+ message.activityType === VOICE_CHAT_ACTIVITY
+ ? (message.content.call as VoiceChatEntry)
+ : null;
+ const drawn = call ? (
+ <VoiceChatCard call={call} />
+ ) : (
+ renderActivityMessage(message)
+ );
if (!drawn) return null;
return (
- <Arriving delay={delay}>
+ <Arriving happenedAt={call?.startedAt}>
<ToolRenderBoundary name={activityName(message.activityType)}>
{drawn}
</ToolRenderBoundary>
@@ -1303,8 +1389,7 @@ const TranscriptActivity = memo(function TranscriptActivity({
* `useRenderToolCall` is called HERE rather than passed in as a prop: a function whose identity the
* parent cannot guarantee is the classic way to make a memo boundary useless.
*/
-const TranscriptToolCall = memo(function TranscriptToolCall({
- delay,
+const ToolCallBody = memo(function ToolCallBody({
toolCallId,
name,
args,
@@ -1312,7 +1397,6 @@ const TranscriptToolCall = memo(function TranscriptToolCall({
latest,
spokeAfter,
}: {
- delay: number;
toolCallId: string;
name: string;
args: string;
@@ -1352,38 +1436,111 @@ const TranscriptToolCall = memo(function TranscriptToolCall({
);
return (
- <Arriving delay={delay}>
- <ToolRenderBoundary name={name}>
- <ToolPlaceContext.Provider value={place}>
- {/*
- * A TOOL WITH NO REGISTERED RENDERER STILL HAPPENED, and since tools moved to the server
- * that is now the ordinary case rather than the exception: MCP tools execute in the runtime
- * and register no renderer here at all. `renderToolCall` still draws the components the app
- * registers, and everything else lands below.
- *
- * What was called, shimmering until its result arrives, and then the server's own words
- * drawn the way a Bot's prose is drawn.
- */}
- {drawn ?? (
- <ServerToolLine
- name={name}
- place={{ toolCallId, latest }}
- result={result}
- />
- )}
- </ToolPlaceContext.Provider>
- </ToolRenderBoundary>
- </Arriving>
+ <ToolRenderBoundary
+ final={toolCallFinal(args, result)}
+ name={name}
+ resetKey={args}
+ >
+ <ToolPlaceContext.Provider value={place}>
+ {/*
+ * A TOOL WITH NO REGISTERED RENDERER STILL HAPPENED, and since tools moved to the server
+ * that is now the ordinary case rather than the exception: MCP tools execute in the runtime
+ * and register no renderer here at all. `renderToolCall` still draws the components the app
+ * registers, and everything else lands below.
+ *
+ * What was called, shimmering until its result arrives, and then the server's own words
+ * drawn the way a Bot's prose is drawn.
+ */}
+ {drawn ?? (
+ <ServerToolLine
+ name={name}
+ place={{ toolCallId, latest }}
+ result={result}
+ />
+ )}
+ </ToolPlaceContext.Provider>
+ </ToolRenderBoundary>
);
});
+/**
+ * A row of tool calls, drawn by ONE component whatever it holds, so a row is never rebuilt as its
+ * calls change. A lone call is the line or card it always was; a run, or a browser step, is the
+ * folded group. Both a `tools` group and a single `tool` item come through here, because a lone call
+ * can be either over its life (it stops folding once its answer asks the person) under one key; see
+ * `groupToolSteps`.
+ */
+type ToolRowProps = {
+ id: string;
+ steps: ToolGroup["steps"];
+ active: boolean;
+ latest: boolean;
+ /** The Bot said something after this row in its turn. See `ToolPlace`. */
+ spokeAfter: boolean;
+};
+
+/**
+ * Whether a tool row would draw the same thing. `groupToolSteps` builds new step objects and a new
+ * array on every render (it has to: the agent mutates the messages in place), so the default memo
+ * check saw a change on every token of a reply streaming below and redrew every finished tool group
+ * in the history, markdown inside collapsed details included. What a row draws is its steps' calls
+ * and results, and those are what is compared. Exported for its test.
+ */
+export function sameToolRow(a: ToolRowProps, b: ToolRowProps): boolean {
+ return (
+ a.id === b.id &&
+ a.active === b.active &&
+ a.latest === b.latest &&
+ a.spokeAfter === b.spokeAfter &&
+ a.steps.length === b.steps.length &&
+ a.steps.every((step, index) => {
+ const other = b.steps[index];
+ return (
+ other !== undefined &&
+ step.id === other.id &&
+ step.result === other.result &&
+ step.toolCall.function.name === other.toolCall.function.name &&
+ step.toolCall.function.arguments === other.toolCall.function.arguments
+ );
+ })
+ );
+}
+
+const ToolRow = memo(function ToolRow({
+ id,
+ steps,
+ active,
+ latest,
+ spokeAfter,
+}: ToolRowProps) {
+ const [only] = steps;
+ return (
+ <Arriving>
+ {steps.length === 1 && only && !isBrowserStep(only) ? (
+ <ArgumentsArrivingContext.Provider value={active}>
+ <ToolCallBody
+ args={only.toolCall.function.arguments}
+ latest={latest}
+ name={only.toolCall.function.name}
+ result={only.result}
+ spokeAfter={spokeAfter}
+ toolCallId={only.toolCall.id}
+ />
+ </ArgumentsArrivingContext.Provider>
+ ) : (
+ <ToolActivity active={active} group={{ kind: "tools", id, steps }} />
+ )}
+ </Arriving>
+ );
+}, sameToolRow);
+
/**
* A tool the runtime executed, drawn for the person watching.
*
* Named from the reader's side: what was done, against which server, with the server's own words
* behind a disclosure. The identifier the model was offered never reaches the screen.
*
- * Exported for its tests, which draw it without the CopilotKit provider `TranscriptToolCall` needs.
+ * Exported for its tests, which draw it without the CopilotKit provider `ToolCallBody` needs.
*/
export function ServerToolLine({
name,
@@ -1453,23 +1610,8 @@ export function ServerToolLine({
);
}
-/**
- * Whether a text item is the person actually sending something, as opposed to a routine firing that
- * merely arrived wearing `role: "user"`.
- *
- * A FIRING IS NOT THE PERSON SPEAKING — `TranscriptMessage` already knows that and draws it as
- * `RoutineFiring` rather than as their bubble, via the same `readFiring` check used here. The scroll
- * machinery below was the one place left that had not caught up: it smooth-scrolled and anchored on
- * `role === "user"` alone, so a routine firing while somebody was reading back through the channel
- * yanked their viewport to the bottom as though they had just typed and sent something. They hadn't;
- * the schedule had. Exported so this can be checked without mounting anything.
- */
-export function isPersonSentMessage(
- role: "user" | "assistant",
- text: string,
-): boolean {
- return role === "user" && readFiring(text) === null;
-}
+/* Moved beside the turns it also decides; re-exported for the callers that read it from here. */
+export { isPersonSentMessage };
/**
* WHERE THE CONVERSATION HAS GOT TO, for an app card that may carry its task on once the app is
@@ -1563,24 +1705,77 @@ function assertNever(_item: never): null {
const SEND_SCROLL_MS = 700;
+/**
+ * Whether the viewport should glide for a beat because the person just sent something.
+ *
+ * ONLY FOR A SEND MADE WHILE THE CONVERSATION IS OPEN. The newest person-sent id also changes while
+ * history is restored, batch by batch, and gliding then animated the scroller's jump to the bottom
+ * of a channel being opened: the conversation visibly loaded and then slid. The first id seen once
+ * history is in is the baseline, never a send.
+ *
+ * Exported so it can be checked without mounting anything.
+ */
+export function shouldGlideOnSend({
+ previous,
+ next,
+ restoring,
+ reducedMotion,
+}: {
+ previous: string | null;
+ next: string | null;
+ restoring: boolean;
+ reducedMotion: boolean;
+}): boolean {
+ return (
+ !restoring &&
+ !reducedMotion &&
+ previous !== null &&
+ next !== null &&
+ previous !== next
+ );
+}
+
function useSmoothSendScroll(
viewport: React.RefObject<HTMLDivElement | null>,
newestUserMessageId: string | null,
+ restoring: boolean,
+ onSend: () => void,
) {
const reducedMotion = useReducedMotion();
const seenRef = useRef<string | null>(null);
+ /*
+ * Whether the conversation has been seen open since it was restored. Separate from `seenRef`:
+ * the glide needs a previous message to compare with, but a send does not. In a routine's channel
+ * that holds only firings, the person's first message has nothing before it and is still a send.
+ */
+ const openRef = useRef(false);
useLayoutEffect(() => {
const element = viewport.current;
const previous = seenRef.current;
- seenRef.current = newestUserMessageId;
+ const wasOpen = openRef.current;
+ // Nothing is recorded while restoring, so the first id after it is a baseline (see above).
+ seenRef.current = restoring ? null : newestUserMessageId;
+ openRef.current = !restoring;
+
+ // A send picks following back up whatever the motion setting; only the glide depends on it.
+ if (
+ wasOpen &&
+ !restoring &&
+ newestUserMessageId !== null &&
+ newestUserMessageId !== previous
+ ) {
+ onSend();
+ }
if (
element === null ||
- newestUserMessageId === null ||
- previous === null ||
- previous === newestUserMessageId ||
- reducedMotion
+ !shouldGlideOnSend({
+ previous,
+ next: newestUserMessageId,
+ restoring,
+ reducedMotion: reducedMotion ?? false,
+ })
) {
return;
}
@@ -1594,7 +1789,24 @@ function useSmoothSendScroll(
window.clearTimeout(timer);
element.style.scrollBehavior = "";
};
- }, [newestUserMessageId, reducedMotion, viewport]);
+ }, [newestUserMessageId, onSend, reducedMotion, restoring, viewport]);
+}
+
+/** The transcript's one `LateRenderersWatch`, with what it needs from the provider and the server. */
+function TranscriptRenderersWatch({
+ onVersion,
+}: {
+ onVersion: (version: number) => void;
+}) {
+ const { copilotkit } = useCopilotKit();
+ const { data: capabilities } = useQuery(deploymentCapabilitiesQueryOptions());
+ return (
+ <LateRenderersWatch
+ core={copilotkit}
+ onVersion={onVersion}
+ settled={capabilities?.generativeUi}
+ />
+ );
}
export function ChatTranscript({
@@ -1618,9 +1830,12 @@ export function ChatTranscript({
* cost was markdown parsing and chart SVGs, and those are skipped by the memoised children below,
* which is where the 25x came from. This runs per render and is not worth guarding.
*/
+ /* Which row each tool step was drawn in, so a row keeps its key; see `groupToolSteps`. */
+ const rowIdsRef = useRef(new Map<string, string>());
const items = groupToolSteps(
dropRepeatedAppCards(toVisibleChatItems(messages)),
isDrawn,
+ rowIdsRef.current,
);
/*
@@ -1657,7 +1872,23 @@ export function ChatTranscript({
*/
item.kind === "attachments",
)?.id ?? null;
- useSmoothSendScroll(viewportRef, newestUserMessageId);
+ /* Whether the view follows a streaming reply; see `follow-intent`. */
+ const follow = useFollowIntent(viewportRef, restoring);
+ const { dispatch: dispatchFollow } = follow;
+ const followOnSend = useCallback(
+ () => dispatchFollow({ type: "send" }),
+ [dispatchFollow],
+ );
+ const followOnQueued = useCallback(
+ () => dispatchFollow({ type: "queued" }),
+ [dispatchFollow],
+ );
+ useSmoothSendScroll(
+ viewportRef,
+ newestUserMessageId,
+ restoring,
+ followOnSend,
+ );
/* Which tool calls are still the latest thing, for an app card: see `latestFrom`. */
const latestIndex = latestFrom(items, { busy, queued: queued.length });
@@ -1670,174 +1901,423 @@ export function ChatTranscript({
const anchorRows = anchorRowIds(items);
/*
- * One decider per mounted transcript, so opening a different channel starts the cascade over and
- * a message never inherits a delay from a conversation it was not in.
+ * Decided once, from the rows present when the scroller mounts, and forgotten while restoring so
+ * a conversation opened again staggers again. Rows that arrive later are not in it: they have
+ * their own entrance (`Arriving`).
*/
- const delaysRef = useRef<ReturnType<typeof createFirstPaintDelays> | null>(
- null,
- );
- if (delaysRef.current === null) {
- delaysRef.current = createFirstPaintDelays();
+ const openingRef = useRef<Map<string, string> | null>(null);
+ if (restoring) {
+ openingRef.current = null;
+ } else if (openingRef.current === null) {
+ openingRef.current = openingStagger(items.map((item) => item.id));
}
- const delays = delaysRef.current;
+ const opening = openingRef.current;
+ const openingProps = (id: string) => {
+ const delay = opening?.get(id);
+ return delay === undefined
+ ? {}
+ : {
+ className: "history-arrive",
+ style: { "--arrive-delay": delay } as React.CSSProperties,
+ };
+ };
+
+ /* Which rows are drawn; see `useTranscriptPages`. */
+ const pages = useTranscriptPages(
+ items.map((item) => item.id),
+ restoring,
+ );
+ const { drawEarlier, drawTo, from: pagesFrom } = pages;
+ const drawEarlierNearTop = useCallback(
+ (from: number) => {
+ const element = viewportRef.current;
+ if (
+ element !== null &&
+ shouldDrawEarlier({
+ from,
+ scrollTop: element.scrollTop,
+ scrollHeight: element.scrollHeight,
+ })
+ ) {
+ drawEarlier();
+ }
+ },
+ [drawEarlier],
+ );
+ /*
+ * After every page: a page that does not reach LOAD_MARGIN_PX above the fold (short rows, a tall
+ * screen) draws the one before it. ON THE NEXT FRAME, NOT IN THIS COMMIT. The scroller puts the
+ * reader back after a prepend from a MutationObserver callback, which runs after layout effects;
+ * checked here, a reader at the very top (where the browser has nothing to anchor against) still
+ * read `scrollTop` 0, drew another page, read 0 again, and drew the whole history in one burst,
+ * which past about fifty pages is more nested updates than React allows. A frame later the
+ * position is the restored one, and a page is only drawn if the reader really is still near the
+ * top. Each extra page lands above the fold and is held in place, so the wait is never seen.
+ */
+ useLayoutEffect(() => {
+ if (restoring) return;
+ const frame = window.requestAnimationFrame(() =>
+ drawEarlierNearTop(pagesFrom),
+ );
+ return () => window.cancelAnimationFrame(frame);
+ }, [pagesFrom, restoring, drawEarlierNearTop]);
+
+ /* Activities that may be waiting on their renderers; see `LateRenderersWatch`. */
+ const [renderersVersion, setRenderersVersion] = useState(0);
+ const hasActivities = items.some(
+ (item) =>
+ item.kind === "activity" &&
+ item.message.activityType !== VOICE_CHAT_ACTIVITY,
+ );
+ /* The rail's marks, and which turn is being read; see `TranscriptRail`. */
+ const turns = turnsOf(items);
+ const turnIds = turns.map((turn) => turn.id).join("\n");
+ const [activeTurn, setActiveTurn] = useState<string | null>(null);
/*
- * Settled AFTER the render that first had items, not on mount: history arrives asynchronously, so
- * on mount there is nothing to stagger yet and marking it settled then would mean the history
- * cascade never happens.
+ * Read at most once a frame, with one query: while a reply streams the scroller scrolls on every
+ * resize, and a lookup and a layout read per turn per scroll event was real work on a long
+ * conversation.
*/
- const hasItems = items.length > 0;
- useEffect(() => {
- if (hasItems) {
- delays.settle();
+ const activeFrameRef = useRef<number | null>(null);
+ const readActiveTurnNow = useCallback(() => {
+ activeFrameRef.current = null;
+ const element = viewportRef.current;
+ if (element === null || turnIds === "") return;
+ const wanted = new Set(turnIds.split("\n"));
+ const view = element.getBoundingClientRect();
+ const rows: { id: string; top: number }[] = [];
+ for (const row of element.querySelectorAll<HTMLElement>(
+ "[data-message-id]",
+ )) {
+ const id = row.dataset.messageId;
+ if (id !== undefined && wanted.has(id)) {
+ rows.push({ id, top: row.getBoundingClientRect().top - view.top });
+ }
}
- }, [hasItems, delays]);
+ setActiveTurn(
+ currentTurn(
+ rows,
+ element.clientHeight / 3,
+ element.scrollHeight - element.scrollTop - element.clientHeight <=
+ AT_END_PX,
+ ),
+ );
+ }, [turnIds]);
+ const readActiveTurn = useCallback(() => {
+ if (activeFrameRef.current !== null) return;
+ activeFrameRef.current = window.requestAnimationFrame(readActiveTurnNow);
+ }, [readActiveTurnNow]);
+ useEffect(
+ () => () => {
+ if (activeFrameRef.current !== null) {
+ window.cancelAnimationFrame(activeFrameRef.current);
+ }
+ },
+ [],
+ );
+ useLayoutEffect(() => {
+ if (!restoring) readActiveTurnNow();
+ }, [restoring, readActiveTurnNow]);
+
+ /*
+ * A jump from the rail. A turn already drawn is gone to now; one in a page not drawn yet draws
+ * every page down to it first, and is gone to a frame after that commit, once the scroller has put
+ * the reader back where they were (the same wait as the fill check above). Instant, never smooth:
+ * a smooth scroll up passes the top margin and draws pages above while it is moving, and the
+ * scroller's hold on the reader's place would fight it.
+ */
+ const jumpRef = useRef<string | null>(null);
+ const goToTurn = useCallback((id: string) => {
+ const element = viewportRef.current;
+ const row = element?.querySelector(`[data-message-id="${CSS.escape(id)}"]`);
+ if (!element || !row) return;
+ // Less the transcript's own top padding (`py-6`), so the turn sits where a first row would.
+ element.scrollTop +=
+ row.getBoundingClientRect().top -
+ element.getBoundingClientRect().top -
+ TURN_INSET_PX;
+ }, []);
+ /*
+ * Following stops as the view moves, not before the pages are drawn: the scroller holds the
+ * reader's place across a prepend by moving `scrollTop` down by what was added, and at the end of
+ * the conversation that reads exactly like the person scrolling back to the end, which picks
+ * following up again (`nextFollow`).
+ */
+ const goToTurnStill = useCallback(
+ (id: string) => {
+ goToTurn(id);
+ /*
+ * Not when the move left the view at the end: a short last turn is clamped there, nothing
+ * scrolls, and nothing would ever pick following up again.
+ */
+ const element = viewportRef.current;
+ if (
+ element !== null &&
+ element.scrollHeight - element.scrollTop - element.clientHeight >
+ RESUME_PX
+ ) {
+ dispatchFollow({ type: "jump" });
+ }
+ },
+ [dispatchFollow, goToTurn],
+ );
+ const jump = useCallback(
+ (turn: Turn) => {
+ setActiveTurn(turn.id);
+ if (turn.index < pagesFrom) {
+ jumpRef.current = turn.id;
+ drawTo(turn.index);
+ } else {
+ goToTurnStill(turn.id);
+ }
+ },
+ [drawTo, goToTurnStill, pagesFrom],
+ );
+ // biome-ignore lint/correctness/useExhaustiveDependencies: runs after the commit that drew the pages a jump asked for, which is a change of `pagesFrom`.
+ useLayoutEffect(() => {
+ const id = jumpRef.current;
+ if (id === null) return;
+ const frame = window.requestAnimationFrame(() => {
+ jumpRef.current = null;
+ goToTurnStill(id);
+ });
+ return () => window.cancelAnimationFrame(frame);
+ }, [pagesFrom, goToTurnStill]);
+
+ /*
+ * NOTHING BUT THE PLACEHOLDER UNTIL HISTORY IS COMPLETE, AND THE SCROLLER MOUNTED FRESH AFTER IT.
+ *
+ * History arrives in pieces: the gateway snapshot, then the stored thread merged into it, then
+ * the voice archive. Drawing each piece as it came showed a conversation that loaded and then
+ * moved. And the scroller decides where to land ONCE, in a layout effect, the first time it sees
+ * any child (`defaultScrollPosition`, applied by `ie()` in `@shadcn/react`'s message-scroller).
+ * Mounted early, it spent that on the always-present `contents` block below, and the restored
+ * rows then took the "rows appended" path, which pins a lone person's message to the top instead
+ * of going to the end. Mounted here, with every row in the same commit, its one landing is the
+ * bottom of the whole conversation, before the browser paints anything.
+ */
+ if (restoring) {
+ return (
+ <div className="flex size-full min-h-0 flex-col overflow-hidden">
+ <div className="mx-auto flex w-full max-w-2xl flex-col gap-6 px-4 py-6">
+ <RestoringTranscript />
+ {/*
+ * A message typed while history loads is parked, not lost, and must be seen to be: a
+ * composer that cleared with nothing appearing reads as a message that vanished, and the
+ * person types it again.
+ */}
+ {queued.map((message) => (
+ <Queued
+ attachments={message.attachments}
+ key={message.id}
+ onRemove={
+ onRemoveQueued ? () => onRemoveQueued(message.id) : undefined
+ }
+ text={message.text}
+ />
+ ))}
+ </div>
+ </div>
+ );
+ }
+
+ /*
+ * One row, wherever it is drawn. `index` is the row's place in `items`, not in the slice being
+ * drawn, so "the last row" and "latest" mean the same with or without older pages above.
+ */
+ const renderRow = (item: TranscriptItem, index: number) =>
+ item.kind === "tools" || item.kind === "tool" ? (
+ <MessageScrollerItem
+ key={item.id}
+ messageId={item.id}
+ {...openingProps(item.id)}
+ >
+ <ToolRow
+ active={busy && index === items.length - 1}
+ id={item.id}
+ latest={index >= latestIndex}
+ spokeAfter={lastBotWords > index}
+ steps={item.kind === "tools" ? item.steps : [item]}
+ />
+ </MessageScrollerItem>
+ ) : item.kind === "activity" ? (
+ <MessageScrollerItem
+ key={item.id}
+ messageId={item.id}
+ {...openingProps(item.id)}
+ >
+ <TranscriptActivity message={item.message} />
+ </MessageScrollerItem>
+ ) : item.kind === "text" ? (
+ <MessageScrollerItem
+ key={item.id}
+ messageId={item.id}
+ scrollAnchor={anchorRows.has(item.id)}
+ {...openingProps(item.id)}
+ >
+ <TranscriptMessage
+ commandNames={commandNames}
+ role={item.role}
+ streaming={
+ busy && item.role === "assistant" && index === items.length - 1
+ }
+ text={item.text}
+ />
+ </MessageScrollerItem>
+ ) : item.kind === "attachments" ? (
+ <MessageScrollerItem
+ key={item.id}
+ messageId={item.id}
+ scrollAnchor={anchorRows.has(item.id)}
+ {...openingProps(item.id)}
+ >
+ <TranscriptAttachments attachments={item.attachments} />
+ </MessageScrollerItem>
+ ) : (
+ // Every member of the union is handled above. `assertNever` types `item` as
+ // `never` here, so a future addition to `VisibleChatItem` fails to typecheck at
+ // this call instead of silently falling into this branch and rendering nothing.
+ assertNever(item)
+ );
return (
- <MessageScrollerProvider autoScroll scrollPreviousItemPeek={48}>
- <MessageScroller>
- <MessageScrollerViewport ref={viewportRef}>
- <MessageScrollerContent
- aria-busy={busy}
- className="mx-auto w-full max-w-2xl px-4 py-6"
- spacerClassName="order-2"
- >
- {/*
- * DRAWN LAST, WRITTEN FIRST, AND THE SCROLLER IS WHY. Three reviewers have now arrived
- * at this block, worked the mechanism out from the library's bundle, and reached the
- * same place; it had no comment for any of them to read. This is that comment.
- *
- * `MessageScrollerContent` is `flex flex-col`, so `order` is live: the spacer takes
- * `order-2`, these children take `order-1`, and the transcript rows below keep the
- * default `0`. Visual order is therefore items, then anything parked or in flight, then
- * the spacer — while DOM order puts this block first.
- *
- * IT CANNOT SIMPLY BE MOVED DOWN. The scroller finds a newly appended row POSITIONALLY.
- * On every content change it takes `Array.from(content.children)` minus the spacer,
- * compares the length against the previous length, and when it grew scans FROM THE OLD
- * LENGTH FORWARD for the next `data-scroll-anchor="true"` (`je(a, T)` in
- * `@shadcn/react/dist/message-scroller`). A new row is only found when it lands at the
- * very end of that list. Put this block after `items.map` and every appended row lands
- * one slot short of the end, the scan finds this div instead, returns null, and the
- * caller falls through to its follow-the-bottom branch — so a new turn stops aligning
- * to the top of the viewport with a peek of the previous one, silently, with no test
- * failing.
- *
- * `display: contents` IS LOAD-BEARING FOR THE SAME REASON, and not a layout trick. It
- * promotes these children to flex items of the column so they can carry `order`, while
- * the div itself stays a single, always-present entry in `content.children` — one
- * stable slot the row count can be offset by. Wrapping `items.map` the same way would
- * be the natural symmetry and is fatal: the rows would leave `content.children`
- * entirely and the scroller would see a transcript of two elements, neither carrying a
- * `data-message-id`, so nothing would register, be tracked as visible, or anchor.
- *
- * WHAT THIS COSTS, STATED RATHER THAN LEFT TO BE REDISCOVERED. `order` moves paint and
- * not the DOM, so it moves neither focus order nor the reading order of the enclosing
- * `role="log"`. A keyboard user tabbing in reaches the "Remove queued message: …"
- * button of every parked message before any control in the conversation, though those
- * lines are drawn at the very bottom (WCAG 2.4.3); a screen reader reading the log
- * linearly hears the parked messages, and `Stopped`, ahead of the conversation they
- * follow on screen (WCAG 1.3.2).
- *
- * THAT IS A KNOWN, UNPAID DEBT AND NOT AN OVERSIGHT. The fixes available from inside
- * this file were each tried on paper and each breaks something worse: `aria-owns` needs
- * a generated id per row and re-sequences only the accessibility tree, leaving tab
- * order inverted; positive `tabIndex` hijacks the tab sequence of the whole page;
- * hoisting the queue out of `MessageScrollerContent` into a sibling region — the
- * cleanest END STATE, since a parked message is genuinely not a log entry — puts it
- * outside a column that is `min-h-full`, so it lands below the fold on a short
- * transcript, outside the `gap-6` rhythm, and outside the spacer's height arithmetic.
- * Paying it properly means the scroller identifying new rows by identity rather than by
- * position, which is the library's to change and is worth asking for.
- */}
- <div className="contents [&>*]:order-1">
- {stopped ? (
- <Stopped reason={stopped} />
- ) : waitingOnFirstToken ? (
- <Thinking />
- ) : null}
- {working}
- {queued.map((message) => (
- <Queued
- attachments={message.attachments}
- key={message.id}
- onRemove={
- onRemoveQueued
- ? () => onRemoveQueued(message.id)
- : undefined
- }
- text={message.text}
- />
- ))}
- </div>
- {items.length === 0 && restoring ? <RestoringTranscript /> : null}
- {items.map((item, index) =>
- item.kind === "tools" ? (
- <MessageScrollerItem key={item.id} messageId={item.id}>
- <Arriving
- delay={delays.delayFor(item.id, index, items.length)}
- >
- <ToolActivity
- group={item}
- active={busy && index === items.length - 1}
+ <ArrivalsLive>
+ {hasActivities ? (
+ <TranscriptRenderersWatch onVersion={setRenderersVersion} />
+ ) : null}
+ <LateRenderersContext.Provider value={renderersVersion}>
+ <MessageScrollerProvider
+ autoScroll={follow.following}
+ scrollPreviousItemPeek={48}
+ >
+ <MessageScroller className="@container">
+ <MessageScrollerViewport
+ {...follow.viewportHandlers}
+ data-following={follow.following}
+ onScroll={(event) => {
+ follow.viewportHandlers.onScroll?.(event);
+ drawEarlierNearTop(pagesFrom);
+ readActiveTurn();
+ }}
+ ref={viewportRef}
+ >
+ <MessageScrollerContent
+ aria-busy={busy}
+ className="mx-auto w-full max-w-2xl px-4 py-6"
+ spacerClassName="order-2"
+ >
+ {/*
+ * DRAWN LAST, WRITTEN FIRST, AND THE SCROLLER IS WHY. Three reviewers have now arrived
+ * at this block, worked the mechanism out from the library's bundle, and reached the
+ * same place; it had no comment for any of them to read. This is that comment.
+ *
+ * `MessageScrollerContent` is `flex flex-col`, so `order` is live: the spacer takes
+ * `order-2`, these children take `order-1`, and the transcript rows below keep the
+ * default `0`. Visual order is therefore items, then anything parked or in flight, then
+ * the spacer — while DOM order puts this block first.
+ *
+ * IT CANNOT SIMPLY BE MOVED DOWN. The scroller finds a newly appended row POSITIONALLY.
+ * On every content change it takes `Array.from(content.children)` minus the spacer,
+ * compares the length against the previous length, and when it grew scans FROM THE OLD
+ * LENGTH FORWARD for the next `data-scroll-anchor="true"` (`je(a, T)` in
+ * `@shadcn/react/dist/message-scroller`). A new row is only found when it lands at the
+ * very end of that list. Put this block after `items.map` and every appended row lands
+ * one slot short of the end, the scan finds this div instead, returns null, and the
+ * caller falls through to its follow-the-bottom branch — so a new turn stops aligning
+ * to the top of the viewport with a peek of the previous one, silently, with no test
+ * failing.
+ *
+ * OLDER PAGES GO BEFORE THIS BLOCK, AND THAT IS THE SAME MECHANISM USED ON PURPOSE.
+ * When the reader nears the top, the page before is drawn (`useTranscriptPages`). Drawn
+ * here, ahead of this block, it moves whatever was the first child, and a first child
+ * that moved is the scroller's own "rows were prepended" case: it puts the row the
+ * reader was looking at back where it was (`de()`), and never runs the scan above, which
+ * would read the shifted rows as new ones and jump to an old turn. Rows that arrive
+ * live still go after this block, at the end, where that scan looks for them.
+ *
+ * ONE CASE IT DOES NOT COVER. The scroller takes one path per batch of changes, so a page
+ * drawn above and a sent message landing in the SAME commit would be held in place and
+ * the new turn not aligned to the top. They come from different updates (a scroll near
+ * the top, a send at the bottom) and in practice never commit together; if they ever
+ * do, the turn is not aligned when it arrives, and a later change that keeps the row
+ * count can align to it then instead (the scroller's `Ge`), a beat late.
+ *
+ * `display: contents` IS LOAD-BEARING FOR THE SAME REASON, and not a layout trick. It
+ * promotes these children to flex items of the column so they can carry `order`, while
+ * the div itself stays a single, always-present entry in `content.children` — one
+ * stable slot the row count can be offset by. Wrapping `items.map` the same way would
+ * be the natural symmetry and is fatal: the rows would leave `content.children`
+ * entirely and the scroller would see a transcript of two elements, neither carrying a
+ * `data-message-id`, so nothing would register, be tracked as visible, or anchor.
+ *
+ * WHAT THIS COSTS, STATED RATHER THAN LEFT TO BE REDISCOVERED. `order` moves paint and
+ * not the DOM, so it moves neither focus order nor the reading order of the enclosing
+ * `role="log"`. A keyboard user tabbing in reaches the "Remove queued message: …"
+ * button of every parked message before any control in the conversation, though those
+ * lines are drawn at the very bottom (WCAG 2.4.3); a screen reader reading the log
+ * linearly hears the parked messages, and `Stopped`, ahead of the conversation they
+ * follow on screen (WCAG 1.3.2).
+ *
+ * THAT IS A KNOWN, UNPAID DEBT AND NOT AN OVERSIGHT. The fixes available from inside
+ * this file were each tried on paper and each breaks something worse: `aria-owns` needs
+ * a generated id per row and re-sequences only the accessibility tree, leaving tab
+ * order inverted; positive `tabIndex` hijacks the tab sequence of the whole page;
+ * hoisting the queue out of `MessageScrollerContent` into a sibling region — the
+ * cleanest END STATE, since a parked message is genuinely not a log entry — puts it
+ * outside a column that is `min-h-full`, so it lands below the fold on a short
+ * transcript, outside the `gap-6` rhythm, and outside the spacer's height arithmetic.
+ * Paying it properly means the scroller identifying new rows by identity rather than by
+ * position, which is the library's to change and is worth asking for.
+ */}
+ <ArrivalsLiveContext.Provider value={AT_REST}>
+ {items
+ .slice(pages.from, pages.split)
+ .map((item, offset) =>
+ renderRow(item, pages.from + offset),
+ )}
+ </ArrivalsLiveContext.Provider>
+ <div className="contents [&>*]:order-1">
+ {stopped ? (
+ <Stopped reason={stopped} />
+ ) : waitingOnFirstToken ? (
+ <Thinking />
+ ) : null}
+ {working}
+ {queued.map((message) => (
+ <Queued
+ attachments={message.attachments}
+ key={message.id}
+ onRemove={
+ onRemoveQueued
+ ? () => onRemoveQueued(message.id)
+ : undefined
+ }
+ text={message.text}
/>
- </Arriving>
- </MessageScrollerItem>
- ) : item.kind === "tool" ? (
- <MessageScrollerItem key={item.id} messageId={item.id}>
- <TranscriptToolCall
- args={item.toolCall.function.arguments}
- delay={delays.delayFor(item.id, index, items.length)}
- latest={index >= latestIndex}
- name={item.toolCall.function.name}
- result={item.result}
- spokeAfter={lastBotWords > index}
- toolCallId={item.toolCall.id}
- />
- </MessageScrollerItem>
- ) : item.kind === "activity" ? (
- <MessageScrollerItem key={item.id} messageId={item.id}>
- <TranscriptActivity
- delay={delays.delayFor(item.id, index, items.length)}
- message={item.message}
- />
- </MessageScrollerItem>
- ) : item.kind === "text" ? (
- <MessageScrollerItem
- key={item.id}
- messageId={item.id}
- scrollAnchor={anchorRows.has(item.id)}
- >
- <TranscriptMessage
- commandNames={commandNames}
- delay={delays.delayFor(item.id, index, items.length)}
- role={item.role}
- text={item.text}
- />
- </MessageScrollerItem>
- ) : item.kind === "attachments" ? (
- <MessageScrollerItem
- key={item.id}
- messageId={item.id}
- scrollAnchor={anchorRows.has(item.id)}
- >
- <TranscriptAttachments
- attachments={item.attachments}
- delay={delays.delayFor(item.id, index, items.length)}
- />
- </MessageScrollerItem>
- ) : (
- // Every member of the union is handled above. `assertNever` types `item` as
- // `never` here, so a future addition to `VisibleChatItem` fails to typecheck at
- // this call instead of silently falling into this branch and rendering nothing.
- assertNever(item)
- ),
- )}
- </MessageScrollerContent>
- </MessageScrollerViewport>
- <MessageScrollerButton />
- <ScrollNewestQueuedIntoView newest={queued.at(-1)?.id ?? null} />
- </MessageScroller>
- </MessageScrollerProvider>
+ ))}
+ </div>
+ {items
+ .slice(pages.split)
+ .map((item, offset) => renderRow(item, pages.split + offset))}
+ </MessageScrollerContent>
+ </MessageScrollerViewport>
+ <MessageScrollerButton
+ onClick={(event) => {
+ // Ours, not the scroller's: it would scroll before it had been told to follow again.
+ event.preventDefault();
+ dispatchFollow({ type: "button" });
+ }}
+ />
+ <ScrollNewestQueuedIntoView
+ newest={queued.at(-1)?.id ?? null}
+ onQueued={followOnQueued}
+ />
+ <FollowScroll request={follow.request} />
+ <TranscriptRail active={activeTurn} onJump={jump} turns={turns} />
+ </MessageScroller>
+ </MessageScrollerProvider>
+ </LateRenderersContext.Provider>
+ </ArrivalsLive>
);
}
diff --git a/app/src/components/channels/follow-intent.tsx b/app/src/components/channels/follow-intent.tsx
new file mode 100644
index 00000000..7c36156a
--- /dev/null
+++ b/app/src/components/channels/follow-intent.tsx
@@ -0,0 +1,306 @@
+import { useReducedMotion } from "motion/react";
+import {
+ useCallback,
+ useEffect,
+ useLayoutEffect,
+ useRef,
+ useState,
+} from "react";
+import { useMessageScroller } from "@/components/ui/message-scroller";
+
+/**
+ * Whether the transcript follows a streaming reply, decided from what the person does.
+ *
+ * The scroller on its own follows whenever the view is at the end, and a layout change that leaves
+ * the view at the end looks the same to it as somebody scrolling there. So the decision is made
+ * here, from input events only: moving up the page (wheel, keys, a touch drag, a scrollbar drag)
+ * stops following at once, selecting text in the transcript pauses it, and it picks up again when
+ * the person comes back down near the end, presses the button, clears their selection or sends.
+ * A scroll with no input behind it (content growing, shrinking, the scroller's own moves) is never
+ * the person, and changes nothing.
+ */
+
+/** How close to the end, in pixels, scrolling back down picks following up again. */
+export const RESUME_PX = 80;
+
+export type FollowState = {
+ following: boolean;
+ pausedBy: "scroll" | "selection" | null;
+};
+
+export const FOLLOWING: FollowState = { following: true, pausedBy: null };
+
+export type FollowEvent =
+ | { type: "wheel"; deltaY: number }
+ | { type: "key"; key: string; shiftKey: boolean }
+ /* Positive: the finger moved down the screen, which scrolls the page up. */
+ | { type: "touch"; fingerDeltaY: number }
+ | {
+ type: "scroll";
+ top: number;
+ previousTop: number;
+ fromEnd: number;
+ pointerDown: boolean;
+ }
+ | { type: "selection"; active: boolean }
+ | { type: "button" }
+ /*
+ * A wheel, key or touch moving down the page. The scroller stops following the bottom on any
+ * input; at the end, where nothing scrolls, only a scroll to the end puts it back.
+ */
+ | { type: "down"; atEnd: boolean }
+ /* A mark on the rail: they went to a turn of their choosing, so stay with what they chose. */
+ | { type: "jump" }
+ | { type: "send" }
+ /* A message parked under the conversation: they are looking at the end, so go there. */
+ | { type: "queued" };
+
+export type FollowStep = {
+ state: FollowState;
+ scrollToEnd: ScrollBehavior | null;
+};
+
+const PAUSED_BY_SCROLL: FollowState = { following: false, pausedBy: "scroll" };
+const PAUSED_BY_SELECTION: FollowState = {
+ following: false,
+ pausedBy: "selection",
+};
+
+const UP_KEYS = new Set(["ArrowUp", "PageUp", "Home"]);
+const DOWN_KEYS = new Set(["ArrowDown", "PageDown", "End"]);
+
+/** Within this many pixels of the end, a downward input has nothing left to scroll. */
+const END_PX = 8;
+
+function movesUp(event: FollowEvent): boolean {
+ switch (event.type) {
+ case "wheel":
+ return event.deltaY < 0;
+ case "key":
+ return UP_KEYS.has(event.key) || (event.key === " " && event.shiftKey);
+ case "touch":
+ return event.fingerDeltaY > 0;
+ case "jump":
+ return true;
+ case "scroll":
+ // Only a scroll the person is dragging: the scrollbar, with a pointer held down on it.
+ return event.pointerDown && event.top < event.previousTop;
+ default:
+ return false;
+ }
+}
+
+export function nextFollow(state: FollowState, event: FollowEvent): FollowStep {
+ const same = { state, scrollToEnd: null };
+
+ if (movesUp(event)) {
+ return state.pausedBy === "scroll"
+ ? same
+ : { state: PAUSED_BY_SCROLL, scrollToEnd: null };
+ }
+
+ switch (event.type) {
+ case "scroll":
+ return state.pausedBy === "scroll" &&
+ event.top > event.previousTop &&
+ event.fromEnd <= RESUME_PX
+ ? { state: FOLLOWING, scrollToEnd: "auto" }
+ : same;
+ case "selection":
+ if (event.active && state.following) {
+ return { state: PAUSED_BY_SELECTION, scrollToEnd: null };
+ }
+ if (!event.active && state.pausedBy === "selection") {
+ return { state: FOLLOWING, scrollToEnd: "auto" };
+ }
+ return same;
+ case "down":
+ return state.following && event.atEnd
+ ? { state, scrollToEnd: "auto" }
+ : same;
+ case "button":
+ return { state: FOLLOWING, scrollToEnd: "smooth" };
+ case "send":
+ return { state: FOLLOWING, scrollToEnd: null };
+ case "queued":
+ return { state: FOLLOWING, scrollToEnd: "auto" };
+ default:
+ return same;
+ }
+}
+
+function isEditable(target: EventTarget): boolean {
+ return (
+ target instanceof HTMLElement &&
+ (target.isContentEditable ||
+ target.tagName === "INPUT" ||
+ target.tagName === "TEXTAREA" ||
+ target.tagName === "SELECT")
+ );
+}
+
+export type FollowRequest = { behavior: ScrollBehavior; tick: number };
+
+type ViewportHandlers = Pick<
+ React.ComponentProps<"div">,
+ | "onWheel"
+ | "onKeyDown"
+ | "onTouchStart"
+ | "onTouchMove"
+ | "onPointerDown"
+ | "onScroll"
+>;
+
+/**
+ * The follow state for one transcript, fed from the viewport's input events and from a selection
+ * anywhere inside it. Back to following whenever a conversation is being restored, so a channel
+ * opened next never inherits where the last one was left.
+ *
+ * `following` goes to the scroller as `autoScroll`; `request` is a scroll to the end that a resume
+ * asked for, carried out by `FollowScroll` inside the scroller once `autoScroll` is already true.
+ */
+export function useFollowIntent(
+ viewportRef: React.RefObject<HTMLDivElement | null>,
+ restoring: boolean,
+): {
+ following: boolean;
+ dispatch: (event: FollowEvent) => void;
+ request: FollowRequest | null;
+ viewportHandlers: ViewportHandlers;
+} {
+ const reducedMotion = useReducedMotion() ?? false;
+ const [state, setState] = useState(FOLLOWING);
+ const [request, setRequest] = useState<FollowRequest | null>(null);
+ const stateRef = useRef(state);
+
+ if (restoring && (state !== FOLLOWING || request !== null)) {
+ stateRef.current = FOLLOWING;
+ setState(FOLLOWING);
+ setRequest(null);
+ }
+
+ const dispatch = useCallback(
+ (event: FollowEvent) => {
+ const step = nextFollow(stateRef.current, event);
+ if (step.state !== stateRef.current) {
+ stateRef.current = step.state;
+ setState(step.state);
+ }
+ const behavior = step.scrollToEnd;
+ if (behavior !== null) {
+ setRequest((previous) => ({
+ behavior: reducedMotion ? "auto" : behavior,
+ tick: (previous?.tick ?? 0) + 1,
+ }));
+ }
+ },
+ [reducedMotion],
+ );
+
+ const pointerDownRef = useRef(false);
+ const previousTopRef = useRef(0);
+ const touchYRef = useRef<number | null>(null);
+
+ useEffect(() => {
+ const release = () => {
+ pointerDownRef.current = false;
+ };
+ // Only a selection inside the transcript: text selected in the composer is not reading.
+ const selectionChanged = () => {
+ const selection = document.getSelection();
+ const viewport = viewportRef.current;
+ dispatch({
+ type: "selection",
+ active:
+ selection !== null &&
+ !selection.isCollapsed &&
+ (viewport?.contains(selection.anchorNode) ?? false),
+ });
+ };
+ // A scrollbar drag can end with the pointer anywhere on the page.
+ window.addEventListener("pointerup", release);
+ window.addEventListener("pointercancel", release);
+ window.addEventListener("blur", release);
+ document.addEventListener("selectionchange", selectionChanged);
+ return () => {
+ window.removeEventListener("pointerup", release);
+ window.removeEventListener("pointercancel", release);
+ window.removeEventListener("blur", release);
+ document.removeEventListener("selectionchange", selectionChanged);
+ };
+ }, [dispatch, viewportRef]);
+
+ const down = (element: HTMLElement) =>
+ dispatch({
+ type: "down",
+ atEnd:
+ element.scrollHeight - element.scrollTop - element.clientHeight <=
+ END_PX,
+ });
+
+ const viewportHandlers: ViewportHandlers = {
+ onWheel: (event) => {
+ dispatch({ type: "wheel", deltaY: event.deltaY });
+ if (event.deltaY > 0) down(event.currentTarget);
+ },
+ onKeyDown: (event) => {
+ // A key typed into a field inside the transcript moves a caret, not the page.
+ if (event.defaultPrevented || isEditable(event.target)) return;
+ dispatch({ type: "key", key: event.key, shiftKey: event.shiftKey });
+ if (DOWN_KEYS.has(event.key) || (event.key === " " && !event.shiftKey)) {
+ down(event.currentTarget);
+ }
+ },
+ onTouchStart: (event) => {
+ touchYRef.current = event.touches[0]?.clientY ?? null;
+ },
+ onTouchMove: (event) => {
+ const y = event.touches[0]?.clientY;
+ if (y === undefined) return;
+ const last = touchYRef.current;
+ touchYRef.current = y;
+ if (last === null) return;
+ dispatch({ type: "touch", fingerDeltaY: y - last });
+ // The finger moving up the screen scrolls the page down.
+ if (y < last) down(event.currentTarget);
+ },
+ onPointerDown: (event) => {
+ /*
+ * A press on the viewport itself, not on anything in it: its scrollbar, or the bare margin
+ * beside the conversation. Not a gutter check: an overlay scrollbar (macOS with a trackpad)
+ * takes no width and a right-to-left one sits on the left, so a thumb is pressed inside the
+ * content box. A press on a message is never a drag, so a layout clamp under a finger
+ * resting on one is still not the person's.
+ */
+ pointerDownRef.current = event.target === event.currentTarget;
+ },
+ onScroll: (event) => {
+ const element = event.currentTarget;
+ const top = element.scrollTop;
+ const previousTop = previousTopRef.current;
+ previousTopRef.current = top;
+ dispatch({
+ type: "scroll",
+ top,
+ previousTop,
+ fromEnd: element.scrollHeight - top - element.clientHeight,
+ pointerDown: pointerDownRef.current,
+ });
+ },
+ };
+
+ return { following: state.following, dispatch, request, viewportHandlers };
+}
+
+/**
+ * Carries out a resume's scroll to the end. Renders nothing; it lives inside the scroller to reach
+ * it, and runs in the commit after the resume, when the scroller has already been told to follow, so
+ * the scroll leaves it following rather than free.
+ */
+export function FollowScroll({ request }: { request: FollowRequest | null }) {
+ const { scrollToEnd } = useMessageScroller();
+ useLayoutEffect(() => {
+ if (request !== null) scrollToEnd({ behavior: request.behavior });
+ }, [request, scrollToEnd]);
+ return null;
+}
diff --git a/app/src/components/channels/group-chat.tsx b/app/src/components/channels/group-chat.tsx
index 4e3cf193..2515ce93 100644
--- a/app/src/components/channels/group-chat.tsx
+++ b/app/src/components/channels/group-chat.tsx
@@ -1,6 +1,6 @@
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { Link } from "@tanstack/react-router";
-import { useEffect, useRef } from "react";
+import { useLayoutEffect, useRef } from "react";
import { Streamdown } from "streamdown";
import { Bubble, BubbleContent } from "@/components/ui/bubble";
import {
@@ -42,12 +42,36 @@ export function GroupChat({ channelId }: { channelId: string }) {
(message) => message.status === "running" || message.status === "queued",
);
- // Follow the conversation down as lines arrive, the way the single-Bot transcript does.
- const endRef = useRef<HTMLDivElement | null>(null);
- const lastKey = `${messages.length}:${messages.at(-1)?.status ?? ""}`;
- useEffect(() => {
- if (lastKey) endRef.current?.scrollIntoView({ block: "end" });
- }, [lastKey]);
+ /*
+ * LAND AT THE BOTTOM BEFORE THE FIRST PAINT, THEN FOLLOW ONLY A READER WHO IS STILL THERE.
+ *
+ * This was `scrollIntoView` in a `useEffect`, which runs after the browser has painted: every
+ * group chat showed its top for a frame and then jumped. A layout effect moves it before paint.
+ * And it followed every new line unconditionally, pulling somebody reading an earlier answer back
+ * down each time a Bot spoke; `atBottom` is where the reader was at their last scroll.
+ */
+ const viewportRef = useRef<HTMLDivElement | null>(null);
+ const atBottom = useRef(true);
+ // Once per mount, which is once per channel: the route keys `GroupChat` on its channel id.
+ const landed = useRef(false);
+ const newest = messages.at(-1);
+ const newestIsMine = newest !== undefined && newest.ownerUserId === me?.id;
+ const lastKey = `${messages.length}:${newest?.status ?? ""}`;
+ useLayoutEffect(() => {
+ const element = viewportRef.current;
+ if (element === null || lastKey === "0:") return;
+ if (
+ shouldFollowGroup({
+ landed: landed.current,
+ atBottom: atBottom.current,
+ newestIsMine,
+ })
+ ) {
+ element.scrollTop = element.scrollHeight;
+ landed.current = true;
+ atBottom.current = true;
+ }
+ }, [lastKey, newestIsMine]);
if (group.isPending) return null;
if (group.isError)
@@ -59,7 +83,13 @@ export function GroupChat({ channelId }: { channelId: string }) {
return (
<div className="flex min-h-0 flex-1 flex-col">
- <div className="min-h-0 flex-1 overflow-y-auto">
+ <div
+ className="min-h-0 flex-1 overflow-y-auto"
+ onScroll={(event) => {
+ atBottom.current = isNearBottom(event.currentTarget);
+ }}
+ ref={viewportRef}
+ >
<div className="mx-auto flex w-full max-w-2xl flex-col gap-5 py-6">
{messages.length === 0 ? (
<p className="text-sm text-muted-foreground">
@@ -86,7 +116,6 @@ export function GroupChat({ channelId }: { channelId: string }) {
mine={message.ownerUserId === me?.id}
/>
))}
- <div ref={endRef} />
</div>
</div>
{/* The same column and the same compact composer as a conversation with one Bot. */}
@@ -212,3 +241,38 @@ function GroupLine({
</MessageRow>
);
}
+
+/**
+ * Whether a scrolled element is close enough to its end to count as reading the newest line.
+ *
+ * Exported so it can be checked without mounting anything.
+ */
+export function isNearBottom(
+ element: { scrollTop: number; scrollHeight: number; clientHeight: number },
+ threshold = 80,
+): boolean {
+ return (
+ element.scrollHeight - element.scrollTop - element.clientHeight <= threshold
+ );
+}
+
+/**
+ * Whether the group chat moves to its newest line.
+ *
+ * Always on opening, and always for the person's own message: they just sent it and are looking for
+ * it. A Bot's line only for a reader already at the bottom, so somebody reading an earlier answer
+ * keeps their place.
+ *
+ * Exported so it can be checked without mounting anything.
+ */
+export function shouldFollowGroup({
+ landed,
+ atBottom,
+ newestIsMine,
+}: {
+ landed: boolean;
+ atBottom: boolean;
+ newestIsMine: boolean;
+}): boolean {
+ return !landed || atBottom || newestIsMine;
+}
diff --git a/app/src/components/channels/late-renderers.tsx b/app/src/components/channels/late-renderers.tsx
new file mode 100644
index 00000000..acdee07a
--- /dev/null
+++ b/app/src/components/channels/late-renderers.tsx
@@ -0,0 +1,90 @@
+import { createContext, useEffect, useRef, useState } from "react";
+
+/** The part of the CopilotKit core this needs: its activity renderers, and a way to hear it connect. */
+type RendererCore = {
+ readonly renderActivityMessages: readonly unknown[];
+ subscribe(subscriber: { onRuntimeConnectionStatusChanged?: () => void }): {
+ unsubscribe(): void;
+ };
+};
+
+/** How many frames, after a trigger, to keep looking for the provider's swap before giving up. */
+const LOOK_FRAMES = 10;
+
+/**
+ * A version that goes up when the core's activity renderers change.
+ *
+ * The provider swaps that list in a passive effect when generative UI turns on (the capabilities
+ * answer arriving, `settled` here, or the runtime connecting) and notifies nobody, so an activity
+ * that rendered before then drew nothing and stayed that way until its own message changed. This
+ * looks again after each of those, ONE FRAME at a time for up to LOOK_FRAMES, because the provider's
+ * effect runs after this one and, under a cold start, can land a few frames later; it counts a change
+ * only when the list really is a different list.
+ */
+export function useLateRenderers(
+ core: RendererCore,
+ waiting: boolean,
+ settled: unknown,
+): number {
+ const [version, setVersion] = useState(0);
+ // The list last looked at, kept across looks so a change made before one is not missed.
+ const seenRef = useRef(core.renderActivityMessages);
+
+ // biome-ignore lint/correctness/useExhaustiveDependencies: `settled` is the trigger, not an input
+ useEffect(() => {
+ if (!waiting) return;
+ let frame = 0;
+ const look = (left = LOOK_FRAMES) => {
+ window.cancelAnimationFrame(frame);
+ frame = window.requestAnimationFrame(() => {
+ if (core.renderActivityMessages !== seenRef.current) {
+ seenRef.current = core.renderActivityMessages;
+ setVersion((current) => current + 1);
+ } else if (left > 1) {
+ look(left - 1);
+ }
+ });
+ };
+ const subscription = core.subscribe({
+ onRuntimeConnectionStatusChanged: () => look(),
+ });
+ look();
+ return () => {
+ window.cancelAnimationFrame(frame);
+ subscription.unsubscribe();
+ };
+ }, [core, waiting, settled]);
+
+ return version;
+}
+
+/**
+ * The renderers' version for every activity in a transcript. Read by an activity so it redraws when
+ * the renderers it found missing arrive; see `LateRenderersWatch`.
+ */
+export const LateRenderersContext = createContext(0);
+
+/**
+ * ONE subscription for a whole transcript. Each activity used to carry its own — a core
+ * subscription, a capabilities observer and a frame poll per row — to patch a signal the SDK does
+ * not send; here it is listened for once and handed up, for the transcript to pass down through
+ * `LateRenderersContext`.
+ *
+ * Renders nothing, so the transcript can mount it only while it has activities without changing the
+ * shape of its own tree (which would remount every row).
+ */
+export function LateRenderersWatch({
+ core,
+ settled,
+ onVersion,
+}: {
+ core: RendererCore;
+ settled: unknown;
+ onVersion: (version: number) => void;
+}) {
+ const version = useLateRenderers(core, true, settled);
+ useEffect(() => {
+ if (version > 0) onVersion(version);
+ }, [version, onVersion]);
+ return null;
+}
diff --git a/app/src/components/channels/paced-reveal.ts b/app/src/components/channels/paced-reveal.ts
new file mode 100644
index 00000000..a8aa483b
--- /dev/null
+++ b/app/src/components/channels/paced-reveal.ts
@@ -0,0 +1,152 @@
+import { useReducedMotion } from "motion/react";
+import { useEffect, useRef, useState } from "react";
+
+/**
+ * A streaming reply arrives in bursts: nothing for a moment, then a sentence at once. Drawn as it
+ * arrives, it reads as stuttering. Revealed at a steady pace a little behind what has arrived, it
+ * reads as being written. The pace has a floor, so a slow stream still moves, and a catch-up
+ * budget, so a big burst is worked off in well under a second rather than queued behind the floor.
+ *
+ * Revealed a word at a time: a prefix ends at the end of the text or just before whitespace, and
+ * while the stream is still going it stops short of the last word, because that word may be half
+ * sent — until the text has not grown for TAIL_SETTLES_MS, when the reply has ended its sentence
+ * and the run is busy with something else.
+ */
+
+/** The slowest the reveal ever goes, so a trickle of text still moves. */
+export const MIN_CHARS_PER_SECOND = 90;
+/** While streaming: how long a backlog takes to work off, at most, before the floor takes over. */
+export const CATCH_UP_MS = 400;
+/** After the stream ends: everything is out this long after, however much was still to show. */
+export const FINISH_MS = 300;
+
+const MIN_CHARS_PER_MS = MIN_CHARS_PER_SECOND / 1000;
+
+/** One frame at 60Hz, and the most one step may count: a tab in the background stalls frames. */
+const FRAME_MS = 16;
+const MAX_FRAME_MS = 50;
+
+function isSpace(character: string | undefined): boolean {
+ return character !== undefined && /\s/.test(character);
+}
+
+/**
+ * The longest run that counts as one word. Text with no spaces (Chinese, Japanese, a long link) has
+ * no word to stop at; past this it is revealed a character at a time rather than held whole.
+ */
+export const LONGEST_WORD = 24;
+/** A tail that has not grown for this long is the end of the reply, not half a word. */
+export const TAIL_SETTLES_MS = 250;
+
+/** The furthest prefix that may be shown: all of it, or while the tail may be half sent, up to it. */
+function limitOf(text: string, holdTail: boolean): number {
+ if (!holdTail) return text.length;
+ const end = Math.max(0, text.length - LONGEST_WORD);
+ for (let index = text.length - 1; index >= end; index--) {
+ if (isSpace(text[index])) return index;
+ }
+ return end;
+}
+
+export function nextReveal({
+ text,
+ shown,
+ elapsedMs,
+ streaming,
+ holdTail = streaming,
+ finishInMs,
+}: {
+ text: string;
+ shown: number;
+ elapsedMs: number;
+ streaming: boolean;
+ /** Whether the last word may still be arriving. While streaming, until the text settles. */
+ holdTail?: boolean;
+ finishInMs: number;
+}): number {
+ const floor = Math.min(shown, text.length);
+ const limit = limitOf(text, streaming && holdTail);
+ if (floor >= limit) return floor;
+
+ const backlog = text.length - floor;
+ const budget = streaming ? CATCH_UP_MS : Math.max(finishInMs, 1);
+ const rate = Math.max(MIN_CHARS_PER_MS, backlog / budget);
+ const target = Math.min(
+ limit,
+ floor + Math.max(1, Math.ceil(rate * elapsedMs)),
+ );
+
+ // Forward to the end of the word the target falls in, unless it is too long to be one.
+ const stop = Math.min(limit, target + LONGEST_WORD);
+ let next = target;
+ while (next < stop && !isSpace(text[next])) next++;
+ return next === stop && stop < limit ? target : next;
+}
+
+/**
+ * The part of `text` to draw now. A message that was already there when the conversation opened
+ * starts fully shown and only paces what grows after; one that arrived live starts from nothing.
+ * Reduced motion draws text as it arrives.
+ */
+export function usePacedReveal(
+ text: string,
+ { live, streaming }: { live: boolean; streaming: boolean },
+): string {
+ const reducedMotion = useReducedMotion() ?? false;
+ const [shown, setShown] = useState(() => (live ? 0 : text.length));
+ const finishAtRef = useRef<number | null>(null);
+ const grewAtRef = useRef(0);
+ const lengthRef = useRef(text.length);
+ if (text.length !== lengthRef.current) {
+ lengthRef.current = text.length;
+ grewAtRef.current = performance.now();
+ }
+
+ if (streaming) {
+ finishAtRef.current = null;
+ } else if (finishAtRef.current === null) {
+ finishAtRef.current = performance.now() + FINISH_MS;
+ }
+
+ const pending = !reducedMotion && shown < text.length;
+
+ /*
+ * ONE LOOP FOR AS LONG AS THERE IS TEXT TO SHOW, reading the newest text from refs. Tokens arrive
+ * every 10 to 20ms, between frames; restarting the loop on each one restarted its clock too, so
+ * the next frame measured the few ms since the token rather than the ~16ms since the last frame,
+ * and the reveal ran at a fraction of its pace, then dumped the backlog when the stream ended.
+ */
+ const textRef = useRef(text);
+ textRef.current = text;
+ const streamingRef = useRef(streaming);
+ streamingRef.current = streaming;
+
+ useEffect(() => {
+ if (!pending) return;
+ let last: number | null = null;
+ let frame = window.requestAnimationFrame(function step(now) {
+ // The first frame of a loop has no previous one; a frame's worth keeps it moving.
+ const elapsedMs = Math.min(
+ MAX_FRAME_MS,
+ Math.max(0, now - (last ?? now - FRAME_MS)),
+ );
+ last = now;
+ const finishAt = finishAtRef.current;
+ const current = textRef.current;
+ setShown((shownNow) =>
+ nextReveal({
+ text: current,
+ shown: shownNow,
+ elapsedMs,
+ streaming: streamingRef.current,
+ holdTail: now - grewAtRef.current < TAIL_SETTLES_MS,
+ finishInMs: finishAt === null ? FINISH_MS : finishAt - now,
+ }),
+ );
+ frame = window.requestAnimationFrame(step);
+ });
+ return () => window.cancelAnimationFrame(frame);
+ }, [pending]);
+
+ return pending ? text.slice(0, shown) : text;
+}
diff --git a/app/src/components/channels/tool-activity.tsx b/app/src/components/channels/tool-activity.tsx
index 05cd40ca..013b3a99 100644
--- a/app/src/components/channels/tool-activity.tsx
+++ b/app/src/components/channels/tool-activity.tsx
@@ -55,19 +55,24 @@ export type TranscriptItem = VisibleChatItem | ToolGroup;
*
* `isDrawn` says which tools the app draws itself; the transcript reads it from `useDrawnTool`.
*
- * The group takes its first step's id, so the row keeps its identity while later steps stream in.
+ * EVERY RUN IS A GROUP, A RUN OF ONE INCLUDED, AND KEEPS ITS ROW ID FOR ITS WHOLE LIFE. A lone call
+ * used to be its own `tool` row and became a `tools` row when a second call arrived, under the same
+ * key but a different tree, so React tore the row down and rebuilt it and its entrance replayed. A
+ * group took its first step's id, so when that step turned out to ask the person something and left,
+ * the group's id changed and it was rebuilt again. Now the transcript draws a group of one as the
+ * line it always was, inside the one row type, and `rowIds` remembers which row each step was drawn
+ * in: a run reuses the row of the first of its steps no earlier run in this pass has claimed. Group
+ * ids carry a `group:` prefix, so they can never collide with a single row's id.
*/
export function groupToolSteps(
items: readonly VisibleChatItem[],
isDrawn: (name: string) => boolean,
+ rowIds: Map<string, string> = new Map(),
): TranscriptItem[] {
- const grouped: TranscriptItem[] = [];
+ const segments: (VisibleChatItem | ToolItem[])[] = [];
let run: ToolItem[] = [];
const close = () => {
- const [first] = run;
- if (!first) return;
- if (run.length === 1 && !isBrowserStep(first)) grouped.push(first);
- else grouped.push({ kind: "tools", id: first.id, steps: run });
+ if (run.length > 0) segments.push(run);
run = [];
};
for (const item of items) {
@@ -76,10 +81,41 @@ export function groupToolSteps(
continue;
}
close();
- grouped.push(item);
+ segments.push(item);
}
close();
- return grouped;
+
+ // Runs claim their rows first, so a group keeps its row when its first step leaves it...
+ const claimed = new Set<string>();
+ const runIds = new Map<ToolItem[], string>();
+ for (const segment of segments) {
+ if (!Array.isArray(segment)) continue;
+ const [first] = segment;
+ if (!first) continue;
+ const kept = segment
+ .map((step) => rowIds.get(step.id))
+ .find((id) => id !== undefined && !claimed.has(id));
+ const id = kept ?? `group:${first.id}`;
+ claimed.add(id);
+ runIds.set(segment, id);
+ for (const step of segment) rowIds.set(step.id, id);
+ }
+
+ // ...and a lone call that stops folding (its answer asks the person) keeps the row it had.
+ return segments.map((segment): TranscriptItem => {
+ if (Array.isArray(segment)) {
+ return {
+ kind: "tools",
+ id: runIds.get(segment) ?? "",
+ steps: segment,
+ };
+ }
+ if (segment.kind !== "tool") return segment;
+ const previous = rowIds.get(segment.id);
+ if (previous === undefined || claimed.has(previous)) return segment;
+ claimed.add(previous);
+ return { ...segment, id: previous };
+ });
}
function foldable(item: ToolItem, isDrawn: (name: string) => boolean): boolean {
diff --git a/app/src/components/channels/tool-boundary.tsx b/app/src/components/channels/tool-boundary.tsx
index 73a9637c..83f2c6cb 100644
--- a/app/src/components/channels/tool-boundary.tsx
+++ b/app/src/components/channels/tool-boundary.tsx
@@ -1,4 +1,5 @@
import { Component, type ReactNode } from "react";
+import { ArgumentsArrivingContext } from "@/components/gallery/streaming";
/**
* A component that throws must not take the conversation with it.
@@ -8,16 +9,41 @@ import { Component, type ReactNode } from "react";
* as a user-readable failure line; stacks stay in the developer console.
*/
export class ToolRenderBoundary extends Component<
- { name: string; children: ReactNode },
- { failed: boolean }
+ {
+ name: string;
+ children: ReactNode;
+ /**
+ * Changes when the call's arguments do. A card that failed on arguments still streaming gets
+ * another chance with the next chunk, because half an argument list is often what it choked on.
+ */
+ resetKey?: unknown;
+ /** The call is complete: a failure now is about the arguments themselves, and it stays. */
+ final?: boolean;
+ },
+ { failed: boolean; failedFinal: boolean; key: unknown }
> {
- state = { failed: false };
+ static contextType = ArgumentsArrivingContext;
+ declare context: React.ContextType<typeof ArgumentsArrivingContext>;
+
+ state = { failed: false, failedFinal: false, key: undefined as unknown };
static getDerivedStateFromError() {
return { failed: true };
}
+ static getDerivedStateFromProps(
+ props: { resetKey?: unknown },
+ state: { failed: boolean; failedFinal: boolean; key: unknown },
+ ) {
+ if (props.resetKey === state.key) return null;
+ if (state.failed && !state.failedFinal && props.resetKey !== undefined) {
+ return { key: props.resetKey, failed: false };
+ }
+ return { key: props.resetKey };
+ }
+
componentDidCatch(error: unknown) {
+ this.setState({ failedFinal: Boolean(this.props.final) });
// Keep stack details out of the conversation while preserving them for component authors.
console.error(
"[gallery] a component failed to render",
@@ -27,6 +53,19 @@ export class ToolRenderBoundary extends Component<
}
render() {
+ /*
+ * Failed on arguments that are still arriving: nothing, until the next chunk retries it. Shown,
+ * the error box flashed between chunks for the whole stream of a card that then drew fine.
+ */
+ if (
+ this.state.failed &&
+ !this.state.failedFinal &&
+ !this.props.final &&
+ this.props.resetKey !== undefined &&
+ this.context
+ ) {
+ return null;
+ }
if (this.state.failed) {
return (
<p className="my-2 rounded-lg border border-destructive/30 bg-destructive/5 px-3 py-2 text-sm text-destructive">
@@ -38,3 +77,25 @@ export class ToolRenderBoundary extends Component<
return this.props.children;
}
}
+
+/**
+ * Whether a tool call can no longer change: it has a result, or its arguments are complete.
+ *
+ * NOT JUST THE RESULT. A decision has none until the person answers it, and the run stays busy for
+ * the whole wait, so a decision that threw on its complete arguments was taken for one still
+ * streaming and drew nothing; the turn hung invisibly until somebody pressed Stop. Streamed
+ * arguments are a JSON object whose closing brace comes last, so they parse only once the last of
+ * them has arrived.
+ */
+export function toolCallFinal(
+ args: string,
+ result: string | undefined,
+): boolean {
+ if (result !== undefined) return true;
+ try {
+ JSON.parse(args);
+ return true;
+ } catch {
+ return false;
+ }
+}
diff --git a/app/src/components/channels/transcript-pages.ts b/app/src/components/channels/transcript-pages.ts
new file mode 100644
index 00000000..5861acb0
--- /dev/null
+++ b/app/src/components/channels/transcript-pages.ts
@@ -0,0 +1,114 @@
+import { useCallback, useRef, useState } from "react";
+
+/**
+ * How many rows a conversation opens with, and how many more are drawn each time the reader nears
+ * the top. Twenty fills a tall screen with margin, so the reader never sees the edge of what is
+ * drawn on open; the rest of a long history costs nothing until somebody scrolls up to it.
+ */
+export const PAGE_ROWS = 20;
+
+/** How close to the top, in pixels, the reader gets before the previous page is drawn above. */
+export const LOAD_MARGIN_PX = 800;
+
+/** The index of the first row drawn when a conversation of `count` rows opens. */
+export function openingFrom(count: number): number {
+ return Math.max(0, count - PAGE_ROWS);
+}
+
+/** The index of the first row drawn once the page before `from` is added. */
+export function earlierFrom(from: number): number {
+ return Math.max(0, from - PAGE_ROWS);
+}
+
+/**
+ * Whether the reader is near enough the top to draw the page before. An unmeasured viewport
+ * (`scrollHeight` 0: nothing laid out yet) decides nothing.
+ */
+export function shouldDrawEarlier(view: {
+ from: number;
+ scrollTop: number;
+ scrollHeight: number;
+}): boolean {
+ return (
+ view.from > 0 && view.scrollHeight > 0 && view.scrollTop < LOAD_MARGIN_PX
+ );
+}
+
+/**
+ * Which rows are drawn: `items.slice(from)`. `split` is where drawing started when the conversation
+ * opened, fixed for as long as it stays open; rows before it were added later, above, and render in
+ * a region of their own (see the `contents` block in `chat-transcript.tsx`).
+ *
+ * BOTH ARE HELD AS ROWS, NOT INDICES. Rows are added and removed above them while a conversation is
+ * open — history recovered from storage merges in a prefix, tool steps regroup — and an index then
+ * named a different row: rows crossed the boundary into the live region under another parent, where
+ * they remounted, replayed their entrance and re-typed from nothing, and landed mid-list where the
+ * scroller reads a new turn. A row that has gone keeps the index it last had.
+ *
+ * Forgotten while restoring, the same way the opening stagger is, so a conversation opened again
+ * (or another channel) starts from its newest page.
+ */
+export function useTranscriptPages(
+ ids: readonly string[],
+ restoring: boolean,
+): {
+ from: number;
+ split: number;
+ drawEarlier: () => void;
+ drawTo: (index: number) => void;
+} {
+ /* One object per opening, so a page drawn for an earlier opening is recognisably not this one's. */
+ const openingRef = useRef<{ split: Mark } | null>(null);
+ const [earlier, setEarlier] = useState<{
+ opening: { split: Mark };
+ from: Mark;
+ } | null>(null);
+
+ if (restoring) {
+ openingRef.current = null;
+ } else if (openingRef.current === null) {
+ openingRef.current = { split: markAt(ids, openingFrom(ids.length)) };
+ }
+ const opening = openingRef.current;
+ const split = opening === null ? 0 : place(ids, opening.split);
+ const from =
+ earlier !== null && earlier.opening === opening
+ ? Math.min(place(ids, earlier.from), split)
+ : split;
+
+ const stateRef = useRef({ ids, from });
+ stateRef.current = { ids, from };
+ const drawFrom = useCallback((index: number) => {
+ const current = openingRef.current;
+ const { ids: now, from: drawn } = stateRef.current;
+ if (current === null || index >= drawn) return;
+ setEarlier({ opening: current, from: markAt(now, Math.max(0, index)) });
+ }, []);
+ const drawEarlier = useCallback(
+ () => drawFrom(earlierFrom(stateRef.current.from)),
+ [drawFrom],
+ );
+
+ /* `drawTo`: every page down to the row at `index`, for a jump to a turn not drawn yet. */
+ return { from, split, drawEarlier, drawTo: drawFrom };
+}
+
+/**
+ * A row the boundary sits on, and the index it had when last seen. `id` null is the very start of a
+ * conversation that had no rows: rows arriving into it are live.
+ */
+type Mark = { id: string | null; index: number };
+
+function markAt(ids: readonly string[], index: number): Mark {
+ return { id: ids[index] ?? null, index: Math.min(index, ids.length) };
+}
+
+function place(ids: readonly string[], mark: Mark): number {
+ if (mark.id === null) return Math.min(mark.index, ids.length);
+ const index = ids.indexOf(mark.id);
+ if (index !== -1) {
+ mark.index = index;
+ return index;
+ }
+ return Math.min(mark.index, ids.length);
+}
diff --git a/app/src/components/channels/transcript-rail.tsx b/app/src/components/channels/transcript-rail.tsx
new file mode 100644
index 00000000..3c8b82b3
--- /dev/null
+++ b/app/src/components/channels/transcript-rail.tsx
@@ -0,0 +1,147 @@
+import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip";
+import { memo, useEffect, useRef } from "react";
+import { cn } from "@/lib/utils";
+import type { Turn } from "./transcript-turns";
+
+type RailProps = {
+ turns: readonly Turn[];
+ /** The id of the turn being read. */
+ active: string | null;
+ onJump: (turn: Turn) => void;
+};
+
+function sameTurn(a: Turn, b: Turn): boolean {
+ return (
+ a.id === b.id &&
+ a.index === b.index &&
+ a.prompt === b.prompt &&
+ a.reply === b.reply
+ );
+}
+
+/**
+ * The transcript re-renders on every streamed chunk and rebuilds its turns each time; the rail
+ * redraws only when what it shows has changed, and then only the marks that did.
+ */
+export function sameRail(a: RailProps, b: RailProps): boolean {
+ return (
+ a.active === b.active &&
+ a.onJump === b.onJump &&
+ a.turns.length === b.turns.length &&
+ a.turns.every((turn, index) => {
+ const other = b.turns[index];
+ return other !== undefined && sameTurn(turn, other);
+ })
+ );
+}
+
+/**
+ * A rail in the margin beside a conversation: a mark per turn, the one being read drawn longer.
+ * Hovering or focusing a mark previews its turn — what the person sent, and the start of the
+ * reply — and choosing it goes there.
+ *
+ * Only where the margin is wide enough to hold it (`@3xl` of the scroller: the transcript's
+ * `max-w-2xl` column and a gutter either side), and only once there is more than one turn to move
+ * between.
+ */
+export const TranscriptRail = memo(function TranscriptRail({
+ turns,
+ active,
+ onJump,
+}: RailProps) {
+ const listRef = useRef<HTMLOListElement | null>(null);
+
+ /* A long conversation's rail scrolls; keep the current mark on it. */
+ useEffect(() => {
+ if (active === null) return;
+ listRef.current
+ ?.querySelector<HTMLElement>(`[data-turn="${CSS.escape(active)}"]`)
+ ?.scrollIntoView?.({ block: "nearest" });
+ }, [active]);
+
+ if (turns.length < 2) return null;
+
+ return (
+ <nav
+ aria-label="Turns"
+ className="pointer-events-none absolute inset-y-0 left-2 z-10 hidden items-center @3xl:flex"
+ >
+ <ol
+ className="pointer-events-auto flex max-h-[min(60vh,32rem)] flex-col overflow-y-auto py-2 [scrollbar-width:none]"
+ ref={listRef}
+ >
+ {turns.map((turn) => (
+ <li key={turn.id}>
+ <RailMark
+ current={turn.id === active}
+ onJump={onJump}
+ turn={turn}
+ />
+ </li>
+ ))}
+ </ol>
+ </nav>
+ );
+}, sameRail);
+
+const RailMark = memo(function RailMark({
+ turn,
+ current,
+ onJump,
+}: {
+ turn: Turn;
+ current: boolean;
+ onJump: (turn: Turn) => void;
+}) {
+ return (
+ <TooltipPrimitive.Root>
+ <TooltipPrimitive.Trigger
+ aria-current={current ? "true" : undefined}
+ aria-label={turn.prompt}
+ className="group flex h-3 w-8 cursor-pointer items-center rounded-sm px-2 outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ data-slot="rail-mark"
+ data-turn={turn.id}
+ delay={0}
+ onClick={() => onJump(turn)}
+ >
+ <span
+ className={cn(
+ "h-0.5 rounded-full transition-[width,background-color] duration-150 motion-reduce:transition-none",
+ current
+ ? "w-4 bg-foreground"
+ : "w-2.5 bg-muted-foreground/40 group-hover:w-4 group-hover:bg-muted-foreground group-focus-visible:w-4",
+ )}
+ />
+ </TooltipPrimitive.Trigger>
+ <TooltipPrimitive.Portal>
+ <TooltipPrimitive.Positioner
+ align="center"
+ className="isolate z-50"
+ side="right"
+ sideOffset={8}
+ >
+ <TooltipPrimitive.Popup
+ className="w-80 origin-(--transform-origin) rounded-xl border bg-popover p-4 text-popover-foreground shadow-md data-closed:animate-out data-closed:fade-out-0 data-open:animate-in data-open:fade-in-0 motion-reduce:animate-none"
+ data-slot="rail-preview"
+ >
+ <p className="truncate font-medium text-sm">{turn.prompt}</p>
+ {turn.reply ? (
+ <p className="mt-1 line-clamp-3 text-muted-foreground text-sm">
+ {turn.reply}
+ </p>
+ ) : null}
+ </TooltipPrimitive.Popup>
+ </TooltipPrimitive.Positioner>
+ </TooltipPrimitive.Portal>
+ </TooltipPrimitive.Root>
+ );
+}, sameMark);
+
+function sameMark(
+ a: { turn: Turn; current: boolean; onJump: (turn: Turn) => void },
+ b: { turn: Turn; current: boolean; onJump: (turn: Turn) => void },
+): boolean {
+ return (
+ a.current === b.current && a.onJump === b.onJump && sameTurn(a.turn, b.turn)
+ );
+}
diff --git a/app/src/components/channels/transcript-turns.ts b/app/src/components/channels/transcript-turns.ts
new file mode 100644
index 00000000..fad0b9ec
--- /dev/null
+++ b/app/src/components/channels/transcript-turns.ts
@@ -0,0 +1,130 @@
+import { readFiring } from "@/lib/channels/routine-firing";
+import type { TranscriptItem } from "./tool-activity";
+
+/**
+ * Whether a text item is the person actually sending something, as opposed to a routine firing that
+ * merely arrived wearing `role: "user"`.
+ *
+ * A FIRING IS NOT THE PERSON SPEAKING — `TranscriptMessage` already knows that and draws it as
+ * `RoutineFiring` rather than as their bubble, via the same `readFiring` check used here. The scroll
+ * machinery was the one place left that had not caught up: it smooth-scrolled and anchored on
+ * `role === "user"` alone, so a routine firing while somebody was reading back through the channel
+ * yanked their viewport to the bottom as though they had just typed and sent something. They hadn't;
+ * the schedule had. Exported so this can be checked without mounting anything.
+ */
+export function isPersonSentMessage(
+ role: "user" | "assistant",
+ text: string,
+): boolean {
+ return role === "user" && readFiring(text) === null;
+}
+
+/** One mark on the rail: the row it jumps to, and what its preview says. */
+export type Turn = {
+ /** The id of the turn's first row, which is also its `data-message-id`. */
+ id: string;
+ /** That row's place in the transcript's items, so a jump knows which page to draw. */
+ index: number;
+ prompt: string;
+ /** The first thing the Bot said back, or "" while it hasn't. */
+ reply: string;
+};
+
+function isPersons(item: TranscriptItem): boolean {
+ return (
+ (item.kind === "text" && isPersonSentMessage(item.role, item.text)) ||
+ item.kind === "attachments"
+ );
+}
+
+/*
+ * The turns are rebuilt on every streamed chunk, and stripping every message again each time was the
+ * per-token cost the rest of the transcript avoids. Each text is stripped once; only the reply still
+ * growing is new on a chunk. Cleared whole when it grows large, which only a very long session reaches.
+ */
+const plainCache = new Map<string, string>();
+const PLAIN_CACHE_SIZE = 1000;
+
+/** Markdown read as the words a preview shows: no headings, emphasis, code marks or link targets. */
+export function plainWords(markdown: string): string {
+ const cached = plainCache.get(markdown);
+ if (cached !== undefined) return cached;
+ if (plainCache.size >= PLAIN_CACHE_SIZE) plainCache.clear();
+ const plain = strip(markdown);
+ plainCache.set(markdown, plain);
+ return plain;
+}
+
+function strip(markdown: string): string {
+ return markdown
+ .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+ .replace(/^\s{0,3}(#{1,6}|>|[-*+]|\d+\.)\s+/gm, "")
+ .replace(/[*_~`]+/g, "")
+ .replace(/\s+/g, " ")
+ .trim();
+}
+
+/**
+ * The conversation's turns, oldest first. A turn starts where the person sent something — text, or
+ * files, which arrive as their own row beside the caption and are one turn with it — and runs until
+ * they send again. A routine firing starts none: nobody typed it.
+ */
+export function turnsOf(items: readonly TranscriptItem[]): Turn[] {
+ const turns: Turn[] = [];
+ let current: Turn | null = null;
+ let files = 0;
+ let previousWasPersons = false;
+
+ items.forEach((item, index) => {
+ const persons = isPersons(item);
+ if (persons && !previousWasPersons) {
+ current = { id: item.id, index, prompt: "", reply: "" };
+ files = 0;
+ turns.push(current);
+ }
+ previousWasPersons = persons;
+ if (current === null) return;
+
+ if (persons) {
+ if (item.kind === "text") {
+ current.prompt = plainWords(item.text);
+ } else if (item.kind === "attachments") {
+ files += item.attachments.length;
+ if (current.prompt === "") {
+ current.prompt = files === 1 ? "1 file" : `${files} files`;
+ }
+ }
+ } else if (
+ item.kind === "text" &&
+ item.role === "assistant" &&
+ current.reply === ""
+ ) {
+ current.reply = plainWords(item.text);
+ }
+ });
+
+ return turns;
+}
+
+/** How close to the end, in pixels, counts as being at the end of the conversation. */
+export const AT_END_PX = 8;
+
+/**
+ * Which turn is being read, from where each drawn turn's first row starts relative to the view: the
+ * last to start above `line` (a third of the way down), or the first drawn when none has. At the end
+ * of the conversation it is the last turn, which may be too short to reach the line: opened at the
+ * bottom, a short last answer starts low on the screen, and the turn before it would win.
+ */
+export function currentTurn(
+ rows: readonly { id: string; top: number }[],
+ line: number,
+ atEnd: boolean,
+): string | null {
+ if (atEnd) return rows.at(-1)?.id ?? null;
+ let current: string | null = null;
+ for (const row of rows) {
+ if (current !== null && row.top > line) break;
+ current = row.id;
+ }
+ return current;
+}
diff --git a/app/src/components/gallery/cards.tsx b/app/src/components/gallery/cards.tsx
index 8e60b1d6..eb871fc0 100644
--- a/app/src/components/gallery/cards.tsx
+++ b/app/src/components/gallery/cards.tsx
@@ -1,6 +1,7 @@
import { z } from "zod";
import type { GalleryComponent } from "@/lib/copilot/gallery-registry";
import { Badge, GalleryFrame, type Tone } from "./frame";
+import { byPosition } from "./positions";
const tone = z
.enum(["neutral", "positive", "caution", "negative"])
@@ -43,8 +44,9 @@ export function RecordCard({
title={title}
>
<dl className="grid grid-cols-[minmax(0,10rem)_1fr] gap-x-4 gap-y-2 text-sm">
- {fields.map((field) => (
- <div className="contents" key={field.label}>
+ {byPosition(fields).map(({ item: field, key }) => (
+ // Keyed by position: a label is still being typed while the card draws.
+ <div className="contents" key={key}>
<dt className="truncate text-muted-foreground">{field.label}</dt>
{/* Field values wrap because truncation can hide the reported data. */}
<dd className="min-w-0 break-words">{field.value}</dd>
@@ -85,8 +87,8 @@ export function MetricsCard({
return (
<GalleryFrame caption={caption} title={title}>
<div className="grid grid-cols-2 gap-x-6 gap-y-4 sm:grid-cols-3">
- {metrics.map((metric) => (
- <div key={metric.label}>
+ {byPosition(metrics).map(({ item: metric, key }) => (
+ <div key={key}>
<p className="truncate text-xs text-muted-foreground">
{metric.label}
</p>
@@ -148,8 +150,8 @@ export function ChecklistCard({
title={title}
>
<ul className="space-y-2">
- {items.map((item) => (
- <li className="flex items-start gap-2.5 text-sm" key={item.text}>
+ {byPosition(items).map(({ item, key }) => (
+ <li className="flex items-start gap-2.5 text-sm" key={key}>
<span
aria-hidden="true"
className={`mt-0.5 flex size-4 shrink-0 items-center justify-center rounded-[5px] border text-[10px] ${
@@ -209,8 +211,8 @@ export function NoticeCard({
<p className="text-sm">{body}</p>
{points?.length ? (
<ul className="mt-2 space-y-1 text-sm text-muted-foreground">
- {points.map((entry) => (
- <li className="flex gap-2" key={entry}>
+ {byPosition(points).map(({ item: entry, key }) => (
+ <li className="flex gap-2" key={key}>
<span aria-hidden="true">·</span>
<span className="min-w-0">{entry}</span>
</li>
diff --git a/app/src/components/gallery/charts.tsx b/app/src/components/gallery/charts.tsx
index c1d815f9..8b95d89c 100644
--- a/app/src/components/gallery/charts.tsx
+++ b/app/src/components/gallery/charts.tsx
@@ -2,6 +2,7 @@ import { z } from "zod";
import type { GalleryComponent } from "@/lib/copilot/gallery-registry";
import { GalleryFrame } from "./frame";
import { seriesColour } from "./palette";
+import { byPosition } from "./positions";
const point = z.object({
label: z
@@ -102,8 +103,8 @@ function Sources({ basis, sources, asOf: when }: Provenance) {
<>
{unchecked ? " · " : null}
{"Sources: "}
- {named.map((entry, index) => (
- <span key={`${entry.title}|${entry.url ?? ""}`}>
+ {byPosition(named).map(({ item: entry, key }, index) => (
+ <span key={key}>
{index > 0 ? ", " : null}
{entry.url ? (
<a
@@ -134,7 +135,16 @@ function Sources({ basis, sources, asOf: when }: Provenance) {
/** Charts share a height so several in one answer do not stagger down the page. */
const HEIGHT = 180;
-function formatNumber(value: number): string {
+/**
+ * A value that has arrived. While a chart streams, a point can be there before its number is, and
+ * dividing by it drew a bar `NaN%` tall that collapsed and then popped in.
+ */
+function isValue(value: unknown): value is number {
+ return typeof value === "number" && Number.isFinite(value);
+}
+
+function formatNumber(value: unknown): string {
+ if (!isValue(value)) return "";
if (Math.abs(value) >= 1000) {
return value.toLocaleString(undefined, { maximumFractionDigits: 0 });
}
@@ -153,8 +163,8 @@ function Empty() {
function Legend({ items }: { items: { label: string; colour: string }[] }) {
return (
<ul className="mt-3 flex flex-wrap gap-x-4 gap-y-1">
- {items.map((item) => (
- <li className="flex items-center gap-1.5 text-xs" key={item.label}>
+ {byPosition(items).map(({ item, key }) => (
+ <li className="flex items-center gap-1.5 text-xs" key={key}>
<span
className="size-2 shrink-0 rounded-[3px]"
style={{ background: item.colour }}
@@ -180,7 +190,10 @@ export function BarChartCard({
...origin
}: Partial<z.infer<typeof BarChartProps>>) {
const points = given ?? [];
- const max = Math.max(...points.map((entry) => entry.value ?? 0), 0);
+ const max = Math.max(
+ ...points.map((entry) => (isValue(entry.value) ? entry.value : 0)),
+ 0,
+ );
return (
<GalleryFrame caption={caption} title={title}>
{points.length === 0 ? (
@@ -188,10 +201,10 @@ export function BarChartCard({
) : (
// Columns stretch to full row height so percentage bar heights use the chart area.
<div className="flex items-stretch gap-2" style={{ height: HEIGHT }}>
- {points.map((entry, index) => (
+ {byPosition(points).map(({ item: entry, key }, index) => (
<div
className="flex min-w-0 flex-1 flex-col items-center justify-end gap-1.5"
- key={entry.label}
+ key={key}
>
<span className="text-xs tabular-nums text-muted-foreground">
{formatNumber(entry.value)}
@@ -200,14 +213,17 @@ export function BarChartCard({
their natural height and only the bar itself scales. */}
<div className="flex w-full flex-1 items-end">
<div
- className="w-full rounded-t-md transition-[height]"
+ className={`w-full rounded-t-md transition-[height] ${isValue(entry.value) ? "" : "bg-muted"}`}
style={{
// Normalize to the largest bar so similar values still show their differences.
+ // A bar whose number has not arrived holds the floor in a muted tone.
height:
- max > 0
+ max > 0 && isValue(entry.value)
? `${Math.max((entry.value / max) * 100, 2)}%`
: "2%",
- background: seriesColour(index),
+ ...(isValue(entry.value)
+ ? { background: seriesColour(index) }
+ : {}),
}}
/>
</div>
@@ -241,11 +257,17 @@ export function PieChartCard({
const stroke = 28;
const radius = (size - stroke) / 2;
const circumference = 2 * Math.PI * radius;
- const total = points.reduce((sum, entry) => sum + (entry.value || 0), 0);
+ const total = points.reduce(
+ (sum, entry) => sum + (isValue(entry.value) ? entry.value : 0),
+ 0,
+ );
let travelled = 0;
const slices = points.map((entry, index) => {
- const arc = total > 0 ? (entry.value / total) * circumference : 0;
+ const arc =
+ total > 0 && isValue(entry.value)
+ ? (entry.value / total) * circumference
+ : 0;
const slice = {
...entry,
arc,
@@ -270,12 +292,12 @@ export function PieChartCard({
viewBox={`0 0 ${size} ${size}`}
width={size}
>
- {slices.map((slice) => (
+ {byPosition(slices).map(({ item: slice, key }) => (
<circle
cx={size / 2}
cy={size / 2}
fill="none"
- key={slice.label}
+ key={key}
r={radius}
stroke={slice.colour}
strokeDasharray={`${slice.arc} ${circumference - slice.arc}`}
@@ -285,15 +307,17 @@ export function PieChartCard({
))}
</svg>
<ul className="min-w-0 flex-1 space-y-1.5">
- {slices.map((slice) => (
- <li className="flex items-center gap-2 text-sm" key={slice.label}>
+ {byPosition(slices).map(({ item: slice, key }) => (
+ <li className="flex items-center gap-2 text-sm" key={key}>
<span
className="size-2.5 shrink-0 rounded-[3px]"
style={{ background: slice.colour }}
/>
<span className="min-w-0 flex-1 truncate">{slice.label}</span>
<span className="tabular-nums text-muted-foreground">
- {Math.round((slice.value / total) * 100)}%
+ {isValue(slice.value)
+ ? `${Math.round((slice.value / total) * 100)}%`
+ : ""}
</span>
</li>
))}
@@ -370,13 +394,13 @@ function Plot({
y2={pad.top + fraction * (height - pad.top - pad.bottom)}
/>
))}
- {series.map((line, index) => {
+ {byPosition(series).map(({ item: line, key }, index) => {
const points = line.values.map(
(value, i) => `${xAt(i)},${yAt(value)}`,
);
const colour = seriesColour(index);
return (
- <g key={line.name}>
+ <g key={key}>
{filled ? (
<polygon
fill={colour}
@@ -397,8 +421,8 @@ function Plot({
})}
</svg>
<div className="flex justify-between">
- {labels.map((label) => (
- <span className="truncate text-xs text-muted-foreground" key={label}>
+ {byPosition(labels).map(({ item: label, key }) => (
+ <span className="truncate text-xs text-muted-foreground" key={key}>
{label}
</span>
))}
@@ -482,13 +506,13 @@ export function ProgressChartCard({
<Empty />
) : (
<ul className="space-y-3">
- {points.map((entry, index) => {
+ {byPosition(points).map(({ item: entry, key }, index) => {
const share =
- entry.target > 0
+ isValue(entry.value) && isValue(entry.target) && entry.target > 0
? Math.min((entry.value / entry.target) * 100, 100)
: 0;
return (
- <li key={entry.label}>
+ <li key={key}>
<div className="flex items-baseline justify-between gap-4 text-sm">
<span className="min-w-0 truncate">{entry.label}</span>
<span className="tabular-nums text-muted-foreground">
diff --git a/app/src/components/gallery/decisions.tsx b/app/src/components/gallery/decisions.tsx
index bca8064f..e1a941c8 100644
--- a/app/src/components/gallery/decisions.tsx
+++ b/app/src/components/gallery/decisions.tsx
@@ -3,6 +3,7 @@ import { z } from "zod";
import { Button } from "@/components/ui/button";
import type { GalleryComponent } from "@/lib/copilot/gallery-registry";
import { Badge, GalleryFrame } from "./frame";
+import { byPosition } from "./positions";
/**
* Human-in-the-loop gallery components. `respond` resolves the suspended Bot run, and completed
@@ -82,8 +83,8 @@ export function ApprovalCard(props: Waiting<ApprovalArgs> & { name?: string }) {
{args.details?.length ? (
<dl className="mt-3 grid grid-cols-[minmax(0,9rem)_1fr] gap-x-4 gap-y-1.5 text-sm">
- {args.details.map((detail) => (
- <div className="contents" key={detail.label}>
+ {byPosition(args.details).map(({ item: detail, key }) => (
+ <div className="contents" key={key}>
<dt className="truncate text-muted-foreground">{detail.label}</dt>
<dd className="min-w-0 break-words">{detail.value}</dd>
</div>
@@ -241,8 +242,8 @@ function readChoice(result: string | undefined): string | undefined {
}
/**
- * `kind: "decision"` is what makes these suspend the run: they are registered with
- * `useHumanInTheLoop` rather than as ordinary tools, and the person's answer IS the tool result, so
+ * `kind: "decision"` is what makes these suspend the run: they are registered as human-in-the-loop
+ * tools (`useDecisionTool`) rather than as ordinary ones, and the person's answer IS the tool result, so
* there is no confirmation line to give the model.
*/
export const GALLERY: GalleryComponent[] = [
diff --git a/app/src/components/gallery/positions.ts b/app/src/components/gallery/positions.ts
new file mode 100644
index 00000000..b864832b
--- /dev/null
+++ b/app/src/components/gallery/positions.ts
@@ -0,0 +1,12 @@
+/**
+ * List items paired with a key for their position.
+ *
+ * A gallery component is drawn from arguments that are still arriving, so a label is often half
+ * typed: keyed on it, "Re", "Rev" and "Revenue" were three different items, each torn down and
+ * rebuilt as the next chunk came in, and two items that were briefly both "Q" shared a key. The
+ * model writes a list in order and only ever appends to it, so an item's position is the one thing
+ * about it that does not change while it streams.
+ */
+export function byPosition<T>(items: readonly T[]): { item: T; key: string }[] {
+ return items.map((item, position) => ({ item, key: `at-${position}` }));
+}
diff --git a/app/src/components/gallery/streaming.ts b/app/src/components/gallery/streaming.ts
new file mode 100644
index 00000000..66de54bb
--- /dev/null
+++ b/app/src/components/gallery/streaming.ts
@@ -0,0 +1,20 @@
+import { createContext } from "react";
+
+/**
+ * Whether the component is being drawn from a tool call that is still streaming.
+ *
+ * Provided by the conversation's gallery render. Everywhere else a component is drawn (a preview,
+ * an admin screen, a test) its arguments are complete, which is the default. A component reads it
+ * when something half written should be held in place rather than refused, and only then.
+ */
+export const GalleryStreamingContext = createContext(false);
+
+/**
+ * Whether a call's arguments may still be arriving at all: its row is the newest of a turn that is
+ * still running. The SDK's own status cannot say this on its own. It reports `inProgress` for any
+ * call with no result, so a call whose run was stopped, or whose page closed before it answered,
+ * reloads as `inProgress` for good; held back on that, its last bar stayed muted forever.
+ *
+ * The transcript provides it per row. Anywhere else nothing is known, and the status decides.
+ */
+export const ArgumentsArrivingContext = createContext(true);
diff --git a/app/src/components/gallery/table.tsx b/app/src/components/gallery/table.tsx
index 5b690607..e4bca29f 100644
--- a/app/src/components/gallery/table.tsx
+++ b/app/src/components/gallery/table.tsx
@@ -1,7 +1,9 @@
-import { useState } from "react";
+import { useContext, useState } from "react";
import { z } from "zod";
import type { GalleryComponent } from "@/lib/copilot/gallery-registry";
import { Badge, GalleryFrame } from "./frame";
+import { byPosition } from "./positions";
+import { GalleryStreamingContext } from "./streaming";
export const DataTableProps = z
.object({
@@ -33,13 +35,40 @@ export const DataTableProps = z
"Column labels must be unique and every row must have one cell per column",
);
+/**
+ * The table without its last row while that row is still being written.
+ *
+ * The table is validated whole, and a row must have one cell per column, so a row half written made
+ * the whole table invalid: it dropped to "Waiting for complete table data" every time a new row
+ * started, and a table whose last column is a number (held back while it arrives) never drew until
+ * the call ended. Only a short LAST row, and only while the call streams, is set aside: a short row
+ * anywhere else, or in a finished table, is still wrong.
+ */
+function withoutArrivingRow(props: Record<string, unknown>): {
+ table: Record<string, unknown>;
+ arriving: boolean;
+} {
+ const { columns, rows } = props;
+ if (!Array.isArray(columns) || !Array.isArray(rows) || rows.length === 0) {
+ return { table: props, arriving: false };
+ }
+ const last = rows.at(-1) as { cells?: unknown } | undefined;
+ const cells = Array.isArray(last?.cells) ? last.cells.length : 0;
+ if (cells >= columns.length) return { table: props, arriving: false };
+ return { table: { ...props, rows: rows.slice(0, -1) }, arriving: true };
+}
+
/** A real table: header buttons sort while the native row/column relationships stay intact. */
export function DataTable(props: Record<string, unknown>) {
const [sort, setSort] = useState<{
column: number;
ascending: boolean;
} | null>(null);
- const parsed = DataTableProps.safeParse(props);
+ const streaming = useContext(GalleryStreamingContext);
+ const { table, arriving } = streaming
+ ? withoutArrivingRow(props)
+ : { table: props, arriving: false };
+ const parsed = DataTableProps.safeParse(table);
if (!parsed.success) {
return (
<GalleryFrame title="Table">
@@ -86,9 +115,9 @@ export function DataTable(props: Record<string, unknown>) {
</caption>
<thead className="bg-muted/50 text-xs text-muted-foreground">
<tr>
- {columns.map((column, index) => (
+ {byPosition(columns).map(({ item: column, key }, index) => (
<th
- key={column}
+ key={key}
scope="col"
aria-sort={
sort?.column === index
@@ -132,9 +161,9 @@ export function DataTable(props: Record<string, unknown>) {
key={row.position}
className="even:bg-muted/20 hover:bg-muted/40"
>
- {columns.map((column, index) => (
+ {byPosition(columns).map(({ key }, index) => (
<td
- key={column}
+ key={key}
className={`min-w-24 max-w-xs break-words px-3 py-2.5 align-top ${typeof row.cells[index] === "number" ? "text-right tabular-nums" : ""}`}
>
{row.cells[index] === "" ? (
@@ -154,7 +183,18 @@ export function DataTable(props: Record<string, unknown>) {
))}
</tr>
))}
- {rows.length === 0 && (
+ {arriving ? (
+ // The row still being written, holding its place rather than the whole table waiting.
+ <tr>
+ <td
+ colSpan={columns.length}
+ className="px-3 py-2.5 text-muted-foreground"
+ >
+ <span aria-hidden="true">…</span>
+ </td>
+ </tr>
+ ) : null}
+ {rows.length === 0 && !arriving && (
<tr>
<td
colSpan={columns.length}
diff --git a/app/src/lib/copilot/gallery-tools.tsx b/app/src/lib/copilot/gallery-tools.tsx
index b8e1b8fd..d5ff84f3 100644
--- a/app/src/lib/copilot/gallery-tools.tsx
+++ b/app/src/lib/copilot/gallery-tools.tsx
@@ -1,8 +1,21 @@
-import { useFrontendTool, useHumanInTheLoop } from "@copilotkit/react-core/v2";
+import { useCopilotKit, useFrontendTool } from "@copilotkit/react-core/v2";
import { NOT_SHOWN, NOT_SHOWN_TAIL } from "@openbot/shared/component-markers";
import { useQuery, useQueryClient } from "@tanstack/react-query";
-import { useCallback, useEffect, useMemo, useState } from "react";
+import {
+ useCallback,
+ useEffect,
+ useContext,
+ useLayoutEffect,
+ useMemo,
+ useRef,
+ useState,
+ useSyncExternalStore,
+} from "react";
import { RefusedCard } from "@/components/gallery/refused";
+import {
+ ArgumentsArrivingContext,
+ GalleryStreamingContext,
+} from "@/components/gallery/streaming";
import {
agentComponentsQueryOptions,
announceGallery,
@@ -16,6 +29,14 @@ import {
type GalleryComponent,
galleryManifest,
} from "@/lib/copilot/gallery-registry";
+import {
+ cardState,
+ COULDNT_CHECK,
+ createGrantStore,
+ type GrantStore,
+ grantsFrom,
+} from "@/lib/copilot/grant-store";
+import { settledArgs } from "@/lib/copilot/settled-args";
/**
* Register compiled gallery components once per name, scoped to the active Bot with `available`.
@@ -36,7 +57,19 @@ export function GalleryTools() {
// See sandboxed-tools: the placeholder Bot is not fetchable, so the grant query waits for a
// surface to declare a real one.
const declared = useDeclaredBotId();
- const { data: granted } = useQuery(agentComponentsQueryOptions(declared));
+ const grantsQuery = useQuery(agentComponentsQueryOptions(declared));
+ const granted = grantsQuery.data;
+ // One store per mount; every card reads its grants from here (see `grant-store.ts`).
+ const [store] = useState(createGrantStore);
+ useEffect(() => {
+ store.set({
+ grants: grantsFrom({
+ data: granted,
+ isError: grantsQuery.isError,
+ enabled: declared !== undefined,
+ }),
+ });
+ }, [store, granted, grantsQuery.isError, declared]);
const held = useMemo(
() =>
new Map(
@@ -52,13 +85,19 @@ export function GalleryTools() {
<>
{GALLERY_COMPONENTS.map((spec) =>
spec.kind === "decision" ? (
- <GrantedDecision held={held} key={spec.name} spec={spec} />
+ <GrantedDecision
+ held={held}
+ key={spec.name}
+ spec={spec}
+ store={store}
+ />
) : (
<GrantedTool
grantsFor={grantsFor}
held={held}
key={spec.name}
spec={spec}
+ store={store}
/>
),
)}
@@ -70,64 +109,17 @@ function GrantedTool({
grantsFor,
spec,
held,
+ store,
}: {
grantsFor: string;
spec: GalleryComponent;
held: Map<string, string>;
+ store: GrantStore;
}) {
const description = held.get(spec.name);
const isHeld = description !== undefined;
-
- /**
- * Refusals decided by the server, keyed by the call they refused.
- *
- * Per-call keys preserve the original render for calls made before a grant was revoked.
- */
- const [refusals, setRefusals] = useState<ReadonlyMap<string, string>>(
- new Map(),
- );
-
- const Component = spec.Component;
-
- const render = useCallback(
- (props: {
- toolCallId?: string;
- args?: Record<string, unknown>;
- result?: string;
- }) => {
- const refusal = props.toolCallId
- ? refusals.get(props.toolCallId)
- : undefined;
- if (refusal) {
- return <RefusedCard reason={refusal} title={spec.title} />;
- }
- /*
- * A stored refusal. The in-memory map above is gone once the page reloads, and a headless turn
- * never had one: the server answered the call itself (`server/src/components/headless.ts`).
- * The result is what survives, so a call that drew nothing is drawn as the refusal it was.
- */
- if (props.result?.startsWith(NOT_SHOWN)) {
- const lead = `${NOT_SHOWN}${spec.title}. `;
- const reason = (
- props.result.startsWith(lead)
- ? props.result.slice(lead.length)
- : props.result.slice(NOT_SHOWN.length)
- ).replace(NOT_SHOWN_TAIL, "");
- return <RefusedCard reason={reason} title={spec.title} />;
- }
- // Render from the polled grant snapshot so revocations show before a new call starts.
- if (!isHeld) {
- return (
- <RefusedCard
- reason={`${spec.title} is not available to this Bot at the moment. An administrator grants components per Bot, and can unpublish one for every Bot at once.`}
- title={spec.title}
- />
- );
- }
- return <Component {...(props.args ?? {})} />;
- },
- [Component, isHeld, refusals, spec.title],
- );
+ // Created ONCE: the SDK rebuilds a card whenever this identity changes. See `makeGalleryRender`.
+ const [render] = useState(() => makeGalleryRender(spec, store));
useFrontendTool({
name: spec.name,
@@ -149,7 +141,9 @@ function GrantedTool({
const reason = decision.reason ?? "That component is not allowed here.";
const id = context?.toolCall?.id;
if (id) {
- setRefusals((current) => new Map(current).set(id, reason));
+ store.set({
+ refusals: new Map(store.get().refusals).set(id, reason),
+ });
}
// Led with the same words the card shows, so the transcript and the card agree.
return `${NOT_SHOWN}${spec.title}. ${reason}${NOT_SHOWN_TAIL}`;
@@ -162,43 +156,208 @@ function GrantedTool({
return null;
}
+/**
+ * The card a gallery tool call draws, made once per component.
+ *
+ * ONCE, AND THAT IS THE POINT. The SDK hands this function to `ToolCallRenderer` as the component
+ * type, and remounts the card whenever it changes identity. It used to be a `useCallback` over the
+ * grants, so grants arriving (they start unknown on every channel) rebuilt every card: drawn as the
+ * refusal, then torn down and drawn again as the component. Now it reads the grants from the store
+ * and only re-renders. Exported for its tests.
+ */
+export function makeGalleryRender(spec: GalleryComponent, store: GrantStore) {
+ const Component = spec.Component;
+ return function GalleryRender(props: {
+ toolCallId?: string;
+ args?: Record<string, unknown>;
+ result?: string;
+ status?: string;
+ }) {
+ const snapshot = useSyncExternalStore(
+ store.subscribe,
+ store.get,
+ store.get,
+ );
+ const arriving = useContext(ArgumentsArrivingContext);
+ const refusal = props.toolCallId
+ ? snapshot.refusals.get(props.toolCallId)
+ : undefined;
+ if (refusal) {
+ return <RefusedCard reason={refusal} title={spec.title} />;
+ }
+ /*
+ * A stored refusal. The in-memory map above is gone once the page reloads, and a headless turn
+ * never had one: the server answered the call itself (`server/src/components/headless.ts`).
+ * The result is what survives, so a call that drew nothing is drawn as the refusal it was.
+ */
+ if (props.result?.startsWith(NOT_SHOWN)) {
+ const lead = `${NOT_SHOWN}${spec.title}. `;
+ const reason = (
+ props.result.startsWith(lead)
+ ? props.result.slice(lead.length)
+ : props.result.slice(NOT_SHOWN.length)
+ ).replace(NOT_SHOWN_TAIL, "");
+ return <RefusedCard reason={reason} title={spec.title} />;
+ }
+ // From the polled grants, so a revocation shows before a new call starts. Unknown draws.
+ const state = cardState(snapshot, spec.name, spec.title, props.toolCallId);
+ if (typeof state === "object") {
+ return <RefusedCard reason={state.refused} title={spec.title} />;
+ }
+ /*
+ * A number, link or colour still arriving is held back; see `settledArgs`. Only while the
+ * arguments are streaming (`inProgress`, not `executing`) in a row that can still receive them.
+ */
+ const complete = !(arriving && props.status === "inProgress");
+ return (
+ <GalleryStreamingContext.Provider value={!complete}>
+ <Component {...settledArgs(props.args ?? {}, complete)} />
+ </GalleryStreamingContext.Provider>
+ );
+ };
+}
+
function GrantedDecision({
spec,
held,
+ store,
}: {
spec: GalleryComponent;
held: Map<string, string>;
+ store: GrantStore;
}) {
+ useDecisionTool(spec, store, held);
+ return null;
+}
+
+type FrontendTool = Parameters<typeof useFrontendTool>[0];
+
+/**
+ * The removal the SDK's `useHumanInTheLoop` does on unmount, which `useDecisionTool` copies the rest
+ * of: without it a decision's renderer stayed registered after the gallery tools went away, drawing
+ * from a grant store nobody updated any more.
+ */
+export function useForgetRenderOnUnmount(
+ name: string,
+ core: { removeHookRenderToolCall(name: string, agentId?: string): void },
+) {
+ useLayoutEffect(
+ () => () => core.removeHookRenderToolCall(name),
+ [core, name],
+ );
+}
+
+/** `useFrontendTool`, and its renderer removed again on unmount, as `useHumanInTheLoop` does. */
+function useHumanInTheLoopTool(tool: FrontendTool) {
+ const { copilotkit } = useCopilotKit();
+ useFrontendTool(tool);
+ useForgetRenderOnUnmount(tool.name, copilotkit);
+}
+
+/**
+ * A decision tool: the run waits until the person answers on the card.
+ *
+ * REGISTERED THROUGH `useFrontendTool`, NOT `useHumanInTheLoop`, AND THAT IS THE FIX. The SDK's
+ * human-in-the-loop hook wraps the render in a component of its own that is rebuilt whenever the
+ * tool's description changes (1.83.0: a `useCallback` over `tool.description`). Ours changes from
+ * the built-in words to the published ones exactly when the grants load, so a decision on screen was
+ * torn down at that moment, and again on a revoke. This is that hook's answer-and-wait handler, kept
+ * as it is, with our render created once.
+ *
+ * `register` is the SDK hook (with its unmount cleanup) in the app and a recorder in the tests. Exported for its tests.
+ */
+export function useDecisionTool(
+ spec: GalleryComponent,
+ store: GrantStore,
+ held: Map<string, string>,
+ register: (tool: FrontendTool) => void = useHumanInTheLoopTool,
+) {
const description = held.get(spec.name);
const isHeld = description !== undefined;
- const Component = spec.Component;
+ const resolveRef = useRef<((result: unknown) => void) | null>(null);
+ const stopListeningRef = useRef<(() => void) | null>(null);
- /** Stable component type so in-progress decision cards do not remount. */
- const Render = useMemo(
- () =>
- function DecisionRender(props: Record<string, unknown>) {
- if (isHeld) return <Component {...props} />;
- return (
- <RefusedDecision
- respond={
- props.respond as ((result: unknown) => Promise<void>) | undefined
- }
- title={spec.title}
- />
- );
- },
- [Component, isHeld, spec.title],
+ const respond = useCallback(async (result: unknown) => {
+ if (!resolveRef.current) return;
+ stopListeningRef.current?.();
+ stopListeningRef.current = null;
+ resolveRef.current(result);
+ resolveRef.current = null;
+ }, []);
+
+ const handler = useCallback(
+ async (_args: unknown, context?: { signal?: AbortSignal }) =>
+ new Promise<unknown>((resolve, reject) => {
+ const signal = context?.signal;
+ if (signal?.aborted) {
+ reject(new Error("Human-in-the-loop interaction aborted"));
+ return;
+ }
+ resolveRef.current = resolve;
+ if (signal) {
+ const onAbort = () => {
+ stopListeningRef.current = null;
+ resolveRef.current = null;
+ reject(new Error("Human-in-the-loop interaction aborted"));
+ };
+ signal.addEventListener("abort", onAbort, { once: true });
+ stopListeningRef.current = () =>
+ signal.removeEventListener("abort", onAbort);
+ }
+ }),
+ [],
);
- useHumanInTheLoop({
+ // Created once, for the same reason as `makeGalleryRender`.
+ const [Render] = useState(() => makeDecisionRender(spec, store, respond));
+
+ register({
name: spec.name,
description: description ?? spec.description,
parameters: spec.parameters,
available: isHeld,
+ type: "human-in-the-loop",
+ handler,
render: Render,
- });
+ } as FrontendTool);
+}
- return null;
+/**
+ * The card a decision draws, made once per component.
+ *
+ * It can answer only while the call is executing, as the SDK's own decisions do. While the grants
+ * are unknown it draws without `respond`, which the decision components read as "not yet": the
+ * person sees what is being asked and cannot answer until the Bot is known to be allowed to ask.
+ * Then the same card enables in place. Exported for its tests.
+ */
+export function makeDecisionRender(
+ spec: GalleryComponent,
+ store: GrantStore,
+ respond: (result: unknown) => Promise<void>,
+) {
+ const Component = spec.Component;
+ return function DecisionRender(props: Record<string, unknown>) {
+ const snapshot = useSyncExternalStore(
+ store.subscribe,
+ store.get,
+ store.get,
+ );
+ const answer = props.status === "executing" ? respond : undefined;
+ const state = cardState(snapshot, spec.name, spec.title);
+ if (state === "draw") return <Component {...props} respond={answer} />;
+ if (state === "wait-for-grant") {
+ return <Component {...props} respond={undefined} />;
+ }
+ return (
+ <RefusedDecision
+ {...(snapshot.grants.status === "failed"
+ ? { reason: COULDNT_CHECK(spec.title) }
+ : {})}
+ respond={answer}
+ title={spec.title}
+ />
+ );
+ };
}
/**
@@ -209,12 +368,12 @@ function GrantedDecision({
function RefusedDecision({
title,
respond,
+ reason = `${title} is not available to this Bot at the moment, so the person was not asked. An administrator grants components per Bot, and can unpublish one for every Bot at once.`,
}: {
title: string;
respond?: (result: unknown) => Promise<void>;
+ reason?: string;
}) {
- const reason = `${title} is not available to this Bot at the moment, so the person was not asked. An administrator grants components per Bot, and can unpublish one for every Bot at once.`;
-
useEffect(() => {
if (!respond) return;
void respond(reason).catch(() => {
diff --git a/app/src/lib/copilot/grant-store.ts b/app/src/lib/copilot/grant-store.ts
new file mode 100644
index 00000000..3db33889
--- /dev/null
+++ b/app/src/lib/copilot/grant-store.ts
@@ -0,0 +1,114 @@
+import type { GrantedComponent } from "@/lib/components/queries";
+
+/**
+ * What a gallery card knows about whether its Bot may show it.
+ *
+ * THREE STATES, NOT TWO. Grants are fetched per Bot, and until the surface has declared its Bot and
+ * the answer has come back nobody knows. Reading that as "not held" drew the refusal first and the
+ * component a moment later, flashing "not available" at somebody who was allowed to see it. So
+ * unknown is its own state, and a card in it draws as it would if held. Only an answer, or a load
+ * that failed outright, decides otherwise.
+ */
+export type Grants =
+ | { status: "unknown" }
+ | { status: "known"; held: ReadonlyMap<string, string> }
+ | { status: "failed" };
+
+export type GrantSnapshot = {
+ grants: Grants;
+ /** Refusals the server decided at call time, keyed by the call they refused. */
+ refusals: ReadonlyMap<string, string>;
+};
+
+/**
+ * Grants from the polled query.
+ *
+ * Known whenever there is data, even if the latest poll failed: a blip in a five-second poll is not
+ * a reason to take back what was already known. Failed only when nothing ever arrived.
+ */
+export function grantsFrom(query: {
+ data?: readonly GrantedComponent[];
+ isError: boolean;
+ enabled: boolean;
+}): Grants {
+ if (query.data !== undefined) {
+ return {
+ status: "known",
+ held: new Map(
+ query.data.map((component) => [component.name, component.description]),
+ ),
+ };
+ }
+ if (query.enabled && query.isError) return { status: "failed" };
+ return { status: "unknown" };
+}
+
+export const NOT_AVAILABLE = (title: string) =>
+ `${title} is not available to this Bot at the moment. An administrator grants components per Bot, and can unpublish one for every Bot at once.`;
+
+export const COULDNT_CHECK = (title: string) =>
+ `Couldn't check whether this Bot may show ${title}. Try again in a moment.`;
+
+export type CardState = "draw" | "wait-for-grant" | { refused: string };
+
+/** What one card draws, given what is known about its grant and its own call. */
+export function cardState(
+ snapshot: GrantSnapshot,
+ name: string,
+ title: string,
+ toolCallId?: string,
+): CardState {
+ const refusal = toolCallId ? snapshot.refusals.get(toolCallId) : undefined;
+ if (refusal !== undefined) return { refused: refusal };
+ const { grants } = snapshot;
+ if (grants.status === "failed") return { refused: COULDNT_CHECK(title) };
+ if (grants.status === "unknown") return "wait-for-grant";
+ return grants.held.has(name) ? "draw" : { refused: NOT_AVAILABLE(title) };
+}
+
+function sameGrants(a: Grants, b: Grants): boolean {
+ if (a.status !== b.status) return false;
+ if (a.status !== "known" || b.status !== "known") return true;
+ if (a.held.size !== b.held.size) return false;
+ for (const [name, description] of a.held) {
+ if (b.held.get(name) !== description) return false;
+ }
+ return true;
+}
+
+/**
+ * The grants and refusals every gallery card reads, outside React state on purpose.
+ *
+ * The SDK remounts a card whenever the render function it was registered with changes identity, so
+ * that function is created once and cannot close over grants that change. It subscribes here with
+ * `useSyncExternalStore` instead, and a change re-renders the card rather than rebuilding it.
+ */
+export function createGrantStore() {
+ let snapshot: GrantSnapshot = {
+ grants: { status: "unknown" },
+ refusals: new Map(),
+ };
+ const listeners = new Set<() => void>();
+
+ return {
+ get: (): GrantSnapshot => snapshot,
+ set(next: Partial<GrantSnapshot>) {
+ const grants =
+ next.grants && !sameGrants(next.grants, snapshot.grants)
+ ? next.grants
+ : snapshot.grants;
+ const refusals = next.refusals ?? snapshot.refusals;
+ if (grants === snapshot.grants && refusals === snapshot.refusals) return;
+ snapshot = { grants, refusals };
+ for (const listener of listeners) listener();
+ },
+ subscribe(listener: () => void) {
+ listeners.add(listener);
+ return () => {
+ listeners.delete(listener);
+ };
+ },
+ };
+}
+
+export type GrantStore = ReturnType<typeof createGrantStore>;
diff --git a/app/src/lib/copilot/settled-args.ts b/app/src/lib/copilot/settled-args.ts
new file mode 100644
index 00000000..4ee98943
--- /dev/null
+++ b/app/src/lib/copilot/settled-args.ts
@@ -0,0 +1,76 @@
+/**
+ * The arguments of a streaming tool call with a half-arrived value held back.
+ *
+ * Partial JSON only ever stops at its end, so of everything drawn while a call streams only the last
+ * value can be incomplete. A half-typed label reads fine and is kept, so text still appears as it is
+ * written. A half-typed number is a different number (12 on its way to 125: the bar jumps), and a
+ * half-typed link or colour is a broken one, so those are left out until something follows them or
+ * the call completes. Everything else is shared with the input, not copied.
+ */
+export function settledArgs(
+ args: Record<string, unknown>,
+ complete: boolean,
+): Record<string, unknown> {
+ if (complete) return args;
+ const path = lastLeaf(args);
+ if (path === null) return args;
+ const key = path.at(-1);
+ const leaf = valueAt(args, path);
+ if (key === undefined || !isUnsettled(String(key), leaf)) return args;
+ return without(args, path) as Record<string, unknown>;
+}
+
+type Path = (string | number)[];
+
+function isContainer(value: unknown): value is object {
+ return typeof value === "object" && value !== null;
+}
+
+/** The path to the last scalar, walking the last key or element at every level. */
+function lastLeaf(value: unknown): Path | null {
+ if (!isContainer(value)) return [];
+ const entries = Array.isArray(value)
+ ? value.map((item, index) => [index, item] as const)
+ : Object.entries(value);
+ const last = entries.at(-1);
+ if (last === undefined) return null;
+ const rest = lastLeaf(last[1]);
+ return rest === null ? null : [last[0], ...rest];
+}
+
+function valueAt(value: unknown, path: Path): unknown {
+ return path.reduce<unknown>(
+ (current, key) =>
+ isContainer(current)
+ ? (current as Record<string | number, unknown>)[key]
+ : undefined,
+ value,
+ );
+}
+
+const UNSETTLED_KEY = /(url|href|src|colou?r)$/i;
+
+function isUnsettled(key: string, leaf: unknown): boolean {
+ if (typeof leaf === "number") return true;
+ if (typeof leaf !== "string") return false;
+ return (
+ UNSETTLED_KEY.test(key) || leaf.startsWith("#") || leaf.startsWith("http")
+ );
+}
+
+function without(value: unknown, path: Path): unknown {
+ const [key, ...rest] = path;
+ if (key === undefined || !isContainer(value)) return value;
+ if (Array.isArray(value)) {
+ const copy = [...value];
+ if (rest.length === 0) copy.splice(Number(key), 1);
+ else copy[Number(key)] = without(copy[Number(key)], rest);
+ return copy;
+ }
+ const record = value as Record<string, unknown>;
+ if (rest.length === 0) {
+ const { [String(key)]: _dropped, ...kept } = record;
+ return kept;
+ }
+ return { ...record, [key]: without(record[String(key)], rest) };
+}
diff --git a/app/src/lib/voice/archive.ts b/app/src/lib/voice/archive.ts
index 0d845eb7..96ddbfa0 100644
--- a/app/src/lib/voice/archive.ts
+++ b/app/src/lib/voice/archive.ts
@@ -29,6 +29,11 @@ const keys = {
export function voiceSessionQueryOptions(channelId: string) {
return queryOptions({
queryKey: keys.saved(channelId),
+ /*
+ * A channel's history waits on this (see `historyIsLoading`), so a failure is final at once:
+ * retried, it held the conversation behind the placeholder for another second.
+ */
+ retry: false,
queryFn: async ({ signal }): Promise<VoiceSessionRecord[]> => {
const sessions: VoiceSessionRecord[] = [];
let cursor: string | null = null;
@@ -165,6 +170,12 @@ export function useVoiceArchive(channelId: string) {
a.startedAt.localeCompare(b.startedAt) || a.id.localeCompare(b.id),
),
error: saved.error,
+ /**
+ * The saved calls have not come back yet. A channel waits on this before showing its history,
+ * so a call card is never spliced into a conversation already on screen. False after a failed
+ * load too: the conversation is readable without its calls, and `error` says what went wrong.
+ */
+ pending: saved.isPending,
};
}
@@ -192,6 +203,27 @@ export function cachedVoiceArchive(channelId: string): VoiceChatEntry[] {
);
}
+/*
+ * One card message per call, kept for as long as the call object is: the transcript skips redrawing
+ * a card whose message is the one it drew last time, and a fresh object on every render redrew every
+ * voice-chat card on every token of a reply streaming below it.
+ */
+const cardMessages = new WeakMap<VoiceChatEntry, ActivityMessage>();
+
+function cardMessageOf(call: VoiceChatEntry): ActivityMessage {
+ let message = cardMessages.get(call);
+ if (message === undefined) {
+ message = {
+ id: `voice-chat:${call.id}`,
+ role: "activity",
+ activityType: VOICE_CHAT_ACTIVITY,
+ content: { call },
+ };
+ cardMessages.set(call, message);
+ }
+ return message;
+}
+
/** Card position is anchored to the message preceding the call, ahead of its delegated work. */
export function withVoiceChats(
messages: readonly Message[],
@@ -201,12 +233,7 @@ export function withVoiceChats(
const groups = new Map<string | null, ActivityMessage[]>();
const ids = new Set(messages.map((message) => message.id));
for (const call of calls) {
- const message: ActivityMessage = {
- id: `voice-chat:${call.id}`,
- role: "activity",
- activityType: VOICE_CHAT_ACTIVITY,
- content: { call },
- };
+ const message = cardMessageOf(call);
if (ids.has(message.id)) continue;
const group = groups.get(call.anchorMessageId) ?? [];
group.push(message);
diff --git a/app/src/styles.css b/app/src/styles.css
index 8adf9c0b..46f20924 100644
--- a/app/src/styles.css
+++ b/app/src/styles.css
@@ -120,3 +120,35 @@
margin-top: 0;
}
}
+
+/*
+ * A conversation's newest rows rendering in as it opens. The delay is set per row as
+ * `--arrive-delay`; see
+ * `openingStagger` in chat-transcript.tsx. Opacity and transform only, so nothing the scroller
+ * measured moves.
+ */
+.history-arrive {
+ animation: history-arrive 240ms cubic-bezier(0.23, 1, 0.32, 1) both;
+ animation-delay: var(--arrive-delay, 0ms);
+}
+
+@keyframes history-arrive {
+ from {
+ opacity: 0;
+ transform: translateY(6px);
+ }
+}
+
+/* Reduced motion keeps the fade and drops the movement and the queue: gentler, not absent. */
+@media (prefers-reduced-motion: reduce) {
+ .history-arrive {
+ animation-name: history-arrive-fade;
+ animation-delay: 0ms;
+ }
+}
+
+@keyframes history-arrive-fade {
+ from {
+ opacity: 0;
+ }
+}
diff --git a/app/tests/browser-activity.test.ts b/app/tests/browser-activity.test.ts
index 73c38e7e..0475e547 100644
--- a/app/tests/browser-activity.test.ts
+++ b/app/tests/browser-activity.test.ts
@@ -28,13 +28,13 @@ test("navigation and intervening browser actions become one stable row as result
const first = step("one");
const items = [first, step("read", "computer_read"), step("two")];
const grouped = groupToolSteps(items, drawn);
- expect(grouped).toEqual([{ kind: "tools", id: "one", steps: items }]);
+ expect(grouped).toEqual([{ kind: "tools", id: "group:one", steps: items }]);
expect(
groupToolSteps(
[{ ...first, result: '{"ok":true}' }, ...items.slice(1)],
drawn,
)[0]?.id,
- ).toBe("one");
+ ).toBe("group:one");
expect(items).toHaveLength(3);
});
@@ -53,7 +53,11 @@ test("grouping keeps messages, other tools, and human assistance requests in the
];
for (const boundary of boundaries) {
const grouped = groupToolSteps([step("one"), boundary, step("two")], drawn);
- expect(grouped.map((item) => item.id)).toEqual(["one", boundary.id, "two"]);
+ expect(grouped.map((item) => item.id)).toEqual([
+ "group:one",
+ boundary.id,
+ "group:two",
+ ]);
expect(grouped[1]).toBe(boundary);
}
});
diff --git a/app/tests/decision-registration.test.tsx b/app/tests/decision-registration.test.tsx
new file mode 100644
index 00000000..ae8841e9
--- /dev/null
+++ b/app/tests/decision-registration.test.tsx
@@ -0,0 +1,146 @@
+import { afterAll, afterEach, beforeAll, expect, test } from "bun:test";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { act, cleanup, render, renderHook } from "@testing-library/react";
+import type { GalleryComponent } from "@/lib/copilot/gallery-registry";
+import {
+ useDecisionTool,
+ useForgetRenderOnUnmount,
+} from "@/lib/copilot/gallery-tools";
+import { createGrantStore } from "@/lib/copilot/grant-store";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * A decision is registered with ONE render for its whole life. The SDK's human-in-the-loop hook
+ * wraps the render in a component of its own that is rebuilt whenever the tool's description
+ * changes, and the description changes from the built-in words to the published ones exactly when
+ * the grants load, so the card on screen was torn down then. The decision registers through
+ * `useFrontendTool` itself, with the same answer-and-wait handler the SDK hook has.
+ */
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+});
+
+afterEach(() => {
+ cleanup();
+ answer = undefined;
+});
+
+afterAll(async () => {
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+type Registered = {
+ name: string;
+ description: string;
+ available: boolean;
+ type?: string;
+ handler: (
+ args: unknown,
+ context?: { signal?: AbortSignal },
+ ) => Promise<unknown>;
+ render: (props: Record<string, unknown>) => React.ReactNode;
+};
+
+let answer: ((result: unknown) => Promise<void>) | undefined;
+
+function Decision(props: { respond?: (result: unknown) => Promise<void> }) {
+ answer = props.respond;
+ return <p>decision</p>;
+}
+
+const spec = {
+ name: "askApproval",
+ title: "Approval",
+ kind: "decision",
+ description: "Built-in words.",
+ parameters: {},
+ Component: Decision,
+} as unknown as GalleryComponent;
+
+test("keeps one render while the description changes as grants load", () => {
+ const registered: Registered[] = [];
+ const store = createGrantStore();
+ const { rerender } = renderHook(
+ ({ held }: { held: Map<string, string> }) =>
+ useDecisionTool(spec, store, held, (tool) => {
+ registered.push(tool as Registered);
+ }),
+ { initialProps: { held: new Map<string, string>() } },
+ );
+
+ rerender({ held: new Map([["askApproval", "Published words."]]) });
+
+ const first = registered[0];
+ const last = registered.at(-1);
+ expect(first?.description).toBe("Built-in words.");
+ expect(last?.description).toBe("Published words.");
+ expect(last?.available).toBe(true);
+ expect(last?.type).toBe("human-in-the-loop");
+ expect(registered.every((tool) => tool.render === first?.render)).toBe(true);
+});
+
+test("the handler waits for the person's answer from the card", async () => {
+ const registered: Registered[] = [];
+ const store = createGrantStore();
+ store.set({
+ grants: { status: "known", held: new Map([["askApproval", "d"]]) },
+ });
+ renderHook(() =>
+ useDecisionTool(spec, store, new Map([["askApproval", "d"]]), (tool) => {
+ registered.push(tool as Registered);
+ }),
+ );
+ const tool = registered.at(-1) as Registered;
+ const Render = tool.render as (
+ props: Record<string, unknown>,
+ ) => React.ReactNode;
+
+ const waiting = tool.handler({});
+ render(<Render args={{}} status="executing" />);
+ await act(async () => {
+ await answer?.("approved");
+ });
+
+ expect(await waiting).toBe("approved");
+});
+
+test("the card cannot answer before the call is executing", () => {
+ const registered: Registered[] = [];
+ const store = createGrantStore();
+ store.set({
+ grants: { status: "known", held: new Map([["askApproval", "d"]]) },
+ });
+ renderHook(() =>
+ useDecisionTool(spec, store, new Map([["askApproval", "d"]]), (tool) => {
+ registered.push(tool as Registered);
+ }),
+ );
+ const Render = (registered.at(-1) as Registered).render as (
+ props: Record<string, unknown>,
+ ) => React.ReactNode;
+
+ render(<Render args={{}} status="inProgress" />);
+
+ expect(answer).toBeUndefined();
+});
+
+/*
+ * The SDK's own human-in-the-loop hook removes its renderer when it unmounts; the copy here did not,
+ * so a decision kept drawing from a grant store nobody updated after the gallery tools went away.
+ */
+test("a decision's renderer is removed when it unmounts", () => {
+ const removed: string[] = [];
+ const core = {
+ removeHookRenderToolCall: (name: string) => {
+ removed.push(name);
+ },
+ };
+ const view = renderHook(() => useForgetRenderOnUnmount("askApproval", core));
+ expect(removed).toEqual([]);
+
+ view.unmount();
+
+ expect(removed).toEqual(["askApproval"]);
+});
diff --git a/app/tests/follow-intent.test.ts b/app/tests/follow-intent.test.ts
new file mode 100644
index 00000000..e59598bc
--- /dev/null
+++ b/app/tests/follow-intent.test.ts
@@ -0,0 +1,165 @@
+import { expect, test } from "bun:test";
+import {
+ FOLLOWING,
+ type FollowState,
+ nextFollow,
+} from "@/components/channels/follow-intent";
+
+/**
+ * Whether the view follows a streaming reply is decided by what the person does, never by where the
+ * view happens to be after a layout change. Moving up the page stops following at once; coming back
+ * down near the end, pressing the button or sending picks it up again.
+ */
+
+const PAUSED: FollowState = { following: false, pausedBy: "scroll" };
+const SELECTING: FollowState = { following: false, pausedBy: "selection" };
+
+function scroll(
+ top: number,
+ previousTop: number,
+ fromEnd = 400,
+ pointerDown = false,
+) {
+ return { type: "scroll" as const, top, previousTop, fromEnd, pointerDown };
+}
+
+test("an upward wheel stops following", () => {
+ expect(nextFollow(FOLLOWING, { type: "wheel", deltaY: -40 })).toEqual({
+ state: PAUSED,
+ scrollToEnd: null,
+ });
+});
+
+test("a downward wheel keeps following", () => {
+ expect(nextFollow(FOLLOWING, { type: "wheel", deltaY: 40 }).state).toBe(
+ FOLLOWING,
+ );
+});
+
+test("scroll keys stop following", () => {
+ for (const key of ["PageUp", "ArrowUp", "Home"]) {
+ expect(
+ nextFollow(FOLLOWING, { type: "key", key, shiftKey: false }).state,
+ ).toEqual(PAUSED);
+ }
+ expect(
+ nextFollow(FOLLOWING, { type: "key", key: " ", shiftKey: true }).state,
+ ).toEqual(PAUSED);
+ expect(
+ nextFollow(FOLLOWING, { type: "key", key: " ", shiftKey: false }).state,
+ ).toBe(FOLLOWING);
+ expect(
+ nextFollow(FOLLOWING, { type: "key", key: "ArrowDown", shiftKey: false })
+ .state,
+ ).toBe(FOLLOWING);
+});
+
+test("a touch drag up the page stops following", () => {
+ expect(
+ nextFollow(FOLLOWING, { type: "touch", fingerDeltaY: 12 }).state,
+ ).toEqual(PAUSED);
+ expect(
+ nextFollow(FOLLOWING, { type: "touch", fingerDeltaY: -12 }).state,
+ ).toBe(FOLLOWING);
+});
+
+test("a scrollbar drag up stops following", () => {
+ expect(nextFollow(FOLLOWING, scroll(400, 500, 400, true)).state).toEqual(
+ PAUSED,
+ );
+});
+
+test("a layout correction is not the person scrolling", () => {
+ expect(nextFollow(FOLLOWING, scroll(400, 500, 0, false)).state).toBe(
+ FOLLOWING,
+ );
+});
+
+test("scrolling back down to within 80px resumes", () => {
+ expect(nextFollow(PAUSED, scroll(900, 850, 60))).toEqual({
+ state: FOLLOWING,
+ scrollToEnd: "auto",
+ });
+ expect(nextFollow(PAUSED, scroll(900, 850, 81)).state).toBe(PAUSED);
+});
+
+test("an upward move ending near the end does not resume", () => {
+ expect(nextFollow(PAUSED, scroll(850, 900, 60)).state).toBe(PAUSED);
+});
+
+test("selecting text pauses and clearing it resumes", () => {
+ const paused = nextFollow(FOLLOWING, { type: "selection", active: true });
+ expect(paused).toEqual({ state: SELECTING, scrollToEnd: null });
+ expect(
+ nextFollow(paused.state, { type: "selection", active: false }),
+ ).toEqual({ state: FOLLOWING, scrollToEnd: "auto" });
+});
+
+test("scrolling away while selecting is a scroll pause", () => {
+ expect(nextFollow(SELECTING, { type: "wheel", deltaY: -40 }).state).toEqual(
+ PAUSED,
+ );
+});
+
+test("clearing a selection does not resume a scroll pause", () => {
+ expect(nextFollow(PAUSED, { type: "selection", active: false }).state).toBe(
+ PAUSED,
+ );
+ expect(nextFollow(PAUSED, { type: "selection", active: true }).state).toBe(
+ PAUSED,
+ );
+});
+
+test("the button resumes smoothly", () => {
+ expect(nextFollow(PAUSED, { type: "button" })).toEqual({
+ state: FOLLOWING,
+ scrollToEnd: "smooth",
+ });
+});
+
+test("a send resumes without scrolling", () => {
+ expect(nextFollow(PAUSED, { type: "send" })).toEqual({
+ state: FOLLOWING,
+ scrollToEnd: null,
+ });
+});
+
+test("a queued message resumes at the end", () => {
+ expect(nextFollow(PAUSED, { type: "queued" })).toEqual({
+ state: FOLLOWING,
+ scrollToEnd: "auto",
+ });
+});
+
+/* Jumping to a turn from the rail is the person moving through the conversation, like scrolling up. */
+test("a jump from the rail stops following, and coming back to the end resumes it", () => {
+ const jumped = nextFollow(FOLLOWING, { type: "jump" });
+ expect(jumped).toEqual({ state: PAUSED, scrollToEnd: null });
+ expect(nextFollow(jumped.state, scroll(900, 800, 40)).state).toEqual(
+ FOLLOWING,
+ );
+});
+
+/*
+ * The scroller drops out of following the bottom on ANY wheel, touch or scroll key, downward ones
+ * included, and only comes back on its own when a scroll lands at the end. At the end already,
+ * a downward flick scrolls nothing, so it stayed out while this said following and the reply ran
+ * off the bottom. A scroll to the end puts it back.
+ */
+test("downward input at the end while following asks for the end again", () => {
+ expect(nextFollow(FOLLOWING, { type: "down", atEnd: true })).toEqual({
+ state: FOLLOWING,
+ scrollToEnd: "auto",
+ });
+});
+
+test("downward input above the end, or while paused, asks for nothing", () => {
+ expect(nextFollow(FOLLOWING, { type: "down", atEnd: false })).toEqual({
+ state: FOLLOWING,
+ scrollToEnd: null,
+ });
+ expect(nextFollow(PAUSED, { type: "down", atEnd: true })).toEqual({
+ state: PAUSED,
+ scrollToEnd: null,
+ });
+});
diff --git a/app/tests/gallery-render.test.tsx b/app/tests/gallery-render.test.tsx
new file mode 100644
index 00000000..ebb41486
--- /dev/null
+++ b/app/tests/gallery-render.test.tsx
@@ -0,0 +1,237 @@
+import { afterAll, afterEach, beforeAll, expect, test } from "bun:test";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { act, cleanup, render } from "@testing-library/react";
+import { useEffect } from "react";
+import {
+ makeDecisionRender,
+ makeGalleryRender,
+} from "@/lib/copilot/gallery-tools";
+import { createGrantStore } from "@/lib/copilot/grant-store";
+import { ArgumentsArrivingContext } from "@/components/gallery/streaming";
+import { DataTable } from "@/components/gallery/table";
+import type { GalleryComponent } from "@/lib/copilot/gallery-registry";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * A card a Bot draws is created ONCE and grows in place. The SDK remounts a card whenever the render
+ * function it was registered with changes identity, so the render is made once per component and
+ * reads the grants from a store: grants arriving or changing re-render the card instead of tearing
+ * it down. Mounts are counted with an effect that runs once per mount.
+ */
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+afterAll(async () => {
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+let mounts = 0;
+let lastRespond: unknown = "unset";
+
+function Counted(props: { title?: string }) {
+ useEffect(() => {
+ mounts += 1;
+ }, []);
+ return <p>{props.title ?? "untitled"}</p>;
+}
+
+function CountedDecision(props: {
+ args?: { title?: string };
+ respond?: unknown;
+}) {
+ useEffect(() => {
+ mounts += 1;
+ }, []);
+ lastRespond = props.respond;
+ return <p>{props.args?.title ?? "untitled"}</p>;
+}
+
+const spec = (Component: GalleryComponent["Component"]) =>
+ ({
+ name: "chart",
+ title: "Bar chart",
+ kind: "chart",
+ description: "A chart.",
+ parameters: {},
+ Component,
+ }) as unknown as GalleryComponent;
+
+const heldGrants = {
+ status: "known" as const,
+ held: new Map([["chart", "A chart."]]),
+};
+
+afterEach(() => {
+ mounts = 0;
+ lastRespond = "unset";
+});
+
+test("waits without refusing while grants are unknown", () => {
+ const Render = makeGalleryRender(spec(Counted), createGrantStore());
+ const view = render(
+ <Render args={{ title: "Revenue" }} status="inProgress" toolCallId="c1" />,
+ );
+
+ expect(view.getByText("Revenue")).toBeTruthy();
+ expect(view.queryByText(/not available/)).toBeNull();
+});
+
+test("mounts once while grants load and args stream", () => {
+ const store = createGrantStore();
+ const Render = makeGalleryRender(spec(Counted), store);
+ const view = render(
+ <Render args={{ title: "Re" }} status="inProgress" toolCallId="c1" />,
+ );
+
+ act(() => store.set({ grants: heldGrants }));
+ view.rerender(
+ <Render args={{ title: "Revenue" }} status="complete" toolCallId="c1" />,
+ );
+
+ expect(view.getByText("Revenue")).toBeTruthy();
+ expect(mounts).toBe(1);
+});
+
+test("refuses once grants say not held", () => {
+ const store = createGrantStore();
+ store.set({ grants: { status: "known", held: new Map() } });
+ const Render = makeGalleryRender(spec(Counted), store);
+ const view = render(
+ <Render args={{ title: "Revenue" }} status="complete" toolCallId="c1" />,
+ );
+
+ expect(view.getByText(/not available to this Bot/)).toBeTruthy();
+});
+
+test("refuses with the couldn't-check reason when grants failed", () => {
+ const store = createGrantStore();
+ store.set({ grants: { status: "failed" } });
+ const Render = makeGalleryRender(spec(Counted), store);
+ const view = render(
+ <Render args={{ title: "Revenue" }} status="complete" toolCallId="c1" />,
+ );
+
+ expect(
+ view.getByText(/Couldn't check whether this Bot may show Bar chart/),
+ ).toBeTruthy();
+});
+
+test("an earlier call keeps drawing after a revoke while a new call is refused", () => {
+ const store = createGrantStore();
+ store.set({
+ grants: heldGrants,
+ refusals: new Map([["call-2", "That component was just switched off."]]),
+ });
+ const Render = makeGalleryRender(spec(Counted), store);
+ const view = render(
+ <>
+ <Render
+ args={{ title: "Earlier" }}
+ status="complete"
+ toolCallId="call-1"
+ />
+ <Render args={{ title: "Later" }} status="complete" toolCallId="call-2" />
+ </>,
+ );
+
+ expect(view.getByText("Earlier")).toBeTruthy();
+ expect(view.queryByText("Later")).toBeNull();
+ expect(view.getByText(/just switched off/)).toBeTruthy();
+});
+
+test("a decision waits disabled, then enables in place", () => {
+ const store = createGrantStore();
+ const respond = async () => {};
+ const Render = makeDecisionRender(spec(CountedDecision), store, respond);
+ const view = render(
+ <Render args={{ title: "Approve" }} respond={respond} status="executing" />,
+ );
+
+ expect(lastRespond).toBeUndefined();
+ act(() => store.set({ grants: heldGrants }));
+ view.rerender(
+ <Render args={{ title: "Approve" }} respond={respond} status="executing" />,
+ );
+
+ expect(lastRespond).toBe(respond);
+ expect(mounts).toBe(1);
+});
+
+function ShowsValue(props: { title?: string; value?: number }) {
+ return (
+ <p>
+ {props.title}: {props.value ?? "pending"}
+ </p>
+ );
+}
+
+test("a half-arrived number is held back until the call completes", () => {
+ const store = createGrantStore();
+ store.set({ grants: heldGrants });
+ const Render = makeGalleryRender(spec(ShowsValue), store);
+ const view = render(
+ <Render args={{ title: "Sales", value: 12 }} status="inProgress" />,
+ );
+ expect(view.getByText("Sales: pending")).toBeTruthy();
+
+ view.rerender(
+ <Render args={{ title: "Sales", value: 125 }} status="complete" />,
+ );
+ expect(view.getByText("Sales: 125")).toBeTruthy();
+});
+
+test("a streaming table draws its complete rows through the gallery render", () => {
+ const store = createGrantStore();
+ store.set({ grants: heldGrants });
+ const Render = makeGalleryRender(
+ spec(DataTable as GalleryComponent["Component"]),
+ store,
+ );
+ const view = render(
+ <Render
+ args={{
+ title: "Sales",
+ columns: ["Quarter", "Revenue"],
+ rows: [{ cells: ["Q1", 8] }, { cells: ["Q2", 9] }],
+ }}
+ status="inProgress"
+ />,
+ );
+
+ expect(view.queryByText(/Waiting for complete table data/)).toBeNull();
+ expect(view.getByText("Q1")).toBeTruthy();
+});
+
+/*
+ * `executing` is a call whose arguments are final and whose handler is still answering; a call with
+ * no result outside the running turn (a stopped run, a page closed mid-call, reloaded) stays
+ * `inProgress` for good. Neither is still arriving, so neither holds its last value back.
+ */
+test("a call whose arguments are final draws its last number", () => {
+ const store = createGrantStore();
+ store.set({ grants: heldGrants });
+ const Render = makeGalleryRender(spec(ShowsValue), store);
+ const view = render(
+ <Render args={{ title: "Sales", value: 125 }} status="executing" />,
+ );
+ expect(view.getByText("Sales: 125")).toBeTruthy();
+});
+
+test("a call left without a result outside the running turn draws its last number", () => {
+ const store = createGrantStore();
+ store.set({ grants: heldGrants });
+ const Render = makeGalleryRender(spec(ShowsValue), store);
+ const view = render(
+ <ArgumentsArrivingContext.Provider value={false}>
+ <Render args={{ title: "Sales", value: 125 }} status="inProgress" />
+ </ArgumentsArrivingContext.Provider>,
+ );
+ expect(view.getByText("Sales: 125")).toBeTruthy();
+});
diff --git a/app/tests/gallery-streaming.test.tsx b/app/tests/gallery-streaming.test.tsx
new file mode 100644
index 00000000..844467ee
--- /dev/null
+++ b/app/tests/gallery-streaming.test.tsx
@@ -0,0 +1,127 @@
+import { afterAll, afterEach, beforeAll, expect, spyOn, test } from "bun:test";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { cleanup, render } from "@testing-library/react";
+import { MetricsCard } from "@/components/gallery/cards";
+import { BarChartCard } from "@/components/gallery/charts";
+import { GalleryStreamingContext } from "@/components/gallery/streaming";
+import { DataTable } from "@/components/gallery/table";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * A gallery component is drawn from arguments that are still arriving. Its list items are keyed by
+ * position, never by a label that is still being typed: "Re", "Rev", "Revenue" were three keys, so
+ * an item was torn down and rebuilt on every chunk. And a number that has not arrived yet holds its
+ * place instead of drawing as NaN.
+ */
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+afterAll(async () => {
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+const bars = (container: HTMLElement) => [
+ ...container.querySelectorAll<HTMLElement>(".rounded-t-md"),
+];
+
+test("a bar keeps its node while its label streams", () => {
+ const view = render(<BarChartCard points={[{ label: "Re", value: 3 }]} />);
+ const before = bars(view.container)[0];
+
+ view.rerender(<BarChartCard points={[{ label: "Revenue", value: 3 }]} />);
+
+ expect(bars(view.container)[0]).toBe(before);
+});
+
+test("a bar without a value yet holds its place", () => {
+ const view = render(
+ <BarChartCard
+ points={[{ label: "A", value: 4 }, { label: "B" } as never]}
+ />,
+ );
+
+ const drawn = bars(view.container);
+ expect(drawn.length).toBe(2);
+ expect(drawn.some((bar) => /NaN/.test(bar.style.height))).toBe(false);
+ expect(drawn[1]?.style.height).toBe("2%");
+ expect(view.container.textContent).not.toContain("NaN");
+});
+
+test("duplicate labels both draw", () => {
+ const errors = spyOn(console, "error").mockImplementation(() => {});
+ const view = render(
+ <BarChartCard
+ points={[
+ { label: "Q1", value: 1 },
+ { label: "Q1", value: 2 },
+ ]}
+ />,
+ );
+
+ expect(bars(view.container).length).toBe(2);
+ expect(
+ errors.mock.calls.some((call) => String(call[0]).includes("same key")),
+ ).toBe(false);
+ errors.mockRestore();
+});
+
+test("a metric keeps its node while its label streams", () => {
+ const view = render(<MetricsCard metrics={[{ label: "Re", value: "3" }]} />);
+ const before = view.getByText("3");
+
+ view.rerender(<MetricsCard metrics={[{ label: "Revenue", value: "3" }]} />);
+
+ expect(view.getByText("3")).toBe(before);
+});
+
+test("a table cell keeps its node while its column name streams", () => {
+ const view = render(
+ <DataTable columns={["Re"]} rows={[{ cells: ["north"] }]} title="Sales" />,
+ );
+ const before = view.getByText("north").closest("td");
+
+ view.rerender(
+ <DataTable
+ columns={["Revenue"]}
+ rows={[{ cells: ["north"] }]}
+ title="Sales"
+ />,
+ );
+
+ expect(view.getByText("north").closest("td")).toBe(before);
+});
+
+test("a table draws its complete rows while the last one is still arriving", () => {
+ const view = render(
+ <GalleryStreamingContext.Provider value>
+ <DataTable
+ columns={["Quarter", "Revenue"]}
+ rows={[{ cells: ["Q1", 8] }, { cells: ["Q2"] }]}
+ title="Sales"
+ />
+ </GalleryStreamingContext.Provider>,
+ );
+
+ expect(view.queryByText(/Waiting for complete table data/)).toBeNull();
+ expect(view.getByText("Q1")).toBeTruthy();
+ expect(view.container.querySelectorAll("tbody tr").length).toBe(2);
+});
+
+test("a complete table with a short last row is still refused", () => {
+ const view = render(
+ <DataTable
+ columns={["Quarter", "Revenue"]}
+ rows={[{ cells: ["Q1", 8] }, { cells: ["Q2"] }]}
+ title="Sales"
+ />,
+ );
+
+ expect(view.getByText(/Waiting for complete table data/)).toBeTruthy();
+});
diff --git a/app/tests/grant-store.test.ts b/app/tests/grant-store.test.ts
new file mode 100644
index 00000000..f93d3a64
--- /dev/null
+++ b/app/tests/grant-store.test.ts
@@ -0,0 +1,125 @@
+import { expect, mock, test } from "bun:test";
+import {
+ cardState,
+ COULDNT_CHECK,
+ createGrantStore,
+ type GrantSnapshot,
+ grantsFrom,
+ NOT_AVAILABLE,
+} from "@/lib/copilot/grant-store";
+
+/**
+ * What a gallery card knows about whether its Bot may show it. "Not known yet" is not "refused":
+ * a card that drew the refusal while the grants were still on their way, and then the component,
+ * flashed "not available" at somebody who was allowed to see it.
+ */
+
+const held = (...names: string[]) =>
+ new Map(names.map((name) => [name, `${name} description`]));
+
+test("grants are unknown while there is no Bot to ask about", () => {
+ expect(grantsFrom({ isError: false, enabled: false })).toEqual({
+ status: "unknown",
+ });
+});
+
+test("grants are unknown while the first answer is on its way", () => {
+ expect(grantsFrom({ isError: false, enabled: true })).toEqual({
+ status: "unknown",
+ });
+});
+
+test("grants are known once they arrive", () => {
+ expect(
+ grantsFrom({
+ data: [{ name: "chart", description: "d" }],
+ isError: false,
+ enabled: true,
+ }),
+ ).toEqual({ status: "known", held: new Map([["chart", "d"]]) });
+});
+
+test("grants that could not be loaded at all have failed", () => {
+ expect(grantsFrom({ isError: true, enabled: true })).toEqual({
+ status: "failed",
+ });
+});
+
+test("a failed poll keeps the grants already known", () => {
+ expect(
+ grantsFrom({
+ data: [{ name: "chart", description: "d" }],
+ isError: true,
+ enabled: true,
+ }),
+ ).toEqual({ status: "known", held: new Map([["chart", "d"]]) });
+});
+
+function snapshot(overrides: Partial<GrantSnapshot> = {}): GrantSnapshot {
+ return {
+ grants: { status: "unknown" },
+ refusals: new Map(),
+ ...overrides,
+ };
+}
+
+test("a card waits, never refuses, while grants are unknown", () => {
+ expect(cardState(snapshot(), "chart", "Bar chart")).toBe("wait-for-grant");
+});
+
+test("a held component draws", () => {
+ expect(
+ cardState(
+ snapshot({ grants: { status: "known", held: held("chart") } }),
+ "chart",
+ "Bar chart",
+ ),
+ ).toBe("draw");
+});
+
+test("a component the Bot does not hold is refused", () => {
+ expect(
+ cardState(
+ snapshot({ grants: { status: "known", held: held() } }),
+ "chart",
+ "Bar chart",
+ ),
+ ).toEqual({ refused: NOT_AVAILABLE("Bar chart") });
+});
+
+test("grants that failed refuse with the couldn't-check reason", () => {
+ expect(
+ cardState(snapshot({ grants: { status: "failed" } }), "chart", "Bar chart"),
+ ).toEqual({ refused: COULDNT_CHECK("Bar chart") });
+ expect(COULDNT_CHECK("Bar chart")).toBe(
+ "Couldn't check whether this Bot may show Bar chart. Try again in a moment.",
+ );
+});
+
+test("a refusal for this call wins over a grant", () => {
+ expect(
+ cardState(
+ snapshot({
+ grants: { status: "known", held: held("chart") },
+ refusals: new Map([["call-2", "Not in this channel."]]),
+ }),
+ "chart",
+ "Bar chart",
+ "call-2",
+ ),
+ ).toEqual({ refused: "Not in this channel." });
+});
+
+test("the store tells its listeners about a change and not about a no-op", () => {
+ const store = createGrantStore();
+ const listener = mock(() => {});
+ store.subscribe(listener);
+
+ store.set({ grants: { status: "unknown" } });
+ expect(listener).toHaveBeenCalledTimes(0);
+
+ const before = store.get();
+ store.set({ grants: { status: "failed" } });
+ expect(listener).toHaveBeenCalledTimes(1);
+ expect(store.get()).not.toBe(before);
+});
diff --git a/app/tests/group-chat-scroll.test.ts b/app/tests/group-chat-scroll.test.ts
new file mode 100644
index 00000000..e3c24391
--- /dev/null
+++ b/app/tests/group-chat-scroll.test.ts
@@ -0,0 +1,61 @@
+import { expect, test } from "bun:test";
+import {
+ isNearBottom,
+ shouldFollowGroup,
+} from "@/components/channels/group-chat";
+
+/**
+ * A group chat follows new lines only for a reader who is already at the bottom. Somebody scrolled
+ * up to read an earlier answer keeps their place while the Bots go on talking below.
+ */
+
+test("80px from the bottom counts as at the bottom", () => {
+ expect(
+ isNearBottom({ scrollTop: 920, scrollHeight: 1000, clientHeight: 0 }),
+ ).toBe(true);
+});
+
+test("81px from the bottom does not", () => {
+ expect(
+ isNearBottom({ scrollTop: 919, scrollHeight: 1000, clientHeight: 0 }),
+ ).toBe(false);
+});
+
+test("a custom threshold is respected", () => {
+ expect(
+ isNearBottom(
+ { scrollTop: 700, scrollHeight: 1000, clientHeight: 100 },
+ 200,
+ ),
+ ).toBe(true);
+ expect(
+ isNearBottom(
+ { scrollTop: 699, scrollHeight: 1000, clientHeight: 100 },
+ 200,
+ ),
+ ).toBe(false);
+});
+
+test("the first landing always goes to the bottom", () => {
+ expect(
+ shouldFollowGroup({ landed: false, atBottom: false, newestIsMine: false }),
+ ).toBe(true);
+});
+
+test("a reader scrolled up keeps their place when a Bot speaks", () => {
+ expect(
+ shouldFollowGroup({ landed: true, atBottom: false, newestIsMine: false }),
+ ).toBe(false);
+});
+
+test("the person's own message is always brought into view", () => {
+ expect(
+ shouldFollowGroup({ landed: true, atBottom: false, newestIsMine: true }),
+ ).toBe(true);
+});
+
+test("a reader at the bottom follows", () => {
+ expect(
+ shouldFollowGroup({ landed: true, atBottom: true, newestIsMine: false }),
+ ).toBe(true);
+});
diff --git a/app/tests/history-loading.test.ts b/app/tests/history-loading.test.ts
new file mode 100644
index 00000000..670da319
--- /dev/null
+++ b/app/tests/history-loading.test.ts
@@ -0,0 +1,61 @@
+import { expect, test } from "bun:test";
+import {
+ historyIsLoading,
+ VOICE_WAIT_MS,
+} from "@/components/channels/channel-chat";
+import { voiceSessionQueryOptions } from "@/lib/voice/archive";
+
+/**
+ * When the transcript waits behind the placeholder. A channel opened from the roster waits for its
+ * whole history — the stored thread and its voice chats. A channel just started from the compose
+ * screen has no history to wait for: its first message is already in hand and must show at once,
+ * not after a voice-chat request it cannot have anything in.
+ */
+
+test("a restoring channel waits", () => {
+ expect(
+ historyIsLoading({ restoring: true, seeded: false, voicePending: false }),
+ ).toBe(true);
+});
+
+test("an opened channel waits for its voice chats", () => {
+ expect(
+ historyIsLoading({ restoring: false, seeded: false, voicePending: true }),
+ ).toBe(true);
+});
+
+test("a channel started from the compose screen does not wait for voice chats", () => {
+ expect(
+ historyIsLoading({ restoring: false, seeded: true, voicePending: true }),
+ ).toBe(false);
+});
+
+test("nothing left to wait for", () => {
+ expect(
+ historyIsLoading({ restoring: false, seeded: false, voicePending: false }),
+ ).toBe(false);
+});
+
+/*
+ * A slow or failing voice service must not hold up text chat: once the thread is in, the voice chats
+ * get VOICE_WAIT_MS more, and the conversation shows without them after that. A failure is final at
+ * once rather than retried behind the placeholder.
+ */
+test("a channel stops waiting for voice chats that take too long", () => {
+ expect(
+ historyIsLoading({
+ restoring: false,
+ seeded: false,
+ voicePending: true,
+ voiceWaitedOut: true,
+ }),
+ ).toBe(false);
+});
+
+test("a failed voice-chat load is not retried behind the placeholder", () => {
+ expect(voiceSessionQueryOptions("c1").retry).toBe(false);
+});
+
+test("the wait for voice chats is short", () => {
+ expect(VOICE_WAIT_MS).toBeLessThanOrEqual(1500);
+});
diff --git a/app/tests/late-renderers.test.tsx b/app/tests/late-renderers.test.tsx
new file mode 100644
index 00000000..1304592b
--- /dev/null
+++ b/app/tests/late-renderers.test.tsx
@@ -0,0 +1,124 @@
+import { afterAll, afterEach, beforeAll, expect, test } from "bun:test";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { act, cleanup, render, renderHook } from "@testing-library/react";
+import {
+ LateRenderersWatch,
+ useLateRenderers,
+} from "@/components/channels/late-renderers";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * The SDK swaps its list of activity renderers in an effect when generative UI turns on (the
+ * capabilities answer, or the runtime connecting) and tells nobody. An activity drawn before then
+ * found no renderer and stayed blank until its message happened to change. It now looks again a
+ * frame after either of those, and redraws when the list really did change.
+ */
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+afterAll(async () => {
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+function fakeCore() {
+ const listeners = new Set<() => void>();
+ return {
+ renderActivityMessages: [] as unknown[],
+ subscribe(subscriber: { onRuntimeConnectionStatusChanged?: () => void }) {
+ const listener = subscriber.onRuntimeConnectionStatusChanged;
+ if (listener) listeners.add(listener);
+ return { unsubscribe: () => listener && listeners.delete(listener) };
+ },
+ connect() {
+ for (const listener of listeners) listener();
+ },
+ listeners,
+ };
+}
+
+const nextFrame = () =>
+ act(() => new Promise((resolve) => window.requestAnimationFrame(resolve)));
+
+test("redraws once the renderers change after the runtime connects", async () => {
+ const core = fakeCore();
+ const { result } = renderHook(() => useLateRenderers(core, true, undefined));
+ await nextFrame();
+ const before = result.current;
+
+ core.renderActivityMessages = [{ activityType: "a2ui" }];
+ act(() => core.connect());
+ await nextFrame();
+
+ expect(result.current).toBe(before + 1);
+});
+
+test("redraws once the renderers change after the capabilities arrive", async () => {
+ const core = fakeCore();
+ const { result, rerender } = renderHook(
+ ({ settled }: { settled: unknown }) =>
+ useLateRenderers(core, true, settled),
+ { initialProps: { settled: undefined as unknown } },
+ );
+ await nextFrame();
+ const before = result.current;
+
+ core.renderActivityMessages = [{ activityType: "a2ui" }];
+ rerender({ settled: true });
+ await nextFrame();
+
+ expect(result.current).toBe(before + 1);
+});
+
+test("an activity that already has its renderer does not listen", () => {
+ const core = fakeCore();
+ renderHook(() => useLateRenderers(core, false, undefined));
+
+ expect(core.listeners.size).toBe(0);
+});
+
+/*
+ * The provider's swap can land a few frames after the connection is heard, under the load of a cold
+ * start. One look a frame later missed it, and nothing looked again.
+ */
+test("keeps looking for a few frames after the runtime connects", async () => {
+ const core = fakeCore();
+ const { result } = renderHook(() => useLateRenderers(core, true, undefined));
+ await nextFrame();
+ const before = result.current;
+
+ act(() => core.connect());
+ await nextFrame();
+ await nextFrame();
+ core.renderActivityMessages = [{ activityType: "a2ui" }];
+ await nextFrame();
+ await nextFrame();
+
+ expect(result.current).toBe(before + 1);
+});
+
+/* One subscription for the whole transcript, however many activities are waiting in it. */
+test("the transcript's watch listens once and reports a change", async () => {
+ const core = fakeCore();
+ const versions: number[] = [];
+ render(
+ <LateRenderersWatch
+ core={core}
+ onVersion={(version) => versions.push(version)}
+ settled={undefined}
+ />,
+ );
+ expect(core.listeners.size).toBe(1);
+
+ core.renderActivityMessages = [{ activityType: "a2ui" }];
+ act(() => core.connect());
+ await nextFrame();
+
+ expect(versions).toEqual([1]);
+});
diff --git a/app/tests/paced-reveal-clock.test.tsx b/app/tests/paced-reveal-clock.test.tsx
new file mode 100644
index 00000000..eec988ae
--- /dev/null
+++ b/app/tests/paced-reveal-clock.test.tsx
@@ -0,0 +1,90 @@
+import { afterAll, afterEach, beforeAll, expect, test } from "bun:test";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { act, cleanup, renderHook } from "@testing-library/react";
+import {
+ FINISH_MS,
+ nextReveal,
+ usePacedReveal,
+} from "@/components/channels/paced-reveal";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * Tokens arrive every 10 to 20ms, between frames. Each used to restart the reveal's frame loop and
+ * its clock, so the next frame measured the few ms since the token rather than the ~16ms since the
+ * last frame, and the reveal ran at a fraction of its pace. Driven here by hand: a frame every 16ms,
+ * a token 10ms into each.
+ */
+
+let now = 0;
+let queue: FrameRequestCallback[] = [];
+const real = {
+ raf: globalThis.requestAnimationFrame,
+ caf: globalThis.cancelAnimationFrame,
+ now: performance.now.bind(performance),
+};
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+ window.requestAnimationFrame = (callback) => {
+ queue.push(callback);
+ return queue.length;
+ };
+ window.cancelAnimationFrame = (id) => {
+ queue[id - 1] = () => {};
+ };
+ performance.now = () => now;
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+afterAll(async () => {
+ window.requestAnimationFrame = real.raf;
+ window.cancelAnimationFrame = real.caf;
+ performance.now = real.now;
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+function frame() {
+ const callbacks = queue;
+ queue = [];
+ act(() => {
+ for (const callback of callbacks) callback(now);
+ });
+}
+
+test("a reply keeps its pace while tokens arrive between frames", () => {
+ let text = Array.from({ length: 200 }, (_, index) => `w${index}`).join(" ");
+ const start = text.length;
+ const { result, rerender } = renderHook(
+ ({ value }) => usePacedReveal(value, { live: true, streaming: true }),
+ { initialProps: { value: text } },
+ );
+
+ // 400ms: the catch-up budget for the backlog that was there at the start.
+ for (let index = 0; index < 25; index++) {
+ now += 10;
+ text += ` t${index}`;
+ rerender({ value: text });
+ now += 6;
+ frame();
+ }
+
+ // What the same frames reveal when each one counts its full 16ms.
+ let ideal = 0;
+ let grown = Array.from({ length: 200 }, (_, index) => `w${index}`).join(" ");
+ for (let index = 0; index < 25; index++) {
+ grown += ` t${index}`;
+ ideal = nextReveal({
+ text: grown,
+ shown: ideal,
+ elapsedMs: 16,
+ streaming: true,
+ finishInMs: FINISH_MS,
+ });
+ }
+ expect(ideal).toBeGreaterThan(start / 2);
+ expect(result.current.length).toBeGreaterThanOrEqual(ideal * 0.95);
+});
diff --git a/app/tests/paced-reveal.test.ts b/app/tests/paced-reveal.test.ts
new file mode 100644
index 00000000..6b8aef4c
--- /dev/null
+++ b/app/tests/paced-reveal.test.ts
@@ -0,0 +1,127 @@
+import { expect, test } from "bun:test";
+import { FINISH_MS, nextReveal } from "@/components/channels/paced-reveal";
+
+/**
+ * A streaming reply arrives in bursts; it is revealed at a steady pace a little behind what has
+ * arrived, a word at a time, and never so far behind that it is still typing long after the Bot
+ * stopped: once the stream ends, the rest is out within FINISH_MS.
+ */
+
+const BURST = Array.from(
+ { length: 80 },
+ (_, index) => `word${index % 10}`,
+).join(" ");
+
+function atBoundary(text: string, shown: number): boolean {
+ return shown === text.length || /\s/.test(text[shown] ?? "");
+}
+
+test("a 400-character burst reveals over several frames, on word boundaries", () => {
+ const text = BURST.slice(0, 400);
+ const lastSpace = text.lastIndexOf(" ");
+ const seen = new Set<number>();
+ let shown = 0;
+ for (let frame = 0; frame < 120; frame++) {
+ shown = nextReveal({
+ text,
+ shown,
+ elapsedMs: 16,
+ streaming: true,
+ finishInMs: FINISH_MS,
+ });
+ seen.add(shown);
+ expect(atBoundary(text, shown)).toBe(true);
+ expect(shown).toBeLessThanOrEqual(lastSpace);
+ }
+ expect(seen.size).toBeGreaterThanOrEqual(5);
+ expect(shown).toBe(lastSpace);
+});
+
+test("after the stream ends the rest is revealed within FINISH_MS", () => {
+ const text = BURST;
+ let shown = 0;
+ let finishInMs = FINISH_MS;
+ while (finishInMs > 0) {
+ shown = nextReveal({
+ text,
+ shown,
+ elapsedMs: 16,
+ streaming: false,
+ finishInMs,
+ });
+ expect(atBoundary(text, shown)).toBe(true);
+ finishInMs -= 16;
+ }
+ shown = nextReveal({
+ text,
+ shown,
+ elapsedMs: 16,
+ streaming: false,
+ finishInMs,
+ });
+ expect(shown).toBe(text.length);
+});
+
+test("never goes backwards", () => {
+ const text = "one two three four";
+ expect(
+ nextReveal({
+ text,
+ shown: 8,
+ elapsedMs: 0,
+ streaming: true,
+ finishInMs: FINISH_MS,
+ }),
+ ).toBeGreaterThanOrEqual(8);
+});
+
+test("a shorter text clamps", () => {
+ expect(
+ nextReveal({
+ text: "short",
+ shown: 40,
+ elapsedMs: 16,
+ streaming: true,
+ finishInMs: FINISH_MS,
+ }),
+ ).toBe(5);
+});
+
+/*
+ * Text with no spaces (Chinese, Japanese, a long link) has no word to stop at. Held back to the last
+ * space, the whole reply stayed hidden for as long as it streamed and then appeared at once.
+ */
+test("text with no spaces still reveals while it streams", () => {
+ const text = "这是一个没有空格的很长的回答".repeat(20);
+ const seen = new Set<number>();
+ let shown = 0;
+ for (let frame = 0; frame < 60; frame++) {
+ shown = nextReveal({
+ text,
+ shown,
+ elapsedMs: 16,
+ streaming: true,
+ finishInMs: FINISH_MS,
+ });
+ seen.add(shown);
+ }
+ expect(seen.size).toBeGreaterThanOrEqual(5);
+ expect(shown).toBeGreaterThan(text.length / 2);
+});
+
+/* A reply whose text has stopped growing is finished, even while the run goes on with other work. */
+test("a tail that has stopped growing is shown", () => {
+ const text = "here is a chart of your sales:";
+ let shown = 0;
+ for (let frame = 0; frame < 60; frame++) {
+ shown = nextReveal({
+ text,
+ shown,
+ elapsedMs: 16,
+ streaming: true,
+ holdTail: false,
+ finishInMs: FINISH_MS,
+ });
+ }
+ expect(shown).toBe(text.length);
+});
diff --git a/app/tests/send-glide.test.ts b/app/tests/send-glide.test.ts
new file mode 100644
index 00000000..0103569a
--- /dev/null
+++ b/app/tests/send-glide.test.ts
@@ -0,0 +1,63 @@
+import { expect, test } from "bun:test";
+import { shouldGlideOnSend } from "@/components/channels/chat-transcript";
+
+/**
+ * The viewport glides for a beat when the person sends something, so the eye can follow their
+ * message up to where it anchors. It must never glide for history: that animated the jump to the
+ * bottom while a channel opened, which is the one moment nothing should be seen moving.
+ */
+
+test("no glide while restoring", () => {
+ expect(
+ shouldGlideOnSend({
+ previous: "a",
+ next: "b",
+ restoring: true,
+ reducedMotion: false,
+ }),
+ ).toBe(false);
+});
+
+test("no glide for the first id after restore", () => {
+ expect(
+ shouldGlideOnSend({
+ previous: null,
+ next: "b",
+ restoring: false,
+ reducedMotion: false,
+ }),
+ ).toBe(false);
+});
+
+test("glide when a new message is sent", () => {
+ expect(
+ shouldGlideOnSend({
+ previous: "a",
+ next: "b",
+ restoring: false,
+ reducedMotion: false,
+ }),
+ ).toBe(true);
+});
+
+test("no glide when nothing changed", () => {
+ expect(
+ shouldGlideOnSend({
+ previous: "a",
+ next: "a",
+ restoring: false,
+ reducedMotion: false,
+ }),
+ ).toBe(false);
+});
+
+test("no glide under reduced motion", () => {
+ expect(
+ shouldGlideOnSend({
+ previous: "a",
+ next: "b",
+ restoring: false,
+ reducedMotion: true,
+ }),
+ ).toBe(false);
+});
diff --git a/app/tests/settled-args.test.ts b/app/tests/settled-args.test.ts
new file mode 100644
index 00000000..395a1e86
--- /dev/null
+++ b/app/tests/settled-args.test.ts
@@ -0,0 +1,53 @@
+import { expect, test } from "bun:test";
+import { settledArgs } from "@/lib/copilot/settled-args";
+
+/**
+ * Partial JSON only ever stops at its end, so of all the arguments drawn while a call streams, only
+ * the last value can be half there. A label that is half typed reads fine; a number that is half
+ * typed is a different number (12 on its way to 125), so a bar would jump. Those are held back until
+ * something follows them or the call completes.
+ */
+
+test("a trailing number is held back while streaming", () => {
+ expect(
+ settledArgs(
+ {
+ points: [
+ { label: "A", value: 4 },
+ { label: "B", value: 12 },
+ ],
+ },
+ false,
+ ),
+ ).toEqual({ points: [{ label: "A", value: 4 }, { label: "B" }] });
+});
+
+test("complete arguments are returned as they are", () => {
+ const args = { points: [{ label: "B", value: 12 }] };
+ expect(settledArgs(args, true)).toBe(args);
+});
+
+test("a trailing label is kept", () => {
+ expect(settledArgs({ points: [{ value: 4, label: "Rev" }] }, false)).toEqual({
+ points: [{ value: 4, label: "Rev" }],
+ });
+});
+
+test("a trailing link is held back", () => {
+ expect(
+ settledArgs({ title: "Docs", link: { url: "https://exa" } }, false),
+ ).toEqual({ title: "Docs", link: {} });
+});
+
+test("a trailing colour is held back", () => {
+ expect(settledArgs({ title: "Status", colour: "#3" }, false)).toEqual({
+ title: "Status",
+ });
+});
+
+test("a number followed by another key is kept", () => {
+ expect(settledArgs({ value: 12, label: "B" }, false)).toEqual({
+ value: 12,
+ label: "B",
+ });
+});
diff --git a/app/tests/tool-activity.test.tsx b/app/tests/tool-activity.test.tsx
index 92697842..a18c470d 100644
--- a/app/tests/tool-activity.test.tsx
+++ b/app/tests/tool-activity.test.tsx
@@ -62,16 +62,26 @@ test("adjacent connector calls fold into one row named after the first", () => {
];
const grouped = groupToolSteps(items, drawn);
expect(grouped.map((item) => item.kind)).toEqual(["tools", "text"]);
- expect(grouped[0]).toMatchObject({ id: "search", steps: items.slice(0, 3) });
+ expect(grouped[0]).toMatchObject({
+ id: "group:search",
+ steps: items.slice(0, 3),
+ });
});
test("one connector call keeps its own line, and anything the app draws stays where it is", () => {
- expect(groupToolSteps([search()], drawn)).toEqual([search()]);
+ // Drawn as its own line, inside the one row type a run uses, so a second call does not rebuild it.
+ expect(groupToolSteps([search()], drawn)).toEqual([
+ { kind: "tools", id: "group:search", steps: [search()] },
+ ]);
const chart = call("chart", "showBarChart");
const help = call("help", "computer_request_help");
for (const boundary of [chart, help, text("between")]) {
const grouped = groupToolSteps([search("a"), boundary, search("b")], drawn);
- expect(grouped.map((item) => item.id)).toEqual(["a", boundary.id, "b"]);
+ expect(grouped.map((item) => item.id)).toEqual([
+ "group:a",
+ boundary.id,
+ "group:b",
+ ]);
}
});
@@ -81,10 +91,10 @@ test("a run of tools the app does not draw folds like connector calls do", () =>
);
const grouped = groupToolSteps([...commands, text("answer")], drawn);
expect(grouped.map((item) => item.kind)).toEqual(["tools", "text"]);
- expect(grouped[0]).toMatchObject({ id: "cmd1", steps: commands });
+ expect(grouped[0]).toMatchObject({ id: "group:cmd1", steps: commands });
// On its own it keeps its own line, as a lone connector call does.
expect(groupToolSteps([commands[0] as ToolItem], drawn)).toEqual([
- commands[0] as ToolItem,
+ { kind: "tools", id: "group:cmd1", steps: [commands[0] as ToolItem] },
]);
// And it joins a run of connector calls rather than splitting it.
const mixed = groupToolSteps([search("a"), commands[0] as ToolItem], drawn);
@@ -101,7 +111,11 @@ test("a tool the app draws ends a run, whatever it is called", () => {
],
drawn,
);
- expect(grouped.map((item) => item.id)).toEqual(["a", "chart", "c"]);
+ expect(grouped.map((item) => item.id)).toEqual([
+ "group:a",
+ "chart",
+ "group:c",
+ ]);
});
test("a tool step is named in words and counted as tools", () => {
@@ -198,7 +212,11 @@ test("the app-access card stays out of a group, even before its answer arrives",
]) {
const card = call("card", "show_app_access", { app: "gmail" }, result);
const grouped = groupToolSteps([search("a"), card, search("b")], drawn);
- expect(grouped.map((item) => item.id)).toEqual(["a", "card", "b"]);
+ expect(grouped.map((item) => item.id)).toEqual([
+ "group:a",
+ "card",
+ "group:b",
+ ]);
}
});
diff --git a/app/tests/tool-boundary.test.tsx b/app/tests/tool-boundary.test.tsx
new file mode 100644
index 00000000..c65028de
--- /dev/null
+++ b/app/tests/tool-boundary.test.tsx
@@ -0,0 +1,136 @@
+import { afterAll, afterEach, beforeAll, expect, spyOn, test } from "bun:test";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { cleanup, render } from "@testing-library/react";
+import {
+ ToolRenderBoundary,
+ toolCallFinal,
+} from "@/components/channels/tool-boundary";
+import { ArgumentsArrivingContext } from "@/components/gallery/streaming";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * A card drawn from a tool call that is still streaming can throw on arguments that are only half
+ * there, and be perfectly drawable a chunk later. The boundary gives it that chance; only a throw on
+ * the complete arguments is final.
+ */
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+afterAll(async () => {
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+function Fragile({ args }: { args: string }) {
+ if (args === "bad" || args === "still bad") throw new Error("half-sent");
+ return <p>drawn {args}</p>;
+}
+
+const FALLBACK = /Couldn't show/;
+
+test("recovers on the next chunk", () => {
+ const quiet = spyOn(console, "error").mockImplementation(() => {});
+ const view = render(
+ <ToolRenderBoundary name="Chart" resetKey="bad">
+ <Fragile args="bad" />
+ </ToolRenderBoundary>,
+ );
+ // Nothing between chunks: the error box flashing on every half-sent chunk read as a failure.
+ expect(view.queryByText(FALLBACK)).toBeNull();
+
+ view.rerender(
+ <ToolRenderBoundary name="Chart" resetKey="good">
+ <Fragile args="good" />
+ </ToolRenderBoundary>,
+ );
+
+ expect(view.getByText("drawn good")).toBeTruthy();
+ quiet.mockRestore();
+});
+
+test("stays failed once the call is complete", () => {
+ const quiet = spyOn(console, "error").mockImplementation(() => {});
+ const view = render(
+ <ToolRenderBoundary final name="Chart" resetKey="bad">
+ <Fragile args="bad" />
+ </ToolRenderBoundary>,
+ );
+
+ view.rerender(
+ <ToolRenderBoundary final name="Chart" resetKey="other">
+ <Fragile args="still bad" />
+ </ToolRenderBoundary>,
+ );
+
+ expect(view.getByText(FALLBACK)).toBeTruthy();
+ quiet.mockRestore();
+});
+
+test("no reset key keeps today's behaviour", () => {
+ const quiet = spyOn(console, "error").mockImplementation(() => {});
+ const view = render(
+ <ToolRenderBoundary name="Chart">
+ <Fragile args="bad" />
+ </ToolRenderBoundary>,
+ );
+
+ view.rerender(
+ <ToolRenderBoundary name="Chart">
+ <Fragile args="good" />
+ </ToolRenderBoundary>,
+ );
+
+ expect(view.getByText(FALLBACK)).toBeTruthy();
+ quiet.mockRestore();
+});
+
+/* A call whose arguments can no longer arrive (its run stopped) has no next chunk to wait for. */
+test("a failure in a row that can no longer receive arguments shows", () => {
+ const quiet = spyOn(console, "error").mockImplementation(() => {});
+ const view = render(
+ <ArgumentsArrivingContext.Provider value={false}>
+ <ToolRenderBoundary name="Chart" resetKey="bad">
+ <Fragile args="bad" />
+ </ToolRenderBoundary>
+ </ArgumentsArrivingContext.Provider>,
+ );
+
+ expect(view.getByText(FALLBACK)).toBeTruthy();
+ quiet.mockRestore();
+});
+
+/*
+ * A decision has no result until the person answers it, and the run stays busy for the whole wait,
+ * so "final" cannot mean "has a result": a decision that threw on its complete arguments drew
+ * nothing, and the turn hung invisibly until somebody pressed Stop. A call is final once its
+ * arguments are complete, and streamed arguments only parse once the last of them has arrived.
+ */
+test("a call is final once its arguments are complete, before any result", () => {
+ expect(toolCallFinal('{"options": "a, b"}', undefined)).toBe(true);
+ expect(toolCallFinal('{"options": ["a", "b"', undefined)).toBe(false);
+ expect(toolCallFinal("", undefined)).toBe(false);
+ expect(toolCallFinal('{"options": [', "answered")).toBe(true);
+});
+
+test("a decision that throws on complete arguments while it waits shows its failure", () => {
+ const quiet = spyOn(console, "error").mockImplementation(() => {});
+ const args = '{"options": "a, b"}';
+ const view = render(
+ <ToolRenderBoundary
+ final={toolCallFinal(args, undefined)}
+ name="Choice"
+ resetKey={args}
+ >
+ <Fragile args="bad" />
+ </ToolRenderBoundary>,
+ );
+
+ expect(view.getByText(FALLBACK)).toBeTruthy();
+ quiet.mockRestore();
+});
diff --git a/app/tests/tool-rows.test.ts b/app/tests/tool-rows.test.ts
new file mode 100644
index 00000000..665832fc
--- /dev/null
+++ b/app/tests/tool-rows.test.ts
@@ -0,0 +1,96 @@
+import { expect, test } from "bun:test";
+import { connectAppRefusal } from "@openbot/shared/connect-prompt";
+import type { VisibleChatItem } from "../src/components/channels/chat-messages";
+import { groupToolSteps } from "../src/components/channels/tool-activity";
+import { REFUSAL_MARKER } from "../src/lib/plugins/tool-result";
+
+/**
+ * A row of tool calls keeps one key for its whole life. React keys the transcript row on it, so a
+ * key that changed when a second call arrived, or when the first call turned out to ask the person
+ * something, tore the row down and rebuilt it: its entrance replayed and anything drawn in it
+ * flickered. Group ids carry a `group:` prefix so they can never collide with a single row's id.
+ */
+
+type ToolItem = Extract<VisibleChatItem, { kind: "tool" }>;
+
+function call(id: string, result?: string): ToolItem {
+ return {
+ kind: "tool",
+ id,
+ toolCall: {
+ id,
+ type: "function",
+ function: { name: "mcp__exa__web_search_exa", arguments: "{}" },
+ },
+ ...(result === undefined ? {} : { result }),
+ };
+}
+
+const text = (id: string): VisibleChatItem => ({
+ kind: "text",
+ id,
+ role: "assistant",
+ text: "Here is what I found.",
+});
+
+const asks = `${REFUSAL_MARKER} ${connectAppRefusal({
+ serverId: "composio-gmail",
+ title: "Gmail",
+ message: "You have not connected your Gmail account.",
+ agentId: "expenses",
+})}`;
+
+const drawsNothing = () => false;
+
+test("a lone foldable call is a group of one under a group key", () => {
+ const grouped = groupToolSteps([call("t1")], drawsNothing, new Map());
+ expect(grouped).toEqual([
+ { kind: "tools", id: "group:t1", steps: [call("t1")] },
+ ]);
+});
+
+test("a second adjacent call keeps the row id", () => {
+ const rowIds = new Map<string, string>();
+ const first = groupToolSteps([call("t1")], drawsNothing, rowIds);
+ const second = groupToolSteps([call("t1"), call("t2")], drawsNothing, rowIds);
+ expect(first.map((item) => item.id)).toEqual(["group:t1"]);
+ expect(second.map((item) => item.id)).toEqual(["group:t1"]);
+});
+
+test("a first step that leaves the group does not take the group's id with it", () => {
+ const rowIds = new Map<string, string>();
+ groupToolSteps([call("t1"), call("t2"), call("t3")], drawsNothing, rowIds);
+ const after = groupToolSteps(
+ [call("t1", asks), call("t2"), call("t3")],
+ drawsNothing,
+ rowIds,
+ );
+ expect(after.map((item) => [item.kind, item.id])).toEqual([
+ ["tool", "t1"],
+ ["tools", "group:t1"],
+ ]);
+});
+
+test("two groups never claim the same row id", () => {
+ const rowIds = new Map<string, string>();
+ groupToolSteps([call("t1"), call("t2")], drawsNothing, rowIds);
+ const split = groupToolSteps(
+ [call("t1"), text("between"), call("t2")],
+ drawsNothing,
+ rowIds,
+ );
+ expect(split.map((item) => item.id)).toEqual([
+ "group:t1",
+ "between",
+ "group:t2",
+ ]);
+});
+
+test("a lone call whose result asks the person keeps its row id", () => {
+ const rowIds = new Map<string, string>();
+ groupToolSteps([call("t1")], drawsNothing, rowIds);
+ const after = groupToolSteps([call("t1", asks)], drawsNothing, rowIds);
+ expect(after.map((item) => [item.kind, item.id])).toEqual([
+ ["tool", "group:t1"],
+ ]);
+});
diff --git a/app/tests/transcript-attachments.test.tsx b/app/tests/transcript-attachments.test.tsx
index 74742107..a15bc1e1 100644
--- a/app/tests/transcript-attachments.test.tsx
+++ b/app/tests/transcript-attachments.test.tsx
@@ -758,10 +758,7 @@ test("a rebuilt but unchanged row of files compares equal", () => {
const rebuilt = ONE_FILE.map((file) => ({ ...file }));
expect(
- sameAttachmentRow(
- { attachments: ONE_FILE, delay: 0 },
- { attachments: rebuilt, delay: 0 },
- ),
+ sameAttachmentRow({ attachments: ONE_FILE }, { attachments: rebuilt }),
).toBe(true);
});
@@ -777,30 +774,18 @@ test("a row that actually changed does not compare equal", () => {
for (const file of changed) {
expect(
- sameAttachmentRow(
- { attachments: ONE_FILE, delay: 0 },
- { attachments: [file], delay: 0 },
- ),
+ sameAttachmentRow({ attachments: ONE_FILE }, { attachments: [file] }),
).toBe(false);
}
- // A file added, a file taken away, and the entrance delay itself — all of them redraw.
- expect(
- sameAttachmentRow(
- { attachments: ONE_FILE, delay: 0 },
- { attachments: [], delay: 0 },
- ),
- ).toBe(false);
+ // A file added or a file taken away — both redraw.
expect(
- sameAttachmentRow(
- { attachments: ONE_FILE, delay: 0 },
- { attachments: [...ONE_FILE, ONE_FILE[0]], delay: 0 },
- ),
+ sameAttachmentRow({ attachments: ONE_FILE }, { attachments: [] }),
).toBe(false);
expect(
sameAttachmentRow(
- { attachments: ONE_FILE, delay: 0 },
- { attachments: ONE_FILE, delay: 0.04 },
+ { attachments: ONE_FILE },
+ { attachments: [...ONE_FILE, ONE_FILE[0]] },
),
).toBe(false);
});
diff --git a/app/tests/transcript-follow.test.tsx b/app/tests/transcript-follow.test.tsx
new file mode 100644
index 00000000..21ebfcaa
--- /dev/null
+++ b/app/tests/transcript-follow.test.tsx
@@ -0,0 +1,222 @@
+import { afterAll, afterEach, beforeAll, expect, test } from "bun:test";
+import type { Message } from "@ag-ui/core";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { act, cleanup, fireEvent, render } from "@testing-library/react";
+import { ChatTranscript } from "@/components/channels/chat-transcript";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * The transcript follows a streaming reply until the person moves up the page or selects some of
+ * it, and picks it up again when they send. `data-following` on the viewport is what the scroller
+ * was told (`autoScroll`).
+ */
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+});
+
+afterEach(() => {
+ document.getSelection()?.removeAllRanges();
+ cleanup();
+});
+
+afterAll(async () => {
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+function user(id: string, text: string): Message {
+ return { id, role: "user", content: text };
+}
+
+function assistant(id: string, text: string): Message {
+ return { id, role: "assistant", content: text };
+}
+
+const HISTORY = [user("u1", "first question"), assistant("a1", "first answer")];
+
+function viewport(container: HTMLElement): HTMLElement {
+ return container.querySelector(
+ '[data-slot="message-scroller-viewport"]',
+ ) as HTMLElement;
+}
+
+function following(container: HTMLElement): string | null {
+ return viewport(container).getAttribute("data-following");
+}
+
+function select(node: Node) {
+ act(() => {
+ document.getSelection()?.selectAllChildren(node);
+ document.dispatchEvent(new Event("selectionchange"));
+ });
+}
+
+function clearSelection() {
+ act(() => {
+ document.getSelection()?.removeAllRanges();
+ document.dispatchEvent(new Event("selectionchange"));
+ });
+}
+
+test("follows by default", () => {
+ const view = render(<ChatTranscript messages={HISTORY} restoring={false} />);
+
+ expect(following(view.container)).toBe("true");
+});
+
+test("an upward wheel stops following", () => {
+ const view = render(<ChatTranscript messages={HISTORY} restoring={false} />);
+
+ fireEvent.wheel(viewport(view.container), { deltaY: -100 });
+
+ expect(following(view.container)).toBe("false");
+});
+
+test("a selection outside the transcript does not pause", () => {
+ const view = render(
+ <>
+ <p>outside the transcript</p>
+ <ChatTranscript messages={HISTORY} restoring={false} />
+ </>,
+ );
+
+ select(view.getByText("outside the transcript"));
+
+ expect(following(view.container)).toBe("true");
+});
+
+test("selecting transcript text pauses and clearing it resumes", () => {
+ const view = render(<ChatTranscript messages={HISTORY} restoring={false} />);
+
+ select(view.getByText("first answer"));
+ expect(following(view.container)).toBe("false");
+
+ clearSelection();
+ expect(following(view.container)).toBe("true");
+});
+
+test("sending a message resumes following", () => {
+ const view = render(<ChatTranscript messages={HISTORY} restoring={false} />);
+ fireEvent.wheel(viewport(view.container), { deltaY: -100 });
+
+ view.rerender(
+ <ChatTranscript
+ messages={[...HISTORY, user("u2", "another question")]}
+ restoring={false}
+ />,
+ );
+
+ expect(following(view.container)).toBe("true");
+});
+
+test("switching channels follows again", () => {
+ const view = render(<ChatTranscript messages={HISTORY} restoring={false} />);
+ fireEvent.wheel(viewport(view.container), { deltaY: -100 });
+
+ view.rerender(<ChatTranscript messages={[]} restoring />);
+ view.rerender(<ChatTranscript messages={HISTORY} restoring={false} />);
+
+ expect(following(view.container)).toBe("true");
+});
+
+test("the scroll button stays mounted", () => {
+ const view = render(<ChatTranscript messages={HISTORY} restoring={false} />);
+
+ const button = view.container.querySelector(
+ '[data-slot="message-scroller-button"]',
+ );
+ expect(button).toBeTruthy();
+ expect(button?.getAttribute("data-active")).toBe("false");
+});
+
+/*
+ * Keys typed into a field inside the transcript (a form in an app card) move a caret, not the
+ * page. Pausing on them left somebody at the very end of a conversation not following it, with no
+ * way back short of the button.
+ */
+test("arrow keys in a field inside the transcript do not pause", () => {
+ const view = render(<ChatTranscript messages={HISTORY} restoring={false} />);
+ const input = document.createElement("input");
+ view.getByText("first answer").appendChild(input);
+
+ fireEvent.keyDown(input, { key: "ArrowUp" });
+ fireEvent.keyDown(input, { key: " ", shiftKey: true });
+
+ expect(following(view.container)).toBe("true");
+});
+
+test("scroll keys on the transcript itself pause", () => {
+ const view = render(<ChatTranscript messages={HISTORY} restoring={false} />);
+
+ fireEvent.keyDown(viewport(view.container), { key: "PageUp" });
+
+ expect(following(view.container)).toBe("false");
+});
+
+/*
+ * Only a press on the scrollbar makes an upward scroll the person's. A finger or mouse resting on a
+ * message while the content shrinks and clamps the view upward is a layout correction.
+ */
+test("a press on a message does not make a layout clamp a scrollbar drag", () => {
+ const view = render(<ChatTranscript messages={HISTORY} restoring={false} />);
+ const element = viewport(view.container);
+ let top = 500;
+ Object.defineProperty(element, "scrollTop", {
+ configurable: true,
+ get: () => top,
+ });
+
+ fireEvent.scroll(element);
+ fireEvent.pointerDown(view.getByText("first answer"));
+ top = 400;
+ fireEvent.scroll(element);
+
+ expect(following(view.container)).toBe("true");
+});
+
+/*
+ * An overlay scrollbar (macOS with a trackpad) takes no width, and a right-to-left one sits on the
+ * left, so a press on the thumb lands inside the content box. It is still a press on the viewport
+ * itself, not on a message in it.
+ */
+test("dragging an overlay scrollbar up pauses", () => {
+ const view = render(<ChatTranscript messages={HISTORY} restoring={false} />);
+ const element = viewport(view.container);
+ let top = 500;
+ Object.defineProperty(element, "scrollTop", {
+ configurable: true,
+ get: () => top,
+ });
+ Object.defineProperty(element, "clientWidth", {
+ configurable: true,
+ get: () => 900,
+ });
+
+ fireEvent.scroll(element);
+ fireEvent.pointerDown(element, { clientX: 890 });
+ top = 400;
+ fireEvent.scroll(element);
+
+ expect(following(view.container)).toBe("false");
+});
+
+/*
+ * A routine's channel can hold nothing the person sent: only firings and what the Bot said. Their
+ * first message there is still a send, though there was no earlier one to compare it with.
+ */
+test("the first message a person sends picks following up again", () => {
+ const before = [assistant("a0", "the daily digest")];
+ const view = render(<ChatTranscript messages={before} restoring={false} />);
+ fireEvent.wheel(viewport(view.container), { deltaY: -100 });
+ expect(following(view.container)).toBe("false");
+
+ view.rerender(
+ <ChatTranscript
+ messages={[...before, user("u1", "what changed?")]}
+ restoring={false}
+ />,
+ );
+
+ expect(following(view.container)).toBe("true");
+});
diff --git a/app/tests/transcript-late-voice.test.tsx b/app/tests/transcript-late-voice.test.tsx
new file mode 100644
index 00000000..f1d24216
--- /dev/null
+++ b/app/tests/transcript-late-voice.test.tsx
@@ -0,0 +1,83 @@
+import { afterAll, afterEach, beforeAll, expect, test } from "bun:test";
+import type { Message } from "@ag-ui/core";
+import { CopilotKitProvider } from "@copilotkit/react-core/v2";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { cleanup, render } from "@testing-library/react";
+import { ChatTranscript } from "@/components/channels/chat-transcript";
+import { type VoiceChatEntry, withVoiceChats } from "@/lib/voice/archive";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * A conversation shows without its voice chats when the voice service is slow, and the cards join
+ * it when they arrive. A card for a call that happened before the conversation opened is history:
+ * it lands among rows already on screen and must not play the entrance of something that just
+ * happened. A call made while the conversation is open still arrives as one.
+ */
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+afterAll(async () => {
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+const history: Message[] = [
+ { id: "u1", role: "user", content: "one" },
+ { id: "a1", role: "assistant", content: "two" },
+ { id: "u2", role: "user", content: "three" },
+ { id: "a2", role: "assistant", content: "four" },
+];
+
+function call(id: string, startedAt: Date): VoiceChatEntry {
+ return {
+ id,
+ channelId: "c",
+ anchorMessageId: "a1",
+ startedAt: startedAt.toISOString(),
+ endedAt: new Date(startedAt.getTime() + 60_000).toISOString(),
+ transcript: [],
+ durationSeconds: 60,
+ summary: null,
+ summaryStatus: "ready",
+ };
+}
+
+function transcript(calls: VoiceChatEntry[]) {
+ return (
+ <CopilotKitProvider>
+ <ChatTranscript
+ messages={withVoiceChats(history, calls)}
+ restoring={false}
+ />
+ </CopilotKitProvider>
+ );
+}
+
+function cardStartsHidden(container: HTMLElement): boolean {
+ const row = container.querySelector('[data-message-id^="voice-chat:"]');
+ const arriving = row?.querySelector('[data-slot="message-arriving"]');
+ expect(arriving).not.toBeNull();
+ return /opacity:\s*0(?![.\d])/.test(arriving?.getAttribute("style") ?? "");
+}
+
+test("a voice chat from before the conversation opened arrives at rest", () => {
+ const view = render(transcript([]));
+
+ view.rerender(transcript([call("v1", new Date(Date.now() - 3_600_000))]));
+
+ expect(cardStartsHidden(view.container)).toBe(false);
+});
+
+test("a voice chat made while the conversation is open arrives live", () => {
+ const view = render(transcript([]));
+
+ view.rerender(transcript([call("v2", new Date(Date.now() + 1_000))]));
+
+ expect(cardStartsHidden(view.container)).toBe(true);
+});
diff --git a/app/tests/transcript-open.test.tsx b/app/tests/transcript-open.test.tsx
new file mode 100644
index 00000000..46ebb013
--- /dev/null
+++ b/app/tests/transcript-open.test.tsx
@@ -0,0 +1,209 @@
+import { afterAll, afterEach, beforeAll, expect, test } from "bun:test";
+import type { Message } from "@ag-ui/core";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { cleanup, render } from "@testing-library/react";
+import { ChatTranscript } from "@/components/channels/chat-transcript";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * What a person sees when a conversation opens.
+ *
+ * History arrives in pieces (the gateway snapshot, then the stored thread merged into it), and the
+ * scroller decides where to land exactly once, the first time it sees a row. So the transcript
+ * draws nothing but the placeholder until history is complete, and then mounts the scroller with
+ * every row at once — the only way its single landing is at the bottom of the whole conversation.
+ *
+ * Harness as in `transcript-attachments.test.tsx`: one document for the file, cleaned per test.
+ */
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+afterAll(async () => {
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+function user(id: string, text: string): Message {
+ return { id, role: "user", content: text };
+}
+
+function assistant(id: string, text: string): Message {
+ return { id, role: "assistant", content: text };
+}
+
+const PLACEHOLDER = "Loading this conversation";
+
+test("restoring hides rows the snapshot already delivered", () => {
+ const view = render(
+ <ChatTranscript
+ messages={[user("u1", "hi"), assistant("a1", "hello")]}
+ restoring
+ />,
+ );
+
+ expect(view.queryByText("hello")).toBeNull();
+ expect(view.container.querySelectorAll("[data-message-id]").length).toBe(0);
+ expect(view.getByLabelText(PLACEHOLDER)).toBeTruthy();
+});
+
+test("rows appear together when restoring ends", () => {
+ const messages = [user("u1", "hi"), assistant("a1", "hello")];
+ const view = render(<ChatTranscript messages={messages} restoring />);
+
+ view.rerender(<ChatTranscript messages={messages} restoring={false} />);
+
+ expect(view.getByText("hi")).toBeTruthy();
+ expect(view.getByText("hello")).toBeTruthy();
+ expect(view.container.querySelectorAll("[data-message-id]").length).toBe(2);
+ expect(view.queryByLabelText(PLACEHOLDER)).toBeNull();
+});
+
+test("a seeded channel shows its first message at once", () => {
+ const view = render(
+ <ChatTranscript messages={[user("u1", "first")]} restoring={false} />,
+ );
+
+ expect(view.getByText("first")).toBeTruthy();
+ expect(view.queryByLabelText(PLACEHOLDER)).toBeNull();
+});
+
+test("an empty conversation shows neither placeholder nor rows once restored", () => {
+ const view = render(<ChatTranscript messages={[]} restoring={false} />);
+
+ expect(view.queryByLabelText(PLACEHOLDER)).toBeNull();
+ expect(view.container.querySelectorAll("[data-message-id]").length).toBe(0);
+});
+
+/**
+ * Only what arrives while the conversation is open animates in. History is already there when it
+ * opens; fading it in row by row read as the conversation still loading. motion renders `initial`
+ * as inline style on the first paint, so a row that animates starts at `opacity: 0`.
+ */
+function startsHidden(element: Element): boolean {
+ return /opacity:\s*0(?![.\d])/.test(element.getAttribute("style") ?? "");
+}
+
+function arriving(container: HTMLElement): Element[] {
+ return [...container.querySelectorAll('[data-slot="message-arriving"]')];
+}
+
+test("history rows do not animate in", () => {
+ const view = render(
+ <ChatTranscript
+ messages={[
+ user("u1", "one"),
+ assistant("a1", "two"),
+ user("u2", "three"),
+ ]}
+ restoring={false}
+ />,
+ );
+
+ const rows = arriving(view.container);
+ expect(rows.length).toBe(3);
+ expect(rows.filter(startsHidden).length).toBe(0);
+});
+
+test("a live row animates in", () => {
+ const history = [user("u1", "one"), assistant("a1", "two")];
+ const view = render(<ChatTranscript messages={history} restoring={false} />);
+
+ view.rerender(
+ <ChatTranscript
+ messages={[...history, user("u2", "new")]}
+ restoring={false}
+ />,
+ );
+
+ const rows = arriving(view.container);
+ expect(rows.length).toBe(3);
+ expect(rows.map(startsHidden)).toEqual([false, false, true]);
+});
+
+test("switching channels does not animate the new history", () => {
+ const view = render(
+ <ChatTranscript messages={[user("u1", "one")]} restoring={false} />,
+ );
+
+ view.rerender(<ChatTranscript messages={[]} restoring />);
+ view.rerender(
+ <ChatTranscript
+ messages={[user("b1", "elsewhere"), assistant("b2", "reply")]}
+ restoring={false}
+ />,
+ );
+
+ const rows = arriving(view.container);
+ expect(rows.length).toBe(2);
+ expect(rows.filter(startsHidden).length).toBe(0);
+});
+
+test("a message typed while history loads is shown under the placeholder", () => {
+ const view = render(
+ <ChatTranscript
+ messages={[]}
+ queued={[
+ { id: "q1", text: "typed early", attachments: [], commandIds: [] },
+ ]}
+ restoring
+ />,
+ );
+
+ expect(view.getByLabelText(PLACEHOLDER)).toBeTruthy();
+ expect(view.getByText("typed early")).toBeTruthy();
+});
+
+/**
+ * Opening a conversation renders its newest rows in with a short stagger. It runs after the view
+ * has landed at the bottom, so it reads as the conversation appearing rather than loading: only
+ * the rows on screen take part, top of the screen first, newest last.
+ */
+function openingDelays(container: HTMLElement): (string | null)[] {
+ return [...container.querySelectorAll("[data-message-id]")].map((row) =>
+ row.classList.contains("history-arrive")
+ ? (row as HTMLElement).style.getPropertyValue("--arrive-delay")
+ : null,
+ );
+}
+
+test("the newest history rows render in, staggered toward the newest", () => {
+ const messages = Array.from({ length: 10 }, (_, index) =>
+ index % 2 === 0
+ ? user(`u${index}`, `question ${index}`)
+ : assistant(`a${index}`, `answer ${index}`),
+ );
+ const view = render(<ChatTranscript messages={messages} restoring={false} />);
+
+ expect(openingDelays(view.container)).toEqual([
+ null,
+ null,
+ "0ms",
+ "30ms",
+ "60ms",
+ "90ms",
+ "120ms",
+ "150ms",
+ "180ms",
+ "210ms",
+ ]);
+});
+
+test("a row that arrives after opening does not take the opening stagger", () => {
+ const history = [user("u1", "one"), assistant("a1", "two")];
+ const view = render(<ChatTranscript messages={history} restoring={false} />);
+
+ view.rerender(
+ <ChatTranscript
+ messages={[...history, user("u2", "new")]}
+ restoring={false}
+ />,
+ );
+
+ expect(openingDelays(view.container)).toEqual(["0ms", "30ms", null]);
+});
diff --git a/app/tests/transcript-pages.test.tsx b/app/tests/transcript-pages.test.tsx
new file mode 100644
index 00000000..e881f701
--- /dev/null
+++ b/app/tests/transcript-pages.test.tsx
@@ -0,0 +1,291 @@
+import { afterAll, afterEach, beforeAll, expect, test } from "bun:test";
+import type { Message } from "@ag-ui/core";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import {
+ act,
+ cleanup,
+ fireEvent,
+ render,
+ renderHook,
+} from "@testing-library/react";
+import { ChatTranscript } from "@/components/channels/chat-transcript";
+import {
+ earlierFrom,
+ openingFrom,
+ shouldDrawEarlier,
+ useTranscriptPages,
+} from "@/components/channels/transcript-pages";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * A conversation opens with only its newest rows drawn, and draws older ones above as the reader
+ * scrolls up. Older rows go BEFORE the always-present `contents` block so that adding them moves the
+ * scroller's first child, which is the scroller's own "rows were prepended, hold the reader's place"
+ * path; rows that arrive live still land after it, where the scroller looks for a turn to anchor.
+ */
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+afterAll(async () => {
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+function user(id: string, text: string): Message {
+ return { id, role: "user", content: text };
+}
+
+function assistant(id: string, text: string): Message {
+ return { id, role: "assistant", content: text };
+}
+
+/* Alternating turns, ids m0…m(n-1), each with its own text. */
+function conversation(count: number, prefix = "m"): Message[] {
+ return Array.from({ length: count }, (_, index) =>
+ index % 2 === 0
+ ? user(`${prefix}${index}`, `${prefix} text ${index}`)
+ : assistant(`${prefix}${index}`, `${prefix} text ${index}`),
+ );
+}
+
+function startsHidden(element: Element): boolean {
+ return /opacity:\s*0(?![.\d])/.test(element.getAttribute("style") ?? "");
+}
+
+function rows(container: HTMLElement): HTMLElement[] {
+ return [...container.querySelectorAll<HTMLElement>("[data-message-id]")];
+}
+
+function content(container: HTMLElement): HTMLElement {
+ return container.querySelector(
+ '[data-slot="message-scroller-content"]',
+ ) as HTMLElement;
+}
+
+function viewport(container: HTMLElement): HTMLElement {
+ return container.querySelector(
+ '[data-slot="message-scroller-viewport"]',
+ ) as HTMLElement;
+}
+
+/*
+ * happy-dom lays nothing out, so the reader's position is stated rather than measured: near the top
+ * until a page is drawn above, then as far down as that page pushed them, which is what the
+ * scroller's prepend path does in a browser.
+ */
+function scrollNearTop(container: HTMLElement) {
+ const element = viewport(container);
+ const opened = rows(container).length;
+ Object.defineProperty(element, "scrollHeight", {
+ configurable: true,
+ value: 5000,
+ });
+ Object.defineProperty(element, "scrollTop", {
+ configurable: true,
+ get: () => (rows(container).length > opened ? 3000 : 100),
+ });
+ fireEvent.scroll(element);
+}
+
+function childIndex(container: HTMLElement, element: Element): number {
+ return [...content(container).children].indexOf(element);
+}
+
+function contentsBlock(container: HTMLElement): Element {
+ return content(container).querySelector(":scope > .contents") as Element;
+}
+
+test("page arithmetic", () => {
+ expect(openingFrom(50)).toBe(30);
+ expect(openingFrom(12)).toBe(0);
+ expect(earlierFrom(30)).toBe(10);
+ expect(earlierFrom(10)).toBe(0);
+});
+
+test("an older page is drawn only near the top of a measured view", () => {
+ expect(
+ shouldDrawEarlier({ from: 30, scrollTop: 100, scrollHeight: 5000 }),
+ ).toBe(true);
+ expect(
+ shouldDrawEarlier({ from: 0, scrollTop: 100, scrollHeight: 5000 }),
+ ).toBe(false);
+ expect(
+ shouldDrawEarlier({ from: 30, scrollTop: 900, scrollHeight: 5000 }),
+ ).toBe(false);
+ expect(shouldDrawEarlier({ from: 30, scrollTop: 0, scrollHeight: 0 })).toBe(
+ false,
+ );
+});
+
+test("opens with only the newest page drawn", () => {
+ const view = render(
+ <ChatTranscript messages={conversation(50)} restoring={false} />,
+ );
+
+ const drawn = rows(view.container);
+ expect(drawn.length).toBe(20);
+ expect(drawn.at(-1)?.dataset.messageId).toBe("m49");
+});
+
+test("scrolling near the top draws the previous page above", () => {
+ const view = render(
+ <ChatTranscript messages={conversation(50)} restoring={false} />,
+ );
+ const before = view.container.querySelector('[data-message-id="m30"]');
+
+ scrollNearTop(view.container);
+
+ const drawn = rows(view.container);
+ expect(drawn.length).toBe(40);
+ expect(drawn[0]?.dataset.messageId).toBe("m10");
+ expect(view.container.querySelector('[data-message-id="m30"]')).toBe(before);
+ const block = contentsBlock(view.container);
+ const older = drawn.filter(
+ (row) => Number(row.dataset.messageId?.slice(1)) < 30,
+ );
+ expect(older.length).toBe(20);
+ for (const row of older) {
+ expect(childIndex(view.container, row)).toBeLessThan(
+ childIndex(view.container, block),
+ );
+ }
+});
+
+test("older rows drawn later do not animate in", () => {
+ const view = render(
+ <ChatTranscript messages={conversation(50)} restoring={false} />,
+ );
+
+ scrollNearTop(view.container);
+
+ for (let index = 10; index < 30; index++) {
+ const row = view.container.querySelector(`[data-message-id="m${index}"]`);
+ const arriving = row?.querySelector('[data-slot="message-arriving"]');
+ expect(arriving).toBeTruthy();
+ expect(startsHidden(arriving as Element)).toBe(false);
+ expect(row?.classList.contains("history-arrive")).toBe(false);
+ }
+});
+
+test("a row that arrives after older pages are drawn lands after the contents block", () => {
+ const messages = conversation(50);
+ const view = render(<ChatTranscript messages={messages} restoring={false} />);
+ scrollNearTop(view.container);
+
+ view.rerender(
+ <ChatTranscript
+ messages={[...messages, user("m50", "a new question")]}
+ restoring={false}
+ />,
+ );
+
+ const row = view.container.querySelector('[data-message-id="m50"]');
+ const children = [...content(view.container).children];
+ const spacer = children.findIndex((child) =>
+ child.hasAttribute("data-message-scroller-spacer"),
+ );
+ expect(childIndex(view.container, row as Element)).toBeGreaterThan(
+ childIndex(view.container, contentsBlock(view.container)),
+ );
+ expect(childIndex(view.container, row as Element)).toBe(spacer - 1);
+});
+
+test("switching channels draws the newest page again", () => {
+ const view = render(
+ <ChatTranscript messages={conversation(50)} restoring={false} />,
+ );
+ scrollNearTop(view.container);
+ expect(rows(view.container).length).toBe(40);
+
+ view.rerender(<ChatTranscript messages={[]} restoring />);
+ view.rerender(
+ <ChatTranscript messages={conversation(50, "n")} restoring={false} />,
+ );
+
+ const drawn = rows(view.container);
+ expect(drawn.length).toBe(20);
+ expect(drawn[0]?.dataset.messageId).toBe("n30");
+});
+
+test("a conversation shorter than a page draws everything with nothing before the contents block", () => {
+ const view = render(
+ <ChatTranscript messages={conversation(5)} restoring={false} />,
+ );
+
+ expect(rows(view.container).length).toBe(5);
+ expect(content(view.container).children[0]).toBe(
+ contentsBlock(view.container),
+ );
+});
+
+/*
+ * At the very top the browser has nothing to anchor against, so `scrollTop` stays 0 until the
+ * scroller puts the reader back, which it does after the commit. Checking again inside that commit
+ * read 0 every time and drew the whole history in one burst (and past ~50 pages, crashed React).
+ */
+test("one trigger at the very top draws one page, not the whole history", () => {
+ const view = render(
+ <ChatTranscript messages={conversation(100)} restoring={false} />,
+ );
+ const element = viewport(view.container);
+ Object.defineProperty(element, "scrollHeight", {
+ configurable: true,
+ value: 5000,
+ });
+ Object.defineProperty(element, "scrollTop", {
+ configurable: true,
+ value: 0,
+ writable: true,
+ });
+
+ fireEvent.scroll(element);
+
+ expect(rows(view.container).length).toBe(40);
+});
+
+/* A jump from the rail to a turn several pages up draws everything down to it, in one go. */
+test("drawing down to a row draws every page from it", () => {
+ const { result } = renderHook(({ ids }) => useTranscriptPages(ids, false), {
+ initialProps: { ids: rowIds(100) },
+ });
+ expect(result.current.from).toBe(80);
+
+ act(() => result.current.drawTo(33));
+ expect(result.current.from).toBe(33);
+
+ act(() => result.current.drawTo(50));
+ expect(result.current.from).toBe(33);
+});
+
+function rowIds(count: number, prefix = "r"): string[] {
+ return Array.from({ length: count }, (_, index) => `${prefix}${index}`);
+}
+
+/*
+ * Rows can be added or removed above the boundary while a conversation is open: history recovered
+ * from storage merges in a prefix, tool steps regroup. Held as indices, the boundary then sat on a
+ * different row, and rows crossed it into the live region, where they remounted and replayed their
+ * entrance. Held as rows, it stays where it was.
+ */
+test("rows added above keep the boundary and the first drawn row where they were", () => {
+ const { result, rerender } = renderHook(
+ ({ ids }) => useTranscriptPages(ids, false),
+ { initialProps: { ids: rowIds(100) } },
+ );
+ expect(result.current).toMatchObject({ from: 80, split: 80 });
+
+ rerender({ ids: [...rowIds(5, "recovered"), ...rowIds(100)] });
+ expect(result.current).toMatchObject({ from: 85, split: 85 });
+
+ act(() => result.current.drawEarlier());
+ expect(result.current.from).toBe(65);
+
+ rerender({ ids: rowIds(100).filter((id) => id !== "r3") });
+ expect(result.current).toMatchObject({ from: 59, split: 79 });
+});
diff --git a/app/tests/transcript-rail.test.tsx b/app/tests/transcript-rail.test.tsx
new file mode 100644
index 00000000..460a0597
--- /dev/null
+++ b/app/tests/transcript-rail.test.tsx
@@ -0,0 +1,153 @@
+import {
+ afterAll,
+ afterEach,
+ beforeAll,
+ expect,
+ mock,
+ spyOn,
+ test,
+} from "bun:test";
+import { Tooltip } from "@base-ui/react/tooltip";
+import type { Message } from "@ag-ui/core";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { act, cleanup, fireEvent, render } from "@testing-library/react";
+import { ChatTranscript } from "@/components/channels/chat-transcript";
+import { TranscriptRail } from "@/components/channels/transcript-rail";
+import type { Turn } from "@/components/channels/transcript-turns";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * A rail beside the conversation with a mark per turn: hovering one previews the turn, choosing one
+ * goes there, drawing older pages first when the turn is not drawn yet.
+ */
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+afterAll(async () => {
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+const TURNS: Turn[] = [
+ { id: "u1", index: 0, prompt: "What changed?", reply: "Two things." },
+ { id: "u2", index: 2, prompt: "Why?", reply: "Because." },
+ { id: "u3", index: 4, prompt: "And now?", reply: "" },
+];
+
+function marks(container: HTMLElement): HTMLButtonElement[] {
+ return Array.from(
+ container.querySelectorAll<HTMLButtonElement>('[data-slot="rail-mark"]'),
+ );
+}
+
+test("a mark per turn, named by what the person sent, with the current one marked", () => {
+ const view = render(
+ <TranscriptRail active="u2" onJump={() => {}} turns={TURNS} />,
+ );
+
+ expect(
+ marks(view.container).map((mark) => mark.getAttribute("aria-label")),
+ ).toEqual(["What changed?", "Why?", "And now?"]);
+ expect(
+ marks(view.container).map((mark) => mark.getAttribute("aria-current")),
+ ).toEqual([null, "true", null]);
+});
+
+test("choosing a mark jumps to its turn", () => {
+ const onJump = mock((_turn: Turn) => {});
+ const view = render(
+ <TranscriptRail active="u3" onJump={onJump} turns={TURNS} />,
+ );
+
+ fireEvent.click(marks(view.container)[0] as HTMLButtonElement);
+
+ expect(onJump).toHaveBeenCalledWith(TURNS[0]);
+});
+
+test("a conversation of one turn has no rail", () => {
+ const view = render(
+ <TranscriptRail active="u1" onJump={() => {}} turns={TURNS.slice(0, 1)} />,
+ );
+
+ expect(view.container.querySelector("nav")).toBeNull();
+});
+
+function conversation(turns: number): Message[] {
+ return Array.from({ length: turns }, (_, index) => [
+ { id: `u${index}`, role: "user", content: `question ${index}` },
+ { id: `a${index}`, role: "assistant", content: `answer ${index}` },
+ ]).flat() as Message[];
+}
+
+function viewport(container: HTMLElement): HTMLElement {
+ return container.querySelector(
+ '[data-slot="message-scroller-viewport"]',
+ ) as HTMLElement;
+}
+
+test("jumping to a turn that is not drawn yet draws down to it and stops following", async () => {
+ const view = render(
+ <ChatTranscript messages={conversation(50)} restoring={false} />,
+ );
+ expect(view.container.querySelector('[data-message-id="u0"]')).toBeNull();
+ // Far from the end once the jump has moved the view up.
+ Object.defineProperty(viewport(view.container), "scrollHeight", {
+ configurable: true,
+ get: () => 5000,
+ });
+
+ await act(async () => {
+ fireEvent.click(marks(view.container)[0] as HTMLButtonElement);
+ await new Promise((resolve) => window.requestAnimationFrame(resolve));
+ });
+
+ expect(view.container.querySelector('[data-message-id="u0"]')).not.toBeNull();
+ expect(viewport(view.container).getAttribute("data-following")).toBe("false");
+});
+
+/*
+ * At the end, the highlighted mark is the last turn; choosing it moves nothing, so no scroll would
+ * ever pick following up again, and a streaming reply would grow below the fold.
+ */
+test("jumping to a turn that leaves the view at the end keeps following", async () => {
+ const view = render(
+ <ChatTranscript messages={conversation(3)} restoring={false} />,
+ );
+
+ await act(async () => {
+ fireEvent.click(marks(view.container).at(-1) as HTMLButtonElement);
+ await new Promise((resolve) => window.requestAnimationFrame(resolve));
+ });
+
+ expect(viewport(view.container).getAttribute("data-following")).toBe("true");
+});
+
+/*
+ * The transcript re-renders on every streamed chunk and rebuilds its turns each time. The rail
+ * must not redraw a mark per turn for it: only what a mark shows changing redraws it.
+ */
+test("the rail does not redraw for turns that are rebuilt but the same", () => {
+ const marksDrawn = spyOn(Tooltip, "Root");
+ const copy = () => TURNS.map((turn) => ({ ...turn }));
+ const onJump = () => {};
+ const view = render(
+ <TranscriptRail active="u3" onJump={onJump} turns={copy()} />,
+ );
+ const before = marksDrawn.mock.calls.length;
+ expect(before).toBe(TURNS.length);
+
+ view.rerender(<TranscriptRail active="u3" onJump={onJump} turns={copy()} />);
+ expect(marksDrawn.mock.calls.length).toBe(before);
+
+ const grown = copy();
+ grown[2] = { ...TURNS[2], reply: "Now this." } as Turn;
+ view.rerender(<TranscriptRail active="u3" onJump={onJump} turns={grown} />);
+ expect(marksDrawn.mock.calls.length).toBe(before + 1);
+ marksDrawn.mockRestore();
+});
diff --git a/app/tests/transcript-rerender.test.tsx b/app/tests/transcript-rerender.test.tsx
new file mode 100644
index 00000000..a268dd13
--- /dev/null
+++ b/app/tests/transcript-rerender.test.tsx
@@ -0,0 +1,203 @@
+import { afterAll, afterEach, beforeAll, expect, spyOn, test } from "bun:test";
+import type { Message } from "@ag-ui/core";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { cleanup, render } from "@testing-library/react";
+import {
+ ChatTranscript,
+ sameToolRow,
+} from "@/components/channels/chat-transcript";
+import * as toolActivity from "@/components/channels/tool-activity";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * While a reply streams, every token re-renders the transcript. Rows that have finished must not
+ * re-render with it: a tool group in history (and the markdown inside it) redrawn on every token is
+ * the cost that made long conversations stutter.
+ */
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+afterAll(async () => {
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+function user(id: string, text: string): Message {
+ return { id, role: "user", content: text };
+}
+
+function assistant(id: string, text: string): Message {
+ return { id, role: "assistant", content: text };
+}
+
+/* An assistant turn that searched twice: two adjacent tool calls, folded into one group row. */
+function searched(id: string): Message[] {
+ return [
+ {
+ id,
+ role: "assistant",
+ content: "",
+ toolCalls: [
+ {
+ id: `${id}-c1`,
+ type: "function",
+ function: { name: "web_search", arguments: '{"q":"one"}' },
+ },
+ {
+ id: `${id}-c2`,
+ type: "function",
+ function: { name: "web_search", arguments: '{"q":"two"}' },
+ },
+ ],
+ },
+ {
+ id: `${id}-r1`,
+ role: "tool",
+ toolCallId: `${id}-c1`,
+ content: "found one",
+ },
+ {
+ id: `${id}-r2`,
+ role: "tool",
+ toolCallId: `${id}-c2`,
+ content: "found two",
+ },
+ ] as Message[];
+}
+
+const step = (id: string, result?: string) => ({
+ kind: "tool" as const,
+ id,
+ toolCall: {
+ id,
+ type: "function" as const,
+ function: { name: "web_search", arguments: '{"q":"x"}' },
+ },
+ result,
+});
+
+test("a rebuilt but identical tool row is the same row", () => {
+ const props = {
+ id: "group:a",
+ active: false,
+ latest: false,
+ spokeAfter: false,
+ };
+ expect(
+ sameToolRow(
+ { ...props, steps: [step("a", "done")] },
+ { ...props, steps: [step("a", "done")] },
+ ),
+ ).toBe(true);
+ expect(
+ sameToolRow(
+ { ...props, steps: [step("a")] },
+ { ...props, steps: [step("a", "done")] },
+ ),
+ ).toBe(false);
+ expect(
+ sameToolRow(
+ { ...props, steps: [step("a", "done")] },
+ { ...props, steps: [step("a", "done"), step("b")] },
+ ),
+ ).toBe(false);
+ expect(
+ sameToolRow(
+ { ...props, steps: [step("a", "done")] },
+ { ...props, active: true, steps: [step("a", "done")] },
+ ),
+ ).toBe(false);
+ expect(
+ sameToolRow(
+ { ...props, steps: [step("a", "done")] },
+ { ...props, spokeAfter: true, steps: [step("a", "done")] },
+ ),
+ ).toBe(false);
+});
+
+test("a finished tool group does not re-render while a reply streams", () => {
+ const renders = spyOn(toolActivity, "ToolActivity");
+ const history = [user("u1", "look it up"), ...searched("a1")];
+ let reply = "Here";
+ const client = new QueryClient();
+ const view = render(
+ <ChatTranscript
+ busy
+ messages={[...history, assistant("a2", reply)]}
+ restoring={false}
+ />,
+ {
+ wrapper: ({ children }) => (
+ <QueryClientProvider client={client}>{children}</QueryClientProvider>
+ ),
+ },
+ );
+ const before = renders.mock.calls.length;
+ expect(before).toBeGreaterThan(0);
+
+ for (let token = 0; token < 10; token++) {
+ reply += ` word${token}`;
+ view.rerender(
+ <ChatTranscript
+ busy
+ messages={[...history, assistant("a2", reply)]}
+ restoring={false}
+ />,
+ );
+ }
+
+ expect(renders.mock.calls.length).toBe(before);
+ renders.mockRestore();
+});
+
+/*
+ * The agent client appends a call's argument chunks to the same `toolCall` object it already
+ * handed over. A row that compared the arguments it was given with themselves never saw them grow,
+ * so a running search showed no query until its result arrived.
+ */
+test("a running tool row redraws as its arguments stream in place", () => {
+ const renders = spyOn(toolActivity, "ToolActivity");
+ const [call, ...rest] = searched("a1");
+ const message = call as Message & {
+ toolCalls: { function: { arguments: string } }[];
+ };
+ const streaming = message.toolCalls[1];
+ if (!streaming) throw new Error("the fixture has two calls");
+ streaming.function.arguments = "";
+ const results = rest.slice(0, 1);
+ const client = new QueryClient();
+ const view = render(
+ <ChatTranscript
+ busy
+ messages={[user("u1", "look it up"), message, ...results]}
+ restoring={false}
+ />,
+ {
+ wrapper: ({ children }) => (
+ <QueryClientProvider client={client}>{children}</QueryClientProvider>
+ ),
+ },
+ );
+
+ const before = renders.mock.calls.length;
+ streaming.function.arguments = '{"q":"two"}';
+ view.rerender(
+ <ChatTranscript
+ busy
+ messages={[user("u1", "look it up"), message, ...results]}
+ restoring={false}
+ />,
+ );
+
+ expect(renders.mock.calls.length).toBeGreaterThan(before);
+ const last = renders.mock.calls.at(-1)?.[0];
+ expect(last?.group.steps[1]?.toolCall.function.arguments).toBe('{"q":"two"}');
+ renders.mockRestore();
+});
diff --git a/app/tests/transcript-stream.test.tsx b/app/tests/transcript-stream.test.tsx
new file mode 100644
index 00000000..3e860017
--- /dev/null
+++ b/app/tests/transcript-stream.test.tsx
@@ -0,0 +1,109 @@
+import { afterAll, afterEach, beforeAll, expect, test } from "bun:test";
+import type { Message } from "@ag-ui/core";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { act, cleanup, render } from "@testing-library/react";
+import {
+ ChatTranscript,
+ messageMode,
+} from "@/components/channels/chat-transcript";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * A reply that arrives while the conversation is open is revealed at a steady pace; history is
+ * drawn whole, as finished text.
+ */
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+afterAll(async () => {
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+function user(id: string, text: string): Message {
+ return { id, role: "user", content: text };
+}
+
+function assistant(id: string, text: string): Message {
+ return { id, role: "assistant", content: text };
+}
+
+const LONG = Array.from({ length: 60 }, (_, index) => `word${index}`).join(" ");
+
+function frames(count: number) {
+ return act(async () => {
+ for (let index = 0; index < count; index++) {
+ await new Promise((resolve) => window.requestAnimationFrame(resolve));
+ }
+ });
+}
+
+test("history is drawn static, and anything live or still streaming is not", () => {
+ expect(messageMode(false, false)).toBe("static");
+ expect(messageMode(true, false)).toBe("streaming");
+ expect(messageMode(false, true)).toBe("streaming");
+});
+
+test("a history message is drawn whole", () => {
+ const view = render(
+ <ChatTranscript
+ messages={[user("u1", "question"), assistant("a1", LONG)]}
+ restoring={false}
+ />,
+ );
+
+ expect(view.container.textContent).toContain(LONG);
+});
+
+test("a live reply starts from less than it has and grows to all of it", async () => {
+ const history = [user("u1", "question")];
+ const view = render(
+ <ChatTranscript busy messages={history} restoring={false} />,
+ );
+
+ view.rerender(
+ <ChatTranscript
+ busy
+ messages={[...history, assistant("a1", LONG)]}
+ restoring={false}
+ />,
+ );
+ expect(view.container.textContent).not.toContain("word59");
+
+ view.rerender(
+ <ChatTranscript
+ busy={false}
+ messages={[...history, assistant("a1", LONG)]}
+ restoring={false}
+ />,
+ );
+ await frames(40);
+
+ expect(view.container.textContent).toContain(LONG);
+});
+
+/* The run goes on after the reply's last word (drawing an interface, say); that word still shows. */
+test("a reply's last word shows while the run is still busy", async () => {
+ const history = [user("u1", "question")];
+ const text = "here is a chart of your sales:";
+ const view = render(
+ <ChatTranscript busy messages={history} restoring={false} />,
+ );
+ view.rerender(
+ <ChatTranscript
+ busy
+ messages={[...history, assistant("a1", text)]}
+ restoring={false}
+ />,
+ );
+
+ await frames(40);
+
+ expect(view.container.textContent).toContain("sales:");
+});
diff --git a/app/tests/transcript-turns.test.ts b/app/tests/transcript-turns.test.ts
new file mode 100644
index 00000000..48ace571
--- /dev/null
+++ b/app/tests/transcript-turns.test.ts
@@ -0,0 +1,133 @@
+import { expect, test } from "bun:test";
+import { frameFiring } from "@openbot/shared/routine-firing";
+import type { TranscriptItem } from "@/components/channels/tool-activity";
+import { currentTurn, turnsOf } from "@/components/channels/transcript-turns";
+
+/**
+ * The rail beside a conversation has one mark per turn: something the person sent, and what the Bot
+ * said back. Each mark knows the row it jumps to and the words its preview shows.
+ */
+
+const said = (
+ id: string,
+ role: "user" | "assistant",
+ text: string,
+): TranscriptItem => ({ kind: "text", id, role, text });
+
+const files = (id: string, count: number): TranscriptItem => ({
+ kind: "attachments",
+ id,
+ attachments: Array.from({ length: count }, (_, index) => ({
+ id: `${id}-${index}`,
+ attachmentId: `${id}-${index}`,
+ url: `/files/${index}`,
+ modality: "image" as const,
+ })),
+});
+
+const searched = (id: string): TranscriptItem => ({
+ kind: "tool",
+ id,
+ toolCall: {
+ id,
+ type: "function",
+ function: { name: "web_search", arguments: "{}" },
+ },
+ result: "found",
+});
+
+test("one turn per message the person sent, with the first thing the Bot said back", () => {
+ const turns = turnsOf([
+ said("u1", "user", "What changed?"),
+ searched("t1"),
+ said("a1", "assistant", "Two things changed."),
+ said("a1b", "assistant", "And a third."),
+ said("u2", "user", "Why?"),
+ said("a2", "assistant", "Because."),
+ ]);
+
+ expect(turns).toEqual([
+ {
+ id: "u1",
+ index: 0,
+ prompt: "What changed?",
+ reply: "Two things changed.",
+ },
+ { id: "u2", index: 4, prompt: "Why?", reply: "Because." },
+ ]);
+});
+
+test("files sent with a caption are one turn, and files alone are named by count", () => {
+ const turns = turnsOf([
+ files("f1", 2),
+ said("u1", "user", "Look at these"),
+ said("a1", "assistant", "Seen."),
+ files("f2", 1),
+ said("a2", "assistant", "A chart."),
+ ]);
+
+ expect(turns.map(({ id, prompt }) => ({ id, prompt }))).toEqual([
+ { id: "f1", prompt: "Look at these" },
+ { id: "f2", prompt: "1 file" },
+ ]);
+});
+
+test("a routine firing is not a turn the person took", () => {
+ const firing = frameFiring("Send the daily digest.");
+ const turns = turnsOf([
+ said("u1", "user", "Hello"),
+ said("a1", "assistant", "Hi"),
+ said("r1", "user", firing),
+ said("a2", "assistant", "Here is the digest."),
+ ]);
+
+ expect(turns.map((turn) => turn.id)).toEqual(["u1"]);
+});
+
+test("a turn still waiting for its reply has none", () => {
+ expect(turnsOf([said("u1", "user", "Hello")])).toEqual([
+ { id: "u1", index: 0, prompt: "Hello", reply: "" },
+ ]);
+});
+
+test("markdown is read as plain words", () => {
+ const [turn] = turnsOf([
+ said("u1", "user", "Hi"),
+ said(
+ "a1",
+ "assistant",
+ "## Summary\n\n**Two** things, see [the doc](https://x.y).",
+ ),
+ ]);
+
+ expect(turn?.reply).toBe("Summary Two things, see the doc.");
+});
+
+/*
+ * Which turn is being read: the last to start above a third of the way down the view — except at the
+ * end of the conversation, where a short last turn starts below that line and is still the one on
+ * screen.
+ */
+test("the turn being read is the last to start above the reading line", () => {
+ const rows = [
+ { id: "u1", top: -900 },
+ { id: "u2", top: 120 },
+ { id: "u3", top: 700 },
+ ];
+ expect(currentTurn(rows, 300, false)).toBe("u2");
+ expect(currentTurn(rows, 50, false)).toBe("u1");
+});
+
+test("at the end of the conversation the last turn is the one being read", () => {
+ const rows = [
+ { id: "u1", top: -900 },
+ { id: "u2", top: 120 },
+ { id: "u3", top: 700 },
+ ];
+ expect(currentTurn(rows, 300, true)).toBe("u3");
+});
+
+test("with no turn above the line, the first one drawn is being read", () => {
+ expect(currentTurn([{ id: "u1", top: 500 }], 300, false)).toBe("u1");
+ expect(currentTurn([], 300, false)).toBeNull();
+});
diff --git a/app/tests/voice-archive-pending.test.tsx b/app/tests/voice-archive-pending.test.tsx
new file mode 100644
index 00000000..13bcc2bd
--- /dev/null
+++ b/app/tests/voice-archive-pending.test.tsx
@@ -0,0 +1,74 @@
+import {
+ afterAll,
+ afterEach,
+ beforeAll,
+ expect,
+ mock,
+ spyOn,
+ test,
+} from "bun:test";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { cleanup, renderHook, waitFor } from "@testing-library/react";
+import { useVoiceArchive } from "../src/lib/voice/archive";
+import { queryClient } from "../src/query-client";
+import { settleReactWork } from "./settle-react-work";
+
+/**
+ * A channel's voice chats are part of its history: the transcript is not shown until they are in,
+ * so it never draws the conversation and then splices a call card into it. `pending` is what the
+ * channel waits on — and it must end on a failed load too, or the placeholder would stay up for
+ * good over a conversation that is perfectly readable without its calls.
+ */
+
+beforeAll(() => {
+ GlobalRegistrator.register({ url: "http://localhost/" });
+});
+
+afterEach(() => {
+ cleanup();
+ mock.restore();
+ queryClient.clear();
+});
+
+afterAll(async () => {
+ await settleReactWork();
+ GlobalRegistrator.unregister();
+});
+
+function answerFetch(answer: () => Promise<Response>) {
+ spyOn(globalThis, "fetch").mockImplementation(
+ Object.assign(answer, { preconnect: globalThis.fetch.preconnect }),
+ );
+}
+
+test("pending while saved voice chats load", () => {
+ answerFetch(() => new Promise<Response>(() => {}));
+
+ const { result } = renderHook(() => useVoiceArchive("channel-1"));
+
+ expect(result.current.pending).toBe(true);
+});
+
+test("not pending once loaded", async () => {
+ answerFetch(async () =>
+ Response.json({ sessions: [], nextCursor: null }, { status: 200 }),
+ );
+
+ const { result } = renderHook(() => useVoiceArchive("channel-1"));
+
+ await waitFor(() => expect(result.current.pending).toBe(false));
+ expect(result.current.error).toBeNull();
+});
+
+test("not pending after a failed load", async () => {
+ answerFetch(async () =>
+ Response.json({ error: "Down for maintenance." }, { status: 500 }),
+ );
+
+ const { result } = renderHook(() => useVoiceArchive("channel-1"));
+
+ await waitFor(() => expect(result.current.pending).toBe(false), {
+ timeout: 5000,
+ });
+ expect(result.current.error).not.toBeNull();
+});
diff --git a/app/tests/voice-archive.test.ts b/app/tests/voice-archive.test.ts
index 8af6e1ed..d966b490 100644
--- a/app/tests/voice-archive.test.ts
+++ b/app/tests/voice-archive.test.ts
@@ -158,3 +158,18 @@ test("earlier calls' context is cut between characters", () => {
expect(context.isWellFormed()).toBe(true);
expect(context).toBe(`${emoji.repeat(5999)}.`);
});
+
+/*
+ * The transcript skips re-rendering a voice-chat card whose message object is the same one it drew
+ * last time. Building a new object for every call on every render meant every card re-rendered on
+ * every token of a reply streaming below it.
+ */
+test("the same call gives the same card message on every render", () => {
+ const messages = [{ id: "before", role: "user" as const, content: "Before" }];
+ const calls = [call("first", "before")];
+
+ const once = withVoiceChats(messages, calls);
+ const again = withVoiceChats([...messages], calls);
+
+ expect(again[1]).toBe(once[1]);
+});