@data-club/ai-hub 0.0.1

package/src/components/MessageList/index.tsx

@@ -0,0 +1,753 @@
+/**
+ * `<MessageList />` — the scrollable list of message bubbles in the
+ * active session.
+ *
+ * Step 10 layers in:
+ *
+ * - `--system` / `--tool` / `--failed` bubble modifiers (Step 9 shipped
+ *   `--user` / `--assistant`).
+ * - The `customMessageActions` slot — Tier-2 / Tier-3 wrappers render
+ *   their own action bar inside every assistant bubble (e.g. 👍 / 👎).
+ * - The `customMessageBubble` slot — Tier-3 escape hatch that replaces
+ *   the entire bubble for a message.
+ * - The `<TpmBanner />` — sits above the streaming bubble during a
+ *   `waiting_provider` phase + the brief resumed-flash.
+ * - The `<ScrollToPresentButton />` — appears when the user has scrolled
+ *   away from the bottom during a running turn (auto-scroll is
+ *   inhibited while they're scrolled up).
+ * - Per-row Retry button on the failed-turn `--failed` assistant bubble.
+ *
+ * Server toggles (§8.4) gate via the resolved prop stack the monolith
+ * passes in:
+ *
+ * - `systemMessagesVisible` — when false, `system` and `tool`-role
+ *   messages are filtered out of the list.
+ * - `tpmNoticeVisible` — when false, `<TpmBanner />` is suppressed.
+ * - `scrollToPresentVisible` — when false, the scroll-to-present
+ *   button is suppressed.
+ *
+ * Exported under `AIHub.MessageList`.
+ *
+ * @see SPECIFICATIONS.md §7.1, §8.4, §10.4
+ * @see ui-sketches/03-chat.md — message_bubble + system_notice
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+
+import {
+  resolveAIHubTexts,
+  type AIHubTexts,
+  type DeepPartial,
+} from "../../auth/texts.js";
+import { useAIHub } from "../../context/useAIHub.js";
+import { chatAffordances } from "../../state/affordances.js";
+import type {
+  AIHubMessage,
+  AIHubMessageActionRenderer,
+  AIHubMessageBubbleRenderer,
+} from "../../types.js";
+
+import { CacheBadge } from "../CacheBadge/index.js";
+import { MarkdownRenderer } from "../MarkdownRenderer/index.js";
+import { ReasoningView } from "../ReasoningView/index.js";
+import { ScrollToPresentButton } from "../ScrollToPresentButton/index.js";
+import { ToolCallView } from "../ToolCallView/index.js";
+import { TpmBanner } from "../TpmBanner/index.js";
+
+/** Distance from bottom (in pixels) that still counts as "at the latest". */
+const BOTTOM_EPSILON_PX = 32;
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Block-expansion stable IDs                                                */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Stable id for the reasoning sub-block of a *historical* assistant
+ * message. Used as the controlled-mode key into the user-expanded
+ * accordion state owned by `<MessageList />`.
+ */
+function reasoningBlockId(messageId: string): string {
+  return `reasoning:${messageId}`;
+}
+
+/** Stable id for the reasoning sub-block of the *currently-streaming* bubble. */
+const STREAMING_REASONING_BLOCK_ID = "reasoning:streaming";
+
+/**
+ * Stable id for a tool-call card. The accordion key is namespaced by the
+ * **owning bubble** (`tool:<parent>:<tool_call_id>`) — empirically Letta
+ * has been observed to reuse `tool_call_id` values across logical
+ * messages within a single multi-step run, and even when it doesn't, the
+ * historical projector's per-step attribution could surface a record in
+ * two bubbles if it misfires. Without the namespace, two cards sharing
+ * an id would expand together because the accordion state lives in
+ * `<MessageList />` (cross-bubble). The namespace makes each bubble's
+ * card an independent accordion slot regardless of upstream id quirks.
+ *
+ * Pass `"streaming"` as `parentId` for the currently-streaming bubble's
+ * tool cards; pass the historical assistant message's id otherwise.
+ */
+function toolCallBlockId(parentId: string, toolCallId: string): string {
+  return `tool:${parentId}:${toolCallId}`;
+}
+
+/**
+ * BEM class names emitted by `<MessageList />`.
+ */
+export interface MessageListClassNames {
+  /**
+   * Outer wrapper. NOT the scroll container — that's `root` (a child of
+   * this element). The wrapper exists so `<ScrollToPresentButton />`
+   * can sit as a sibling of the scroll container and stay anchored to
+   * the visible chat area as the user scrolls.
+   */
+  wrapper: string;
+  /** Scroll container — the actual element that overflows + scrolls. */
+  root: string;
+  /** Inner block; targets `max-width` for readable line lengths. */
+  inner: string;
+  /** Empty-state placeholder (zero messages in the active session). */
+  empty: string;
+  /** Loading state. */
+  loading: string;
+  /** Placeholder when no session is selected. */
+  noSession: string;
+  /**
+   * Error banner shown above the streaming-assistant placeholder when
+   * the active turn failed without producing any assistant output.
+   */
+  errorBanner: string;
+  /** Per-bubble base class. */
+  bubble: string;
+  /** Bubble modifier — `--user`. */
+  bubbleUser: string;
+  /** Bubble modifier — `--assistant`. */
+  bubbleAssistant: string;
+  /** Bubble modifier — `--system`. */
+  bubbleSystem: string;
+  /** Bubble modifier — `--tool`. */
+  bubbleTool: string;
+  /** Bubble modifier — `--failed` (applied to the assistant bubble of a failed turn). */
+  bubbleFailed: string;
+  /** Bubble modifier — `--cancelled` (for the "Stopped" stamp). */
+  bubbleCancelled: string;
+  /** Wrapper for the role label inside the bubble. */
+  bubbleRole: string;
+  /** The text body inside the bubble. */
+  bubbleBody: string;
+  /** The action bar inside the bubble (slot for custom actions). */
+  bubbleActions: string;
+  /** The retry-button on `--failed` bubbles. */
+  bubbleRetryButton: string;
+  /** The "Stopped" stamp on `--cancelled` bubbles. */
+  bubbleCancelledStamp: string;
+  /** Streaming caret while a turn is in flight. */
+  bubbleCaret: string;
+}
+
+const DEFAULT_CLASS_NAMES: MessageListClassNames = Object.freeze({
+  wrapper: "data-club-ai-hub__messages-wrapper",
+  root: "data-club-ai-hub__messages",
+  inner: "data-club-ai-hub__messages__inner",
+  empty: "data-club-ai-hub__messages__empty",
+  loading: "data-club-ai-hub__messages__loading",
+  noSession: "data-club-ai-hub__messages__no-session",
+  errorBanner: "data-club-ai-hub__messages__error",
+  bubble: "data-club-ai-hub__message-bubble",
+  bubbleUser: "data-club-ai-hub__message-bubble--user",
+  bubbleAssistant: "data-club-ai-hub__message-bubble--assistant",
+  bubbleSystem: "data-club-ai-hub__message-bubble--system",
+  bubbleTool: "data-club-ai-hub__message-bubble--tool",
+  bubbleFailed: "data-club-ai-hub__message-bubble--failed",
+  bubbleCancelled: "data-club-ai-hub__message-bubble--cancelled",
+  bubbleRole: "data-club-ai-hub__message-bubble__role",
+  bubbleBody: "data-club-ai-hub__message-bubble__body",
+  bubbleActions: "data-club-ai-hub__message-bubble__actions",
+  bubbleRetryButton: "data-club-ai-hub__message-bubble__retry",
+  bubbleCancelledStamp: "data-club-ai-hub__message-bubble__cancelled-stamp",
+  bubbleCaret: "data-club-ai-hub__message-bubble__caret",
+}) as MessageListClassNames;
+
+/**
+ * Props for `<MessageList />`.
+ */
+export interface MessageListProps {
+  /**
+   * Show system / tool-role bubbles. Default true. When false, those
+   * messages are filtered out (the user-facing list shows user +
+   * assistant only).
+   */
+  showSystemMessages?: boolean;
+  /**
+   * Render `<TpmBanner />` during `waiting_provider` and on
+   * tpm_exhausted. Default true. The monolith passes the resolved
+   * §8.4 flag here.
+   */
+  showTpmNotice?: boolean;
+  /**
+   * Render `<ReasoningView />` inside assistant bubbles when the
+   * message carries `reasoning`. Default true. Monolith forwards the
+   * resolved `reasoning_visible` flag.
+   */
+  showReasoning?: boolean;
+  /**
+   * Render `<ToolCallView />` cards inside assistant bubbles when the
+   * message carries `tool_calls`. Default true. Monolith forwards the
+   * resolved `tool_calls_visible` flag.
+   */
+  showToolCalls?: boolean;
+  /**
+   * Render `<ScrollToPresentButton />` when the user has scrolled away
+   * from the bottom of the list during a running turn. Default true.
+   */
+  showScrollToPresentButton?: boolean;
+  /**
+   * Render a "Retry" button on `--failed` assistant bubbles. Default
+   * true. When false the bubble still renders with the failed modifier
+   * but no action is offered.
+   */
+  showRetryButton?: boolean;
+  /**
+   * Tier 2 / Tier 3 slot — render the action bar of every assistant
+   * message bubble. The renderer receives the full `AIHubMessage` and
+   * returns React-renderable content (or null to suppress the bar
+   * for that message).
+   */
+  renderMessageActions?: AIHubMessageActionRenderer;
+  /**
+   * Tier 3 escape hatch — fully replace the message bubble for any
+   * message. The renderer is wrapped in the list's flex container; the
+   * caller is responsible for choosing variant modifiers.
+   */
+  renderMessageBubble?: AIHubMessageBubbleRenderer;
+  /** Extra class merged onto the root. */
+  className?: string;
+  /** Per-element class overrides. */
+  classNames?: Partial<MessageListClassNames>;
+  /** Wrapper-supplied i18n. */
+  texts?: DeepPartial<AIHubTexts>;
+}
+
+/**
+ * Renders the message list.
+ *
+ * @param props - see `MessageListProps`.
+ * @returns the rendered list.
+ */
+export function MessageList(props: MessageListProps): ReactNode {
+  const {
+    messages,
+    messagesLoading,
+    activeSessionId,
+    streamingAssistantText,
+    streamingReasoning,
+    streamingToolCalls,
+    lastTurnError,
+    state,
+    sendMessage,
+  } = useAIHub();
+  const texts = resolveAIHubTexts(props.texts);
+  const cls = { ...DEFAULT_CLASS_NAMES, ...(props.classNames ?? {}) };
+  const showSystemMessages = props.showSystemMessages ?? true;
+  const showTpmNotice = props.showTpmNotice ?? true;
+  const showScrollToPresent = props.showScrollToPresentButton ?? true;
+  const showRetryButton = props.showRetryButton ?? true;
+  const showReasoning = props.showReasoning ?? true;
+  const showToolCalls = props.showToolCalls ?? true;
+  const rootClass = props.className
+    ? `${cls.root} ${props.className}`
+    : cls.root;
+  const affordances = chatAffordances(state);
+
+  // Block-expansion accordion (reasoning + tool-call blocks). At rest,
+  // at most one block in the entire conversation is user-expanded —
+  // clicking a second block collapses the first. During generation,
+  // the currently-streaming block is additionally auto-expanded, and
+  // the user-accordion ignores it (so up to TWO blocks can be visible:
+  // the auto-expanded streaming one + one user-expanded). When
+  // generation finishes, the streaming auto-expand falls away and the
+  // user's manual accordion remains.
+  const [userExpandedBlockId, setUserExpandedBlockId] = useState<string | null>(null);
+  // The currently-streaming block (reasoning while phase ==
+  // model_reasoning; the most recent still-running tool call while
+  // phase == model_tool_input or tool_executing). Null otherwise.
+  const currentlyStreamingBlockId = useMemo<string | null>(() => {
+    if (state.status !== "running") return null;
+    if (state.phase === "model_reasoning") return STREAMING_REASONING_BLOCK_ID;
+    if (state.phase === "model_tool_input" || state.phase === "tool_executing") {
+      // Walk newest-first; "running" = not yet finished. The translator
+      // computes `status === "running"` when neither output nor error is
+      // set yet, but that derivation happens in the streaming-bubble
+      // render below — here we mirror it.
+      for (let i = streamingToolCalls.length - 1; i >= 0; i--) {
+        const c = streamingToolCalls[i];
+        if (!c) continue;
+        const isRunning = c.status !== "error" && c.output == null;
+        if (isRunning) return toolCallBlockId("streaming", c.tool_call_id);
+      }
+    }
+    return null;
+  }, [state.status, state.phase, streamingToolCalls]);
+  // `expanded` resolver: auto-expand wins (it's the visible-during-stream
+  // contract); user-accordion is the fallback.
+  const isBlockExpanded = useCallback(
+    (blockId: string): boolean =>
+      blockId === currentlyStreamingBlockId || blockId === userExpandedBlockId,
+    [currentlyStreamingBlockId, userExpandedBlockId],
+  );
+  // Toggle: clicking the streaming-locked block is a no-op (the rule is
+  // "the latest in-progress block is always visible"). For every other
+  // block, the accordion replaces: clicking an already-user-expanded
+  // block collapses it to null; clicking any other expands it.
+  const handleToggleBlock = useCallback(
+    (blockId: string): void => {
+      if (blockId === currentlyStreamingBlockId) return;
+      setUserExpandedBlockId((current) => (current === blockId ? null : blockId));
+    },
+    [currentlyStreamingBlockId],
+  );
+
+  // Filter messages: assistant + user always, system + tool gated by
+  // showSystemMessages. Dedupe by id defensively even though the
+  // provider already does it on its own. Empty/whitespace-only messages
+  // are skipped — they appear when the messages-list route applies an
+  // empty `user_override` row (the rendered chip would otherwise be a
+  // tiny empty bubble), or when Letta's `<memory_metadata>`-stripped
+  // system message leaves nothing behind. Assistant bubbles keep
+  // rendering when they carry `reasoning` or `tool_calls` even with
+  // empty text, since those affordances are the message body.
+  const visibleMessages = useMemo(() => {
+    const seen = new Set<string>();
+    const out: AIHubMessage[] = [];
+    for (const msg of messages) {
+      if (seen.has(msg.id)) continue;
+      if ((msg.role === "system" || msg.role === "tool") && !showSystemMessages) {
+        continue;
+      }
+      if (isMessageRenderEmpty(msg)) continue;
+      seen.add(msg.id);
+      out.push(msg);
+    }
+    return out;
+  }, [messages, showSystemMessages]);
+
+  // Track whether the user is currently at-the-bottom (within
+  // BOTTOM_EPSILON_PX). When at-bottom, new content auto-scrolls. When
+  // scrolled up, auto-scroll is suppressed and the
+  // ScrollToPresentButton renders. Recomputed on every scroll event
+  // through the scroll container.
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  const [atBottom, setAtBottom] = useState(true);
+
+  const checkAtBottom = useCallback((): boolean => {
+    const el = scrollRef.current;
+    if (!el) return true;
+    return el.scrollHeight - el.scrollTop - el.clientHeight < BOTTOM_EPSILON_PX;
+  }, []);
+
+  function handleScroll(): void {
+    setAtBottom(checkAtBottom());
+  }
+
+  // Auto-scroll only when the user is at-the-bottom. On session change
+  // we always scroll to the bottom (loading a new session shouldn't
+  // strand the user mid-history).
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    if (atBottom) {
+      el.scrollTop = el.scrollHeight;
+    }
+  }, [messages, streamingAssistantText, atBottom]);
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+    setAtBottom(true);
+  }, [activeSessionId]);
+
+  const handleScrollToPresent = useCallback((): void => {
+    const el = scrollRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+    setAtBottom(true);
+  }, []);
+
+  const handleRetry = useCallback((): void => {
+    // Find the last user message in the visible list (the failed
+    // turn's input). Sending it re-issues the turn.
+    for (let i = visibleMessages.length - 1; i >= 0; i--) {
+      const msg = visibleMessages[i];
+      if (msg && msg.role === "user") {
+        void sendMessage(msg.content);
+        return;
+      }
+    }
+  }, [visibleMessages, sendMessage]);
+
+  if (!activeSessionId) {
+    return (
+      <div className={cls.wrapper} data-testid="message-list-wrapper">
+        <div className={rootClass} data-testid="message-list">
+          <div className={cls.noSession} data-testid="message-list-no-session">
+            {texts.chat.noActiveSessionHint}
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={cls.wrapper} data-testid="message-list-wrapper">
+      <div
+        className={rootClass}
+        ref={scrollRef}
+        onScroll={handleScroll}
+        data-testid="message-list"
+      >
+        <div className={cls.inner} aria-live="polite">
+          {showTpmNotice ? (
+          <TpmBanner
+            onRetry={handleRetry}
+            {...(props.texts !== undefined ? { texts: props.texts } : {})}
+          />
+        ) : null}
+        {messagesLoading ? (
+          <p className={cls.loading} data-testid="message-list-loading">
+            {texts.chat.sessionsLoading}
+          </p>
+        ) : null}
+        {!messagesLoading &&
+        visibleMessages.length === 0 &&
+        streamingAssistantText === null &&
+        lastTurnError === null ? (
+          <p className={cls.empty} data-testid="message-list-empty">
+            {texts.chat.emptyConversationHint}
+          </p>
+        ) : null}
+        {visibleMessages.map((msg) =>
+          props.renderMessageBubble ? (
+            // The Tier-3 escape hatch returns arbitrary content; we
+            // wrap with a stable React key.
+            <div key={msg.id} data-testid="message-bubble-custom">
+              {props.renderMessageBubble(msg) as ReactNode}
+            </div>
+          ) : (
+            <MessageBubble
+              key={msg.id}
+              message={msg}
+              classNames={cls}
+              isFailedAssistant={
+                state.status === "failed" &&
+                msg.role === "assistant" &&
+                isLastAssistant(visibleMessages, msg)
+              }
+              isCancelledAssistant={
+                state.status === "cancelled" &&
+                msg.role === "assistant" &&
+                isLastAssistant(visibleMessages, msg)
+              }
+              showRetryButton={showRetryButton}
+              showReasoning={showReasoning}
+              showToolCalls={showToolCalls}
+              retryLabel={texts.chat.retryFailedButton}
+              failedLabel={texts.chat.streamFailedText}
+              cancelledStampLabel={texts.chat.cancelledStampText}
+              onRetry={handleRetry}
+              isBlockExpanded={isBlockExpanded}
+              onToggleBlock={handleToggleBlock}
+              {...(props.texts !== undefined ? { texts: props.texts } : {})}
+              {...(props.renderMessageActions !== undefined
+                ? { renderMessageActions: props.renderMessageActions }
+                : {})}
+            />
+          ),
+        )}
+        {lastTurnError !== null && state.status === "failed" ? (
+          <div
+            className={`${cls.bubble} ${cls.bubbleAssistant} ${cls.bubbleFailed}`}
+            data-testid="message-bubble-failed-error"
+            data-role="assistant"
+          >
+            <span className={cls.bubbleBody}>
+              {texts.chat.streamFailedText}
+            </span>
+            {showRetryButton ? (
+              <button
+                type="button"
+                className={cls.bubbleRetryButton}
+                onClick={handleRetry}
+                data-testid="message-list-retry"
+              >
+                {texts.chat.retryFailedButton}
+              </button>
+            ) : null}
+          </div>
+        ) : lastTurnError !== null ? (
+          <div
+            className={cls.errorBanner}
+            data-testid="message-list-error"
+            role="alert"
+          >
+            {lastTurnError}
+          </div>
+        ) : null}
+        {streamingAssistantText !== null ||
+        (streamingReasoning !== null && showReasoning) ||
+        (streamingToolCalls.length > 0 && showToolCalls) ? (
+          <div
+            className={`${cls.bubble} ${cls.bubbleAssistant}`}
+            data-testid="message-bubble"
+            data-role="assistant"
+            data-streaming="true"
+          >
+            {streamingReasoning !== null && showReasoning ? (
+              <ReasoningView
+                content={streamingReasoning}
+                streaming={state.phase === "model_reasoning"}
+                expanded={isBlockExpanded(STREAMING_REASONING_BLOCK_ID)}
+                onToggle={() => handleToggleBlock(STREAMING_REASONING_BLOCK_ID)}
+                {...(props.texts !== undefined ? { texts: props.texts } : {})}
+              />
+            ) : null}
+            {showToolCalls
+              ? streamingToolCalls.map((call) => {
+                  const blockId = toolCallBlockId("streaming", call.tool_call_id);
+                  return (
+                    <ToolCallView
+                      key={call.tool_call_id}
+                      toolName={call.tool_name}
+                      status={
+                        call.status === "error"
+                          ? "error"
+                          : call.output != null
+                            ? "done"
+                            : "running"
+                      }
+                      input={call.input}
+                      expanded={isBlockExpanded(blockId)}
+                      onToggle={() => handleToggleBlock(blockId)}
+                      {...(call.output != null ? { output: call.output } : {})}
+                      {...(call.error != null ? { error: call.error } : {})}
+                      {...(props.texts !== undefined ? { texts: props.texts } : {})}
+                    />
+                  );
+                })
+              : null}
+            {streamingAssistantText !== null ? (
+              <span className={cls.bubbleBody}>
+                <MarkdownRenderer
+                  content={streamingAssistantText.replace(/^\s+|\s+$/g, "")}
+                />
+                {affordances.streamingDots ? (
+                  <span className={cls.bubbleCaret} aria-hidden="true" />
+                ) : null}
+              </span>
+            ) : null}
+          </div>
+        ) : null}
+      </div>
+      </div>
+      {showScrollToPresent ? (
+        <ScrollToPresentButton
+          visible={affordances.scrollToPresentVisible && !atBottom}
+          onClick={handleScrollToPresent}
+          {...(props.texts !== undefined ? { texts: props.texts } : {})}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * Returns true when `msg` is the last assistant-role entry in `list`.
+ * Used to scope the failed/cancelled modifiers to the latest assistant
+ * turn only (mid-history assistant messages are not retroactively
+ * failed when a *new* turn fails).
+ */
+function isLastAssistant(
+  list: ReadonlyArray<AIHubMessage>,
+  msg: AIHubMessage,
+): boolean {
+  for (let i = list.length - 1; i >= 0; i--) {
+    const item = list[i];
+    if (!item) continue;
+    if (item.role !== "assistant") continue;
+    return item.id === msg.id;
+  }
+  return false;
+}
+
+/**
+ * True when `msg` has nothing meaningful to render — its `content` is
+ * empty or whitespace-only AND it carries no `reasoning` text or
+ * `tool_calls`. Used by the visibility filter so messages overridden to
+ * empty (e.g. an empty `user_override` row applied to the persisted
+ * `system_message`, or Letta's `<memory_metadata>`-stripped system row
+ * after the strip leaves the slot empty) don't render as tiny empty
+ * bubbles.
+ *
+ * Assistant bubbles with `reasoning` or `tool_calls` are NEVER empty for
+ * this purpose — those affordances are the body. A regular text-only
+ * assistant message with whitespace content is still hidden.
+ */
+function isMessageRenderEmpty(msg: AIHubMessage): boolean {
+  const text = (msg.content ?? "").trim();
+  if (text !== "") return false;
+  if (msg.role === "assistant") {
+    if (msg.reasoning && msg.reasoning.trim() !== "") return false;
+    if (msg.tool_calls && msg.tool_calls.length > 0) return false;
+  }
+  return true;
+}
+
+/**
+ * Single message bubble. Variant modifier is driven by `message.role`,
+ * with `--failed` / `--cancelled` overrides for the most-recent
+ * assistant bubble of the corresponding terminal status.
+ *
+ * For assistant bubbles, renders nested `<ReasoningView />` (when the
+ * message carries `reasoning`) and `<ToolCallView />` cards (one per
+ * `tool_calls` entry) before the visible text — matching the
+ * ui-sketches/03-chat.md layout.
+ */
+function MessageBubble(props: {
+  message: AIHubMessage;
+  classNames: MessageListClassNames;
+  isFailedAssistant: boolean;
+  isCancelledAssistant: boolean;
+  showRetryButton: boolean;
+  showReasoning: boolean;
+  showToolCalls: boolean;
+  retryLabel: string;
+  failedLabel: string;
+  cancelledStampLabel: string;
+  onRetry: () => void;
+  /**
+   * Resolver for the accordion + auto-expand state owned by
+   * `<MessageList />`. Returns whether a given block (`reasoning:<id>`
+   * or `tool:<tool_call_id>`) should render expanded.
+   */
+  isBlockExpanded: (blockId: string) => boolean;
+  /** Toggle handler for the accordion. */
+  onToggleBlock: (blockId: string) => void;
+  texts?: DeepPartial<AIHubTexts>;
+  renderMessageActions?: AIHubMessageActionRenderer;
+}): ReactNode {
+  const { message, classNames: cls } = props;
+  const baseModifier =
+    message.role === "user"
+      ? cls.bubbleUser
+      : message.role === "assistant"
+        ? cls.bubbleAssistant
+        : message.role === "system"
+          ? cls.bubbleSystem
+          : cls.bubbleTool;
+  const stateModifier = props.isFailedAssistant
+    ? cls.bubbleFailed
+    : props.isCancelledAssistant
+      ? cls.bubbleCancelled
+      : null;
+  const klass = [cls.bubble, baseModifier, stateModifier]
+    .filter(Boolean)
+    .join(" ");
+
+  const actions =
+    props.renderMessageActions && message.role === "assistant"
+      ? (props.renderMessageActions(message) as ReactNode)
+      : null;
+
+  const isAssistant = message.role === "assistant";
+  const reasoning = isAssistant && props.showReasoning ? message.reasoning : null;
+  const toolCalls = isAssistant && props.showToolCalls ? message.tool_calls : null;
+
+  return (
+    <div
+      className={klass}
+      data-testid="message-bubble"
+      data-role={message.role}
+      data-message-id={message.id}
+      data-failed={props.isFailedAssistant ? "true" : "false"}
+      data-cancelled={props.isCancelledAssistant ? "true" : "false"}
+    >
+      {reasoning ? (
+        (() => {
+          const blockId = reasoningBlockId(message.id);
+          return (
+            <ReasoningView
+              content={reasoning}
+              expanded={props.isBlockExpanded(blockId)}
+              onToggle={() => props.onToggleBlock(blockId)}
+              {...(props.texts !== undefined ? { texts: props.texts } : {})}
+            />
+          );
+        })()
+      ) : null}
+      {toolCalls?.map((call) => {
+        const blockId = toolCallBlockId(message.id, call.tool_call_id);
+        return (
+          <ToolCallView
+            key={call.tool_call_id}
+            toolName={call.tool_name}
+            status={call.status === "error" ? "error" : "done"}
+            input={call.input}
+            expanded={props.isBlockExpanded(blockId)}
+            onToggle={() => props.onToggleBlock(blockId)}
+            {...(call.output != null ? { output: call.output } : {})}
+            {...(call.error != null ? { error: call.error } : {})}
+            {...(props.texts !== undefined ? { texts: props.texts } : {})}
+          />
+        );
+      })}
+      <span className={cls.bubbleBody}>
+        {isAssistant ? (
+          <MarkdownRenderer content={message.content} />
+        ) : (
+          message.content.trim()
+        )}
+      </span>
+      {isAssistant && message.usage ? (
+        <CacheBadge usage={message.usage} />
+      ) : null}
+      {props.isFailedAssistant ? (
+        <div className={cls.bubbleActions}>
+          <span>{props.failedLabel}</span>
+          {props.showRetryButton ? (
+            <button
+              type="button"
+              className={cls.bubbleRetryButton}
+              onClick={props.onRetry}
+              data-testid="message-bubble-retry"
+            >
+              {props.retryLabel}
+            </button>
+          ) : null}
+        </div>
+      ) : props.isCancelledAssistant ? (
+        <div className={cls.bubbleActions}>
+          <span
+            className={cls.bubbleCancelledStamp}
+            data-testid="message-bubble-cancelled-stamp"
+          >
+            {props.cancelledStampLabel}
+          </span>
+        </div>
+      ) : null}
+      {actions ? (
+        <div
+          className={cls.bubbleActions}
+          data-testid="message-bubble-actions"
+        >
+          {actions}
+        </div>
+      ) : null}
+    </div>
+  );
+}