@adecore/agents-react 0.20.1 → 0.21.0

package/src/chat/subagent-conversation.ts

@@ -1,5 +1,5 @@
 import i18next from 'i18next';
-import type { ChatItem, ChatSubagentResult } from '@adecore/agent-contracts';
+import type { ChatApprovalItem, ChatItem, ChatQuestionItem, ChatSubagentResult } from '@adecore/agent-contracts';
 import { errorCode, isConnectionError, type ChatTransport } from '../transport';
 
 // What the panel opens on: the newest end of the conversation, which is where an agent that works is.
@@ -8,6 +8,7 @@ export const SUBAGENT_PAGE = 60;
 export interface SubagentConversationState {
     status: 'loading' | 'ready' | 'failed';
     items: ChatItem[];
+    pending: Array<ChatApprovalItem | ChatQuestionItem>;
     source: ChatSubagentResult['source'] | null;
     context: NonNullable<ChatSubagentResult['context']> | null;
     /* Where the page before the oldest item on screen starts; null once the start is there. */
@@ -23,6 +24,7 @@ export interface SubagentConversationState {
 export const INITIAL_CONVERSATION: SubagentConversationState = {
     status: 'loading',
     items: [],
+    pending: [],
     source: null,
     context: null,
     cursor: null,
@@ -59,6 +61,13 @@ export function mergeNewest(
     return { items, cursor: current.length === 0 ? pageCursor : currentCursor };
 }
 
+function pendingOf(items: readonly ChatItem[]): Array<ChatApprovalItem | ChatQuestionItem> {
+    return items.filter(
+        (item): item is ChatApprovalItem | ChatQuestionItem =>
+            (item.kind === 'approval' && item.decision === 'pending') || (item.kind === 'question' && item.state === 'pending')
+    );
+}
+
 function messageOf(error: unknown): string {
     return error instanceof Error ? error.message : i18next.t('agent-chat:subagents.noAnswer');
 }
@@ -131,7 +140,8 @@ export class SubagentConversation {
             this.set({ loadingEarlier: true });
             try {
                 const page = await this.ask({ cursor, limit: SUBAGENT_PAGE });
-                this.set({ items: [...page.items, ...this.state.items], cursor: page.history.cursor, live: page.live, loadingEarlier: false });
+                const items = [...page.items, ...this.state.items];
+                this.set({ items, pending: page.pending ?? pendingOf(items), cursor: page.history.cursor, live: page.live, loadingEarlier: false });
             } catch (error) {
                 if (errorCode(error) === 'history-expired') {
                     // The record was written again under this panel; what it holds now is the only truth.
@@ -167,6 +177,7 @@ export class SubagentConversation {
             this.set({
                 status: 'ready',
                 items: merged.items,
+                pending: page.pending ?? pendingOf(merged.items),
                 cursor: merged.cursor,
                 live: page.live,
                 source: page.source,

package/src/chat/timeline-flash.ts

@@ -1,4 +1,5 @@
 import { create } from 'zustand';
+import type { UiReplyTarget } from './logic/timeline-target';
 
 /* The row of a thread a jump landed on: it lights up once, and a card of changes opens when the jump asked for it. */
 export interface TimelineFlash {
@@ -6,13 +7,14 @@ export interface TimelineFlash {
     key: string;
     rowId: string;
     opens: boolean;
+    block?: Pick<UiReplyTarget, 'blockId' | 'revision'>;
     /* A second jump to the same row counts. */
     nonce: number;
 }
 
 interface TimelineFlashStore {
     target: TimelineFlash | null;
-    flash(key: string, rowId: string, opens: boolean): void;
+    flash(key: string, rowId: string, opens: boolean, block?: TimelineFlash['block']): void;
 }
 
 /* A little longer than the animation of `.chat-flash`, so a row that scrolls into view again later is neither lit nor opened a second time. */
@@ -20,9 +22,9 @@ const FLASH_MS = 2000;
 
 export const useTimelineFlash = create<TimelineFlashStore>((set, get) => ({
     target: null,
-    flash(key, rowId, opens) {
+    flash(key, rowId, opens, block) {
         const nonce = (get().target?.nonce ?? 0) + 1;
-        set({ target: { key, rowId, opens, nonce } });
+        set({ target: { key, rowId, opens, nonce, ...(block ? { block } : {}) } });
         const timer = setTimeout(() => {
             if (get().target?.nonce === nonce) {
                 set({ target: null });

package/src/chat/ui/ImageView.tsx

@@ -1,4 +1,4 @@
-import { useRef, useState } from 'react';
+import { useRef, useState, type ReactNode } from 'react';
 import { useTranslation } from 'react-i18next';
 import clsx from 'clsx';
 import { ImageOff, Minus, Plus, RotateCcw } from 'lucide-react';
@@ -34,7 +34,19 @@ function zoomed(view: View, factor: number, pointX: number, pointY: number): Vie
 }
 
 /* An image on its own, large: the wheel and the buttons zoom, dragging pans, Escape closes. */
-function Lightbox({ src, alt, open, onOpenChange }: { src: string; alt: string; open: boolean; onOpenChange(open: boolean): void }) {
+function Lightbox({
+    src,
+    alt,
+    open,
+    onOpenChange,
+    actions
+}: {
+    src: string;
+    alt: string;
+    open: boolean;
+    onOpenChange(open: boolean): void;
+    actions?: ReactNode;
+}) {
     const { t } = useTranslation('agent-chat');
     const [view, setView] = useState<View>(START);
     // The alt of an image an agent read is its path; the header shows the file and keeps the path on a tooltip.
@@ -84,6 +96,7 @@ function Lightbox({ src, alt, open, onOpenChange }: { src: string; alt: string;
                         />
                         <IconButton icon={RotateCcw} size="sm" label={t('image.reset')} disabled={view.scale === MIN_SCALE} onClick={() => setView(START)} />
                     </ButtonGroup>
+                    {actions}
                     <CloseButton label={t('common.action.close')} kbd="esc" className="ml-1" dialog />
                 </div>
                 <div
@@ -130,16 +143,41 @@ function Lightbox({ src, alt, open, onOpenChange }: { src: string; alt: string;
     );
 }
 
+export interface ImageThumbProps {
+    source: ResourceUrl;
+    alt: string;
+    className?: string;
+    /* Width over height, known before the bytes: the thumbnail then fills its container's width at that ratio and holds its place while they load. */
+    aspect?: number;
+    /* Drawn in the lightbox's header before Close, such as icon buttons that act on the image. */
+    actions?: ReactNode;
+    /* Whether the lightbox is open, for a caller that opens it from a control of its own; left out, the thumbnail keeps it. */
+    open?: boolean;
+    onOpenChange?(open: boolean): void;
+}
+
 /*
  * A thumbnail that opens the same image large. The button is the picture, so there is nothing to aim at.
  * The image is bytes where the host keeps them; until they are here a quiet square stands in for it.
  */
-export function ImageThumb({ source, alt, className }: { source: ResourceUrl; alt: string; className?: string }) {
-    const [open, setOpen] = useState(false);
+export function ImageThumb({ source, alt, className, aspect, actions, open: openProp, onOpenChange }: ImageThumbProps) {
+    const [ownOpen, setOwnOpen] = useState(false);
+    const open = openProp ?? ownOpen;
+    const setOpen = (next: boolean): void => {
+        setOwnOpen(next);
+        onOpenChange?.(next);
+    };
     const { url: src, failure } = source;
+    const ratio = aspect === undefined ? undefined : { aspectRatio: aspect };
     if (src === null) {
         return (
-            <span className="grid size-16 place-items-center rounded-lg border border-border bg-surface-sunken text-text-faint">
+            <span
+                className={clsx(
+                    'grid place-items-center rounded-lg border border-border bg-surface-sunken text-text-faint',
+                    aspect === undefined ? 'size-16' : 'w-full'
+                )}
+                style={ratio}
+            >
                 {failure !== null && (
                     <Tooltip label={failure}>
                         <Icon icon={ImageOff} size={14} />
@@ -150,10 +188,15 @@ export function ImageThumb({ source, alt, className }: { source: ResourceUrl; al
     }
     return (
         <>
-            <button className="block overflow-hidden rounded-lg border border-border" onClick={() => setOpen(true)}>
-                <img src={src} alt={alt} className={className} />
+            <button
+                type="button"
+                className={clsx('block overflow-hidden rounded-lg border border-border', aspect !== undefined && 'w-full')}
+                style={ratio}
+                onClick={() => setOpen(true)}
+            >
+                <img src={src} alt={alt} className={clsx(aspect !== undefined && 'size-full object-contain', className)} />
             </button>
-            <Lightbox src={src} alt={alt} open={open} onOpenChange={setOpen} />
+            <Lightbox src={src} alt={alt} open={open} onOpenChange={setOpen} actions={actions} />
         </>
     );
 }

package/src/chat/ui/SubagentTimeline.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
 import { useTranslation } from 'react-i18next';
 import { Bot, LoaderCircle } from 'lucide-react';
 import { deriveTimelineRows } from '../logic/timeline';
@@ -9,6 +9,8 @@ import { EMPTY_TARGET, readTimelineTarget, type TimelineTarget } from '../logic/
 import { openBelow, useSubagentTrail, type SubagentStep } from '../subagent-view';
 import { Row } from './rows/Rows';
 import { ReplyContext } from './reply-context';
+import { PromptComposer } from './PromptComposer';
+import { useProviders } from '../../state/providers';
 import { SubagentInfo } from './SubagentInfo';
 import { TimelineMenuPopup } from './TimelineMenu';
 import { FOLLOW_THRESHOLD_PX, rowRhythm } from './rows/row-rhythm';
@@ -27,8 +29,14 @@ const NO_TURNS = new Set<string>();
 export function SubagentTimeline({ chatId, toolUseId }: { chatId: string; toolUseId: string }) {
     const { t } = useTranslation('agent-chat');
     const scope = useChatScope();
+    const connected = useSyncExternalStore(
+        useCallback((changed) => scope.transport.subscribeStatus(changed), [scope]),
+        useCallback(() => scope.transport.status === 'open', [scope]),
+        () => false
+    );
     const { trail, show } = useSubagentTrail(chatId);
     const [state, setState] = useState<SubagentConversationState>(INITIAL_CONVERSATION);
+    const denyReason = useProviders((row) => row.providers.find((provider) => provider.kind === state.context?.provider)?.capabilities.denyReason === true);
     const controller = useRef<SubagentConversation | null>(null);
     const scrollRef = useRef<HTMLDivElement>(null);
     const threadRef = useRef<HTMLDivElement>(null);
@@ -167,6 +175,21 @@ export function SubagentTimeline({ chatId, toolUseId }: { chatId: string; toolUs
                     </ReplyContext.Provider>
                 </FileLinkContext.Provider>
             )}
+            {state.context?.chatId !== undefined && state.pending.length > 0 && (
+                <div className="chat-column-content shrink-0">
+                    <PromptComposer
+                        key={state.context.chatId}
+                        chatId={state.context.chatId}
+                        pending={state.pending}
+                        focused={false}
+                        disabled={!connected}
+                        hasDraft={false}
+                        denyReason={denyReason}
+                    >
+                        {null}
+                    </PromptComposer>
+                </div>
+            )}
         </div>
     );
 }

package/src/chat/ui/Timeline.tsx

@@ -32,8 +32,17 @@ import {
     ticksOf,
     ticksWithHits
 } from '../logic/scrubber';
-import { EMPTY_TARGET, readTimelineTarget, withCurrentText, type TimelineTarget } from '../logic/timeline-target';
+import {
+    EMPTY_TARGET,
+    readTimelineTarget,
+    revealUiReplyBlock,
+    uiReplyJump,
+    withCurrentText,
+    type TimelineTarget,
+    type UiReplyTarget
+} from '../logic/timeline-target';
 import { forkRefusal } from '../logic/fork';
+import { UiReplyNavigationContext } from './reply-context';
 import { FindRevealContext } from './find-reveal';
 import { BookmarkMarker } from './BookmarkMarker';
 import { MessageActions } from './MessageActions';
@@ -207,10 +216,26 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
     const marks = useMemo(() => bookmarkRows(rows, bookmarks ?? [], items ?? {}), [rows, bookmarks, items]);
     const ticks = useMemo(() => ticksOf(rows, marks), [rows, marks]);
     // A message a jump is on its way to; it may first have to open the turn its reply folded into.
-    const [seeking, setSeeking] = useState<string | null>(null);
+    const [seeking, setSeeking] = useState<{ itemId: string; block?: UiReplyTarget; key: string } | null>(null);
+    const [landing, setLanding] = useState<{ target: UiReplyTarget; key: string } | null>(null);
     // A turn a jump is on its way to, which waits for the page its messages are on to come in.
     const [revealing, setRevealing] = useState<{ turnId: string; target: TurnTarget } | null>(null);
     const flash = useTimelineFlash((s) => s.target);
+    const revealBlock = useCallback(
+        (block: UiReplyTarget) => {
+            setLanding(null);
+            setSeeking({ itemId: block.itemId, block, key: keyOf(chatId) });
+        },
+        [keyOf, chatId]
+    );
+    const uiNavigation = useMemo(
+        () => ({
+            chatId,
+            reveal: revealBlock,
+            flash: flash?.key === keyOf(chatId) && flash.block ? { itemId: flash.rowId, ...flash.block, nonce: flash.nonce } : null
+        }),
+        [revealBlock, flash, keyOf, chatId]
+    );
 
     // Whether the thread's text clears the strip depends on the width of the view, which only the thread's own frame tells.
     useEffect(() => {
@@ -389,7 +414,8 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
             return;
         }
         if (tick.bookmark !== null) {
-            setSeeking(tick.bookmark.itemId);
+            setLanding(null);
+            setSeeking({ itemId: tick.bookmark.itemId, key: keyOf(chatId) });
             return;
         }
         followRef.current = false;
@@ -400,14 +426,34 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
         if (seeking === null) {
             return;
         }
-        const index = rows.findIndex((row) => row.id === seeking);
+        if (seeking.key !== keyOf(chatId)) {
+            setSeeking(null);
+            return;
+        }
+        if (seeking.block) {
+            const jump = uiReplyJump(seeking.block, rows, items, turns.ids, cursor !== null);
+            if (jump.kind === 'earlier') {
+                loadEarlier();
+            } else if (jump.kind === 'turn') {
+                turns.add(jump.turnId);
+            } else {
+                setSeeking(null);
+                if (jump.kind === 'row') {
+                    followRef.current = false;
+                    virtualizer.scrollToIndex(jump.index, { align: 'start' });
+                    setLanding({ target: seeking.block, key: seeking.key });
+                }
+            }
+            return;
+        }
+        const index = rows.findIndex((row) => row.id === seeking.itemId);
         if (index !== -1) {
             setSeeking(null);
             followRef.current = false;
             virtualizer.scrollToIndex(index, { align: 'start' });
             return;
         }
-        const item = items?.[seeking];
+        const item = items?.[seeking.itemId];
         if (item === undefined && cursor !== null) {
             loadEarlier();
             return;
@@ -418,8 +464,36 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
             return;
         }
         setSeeking(null);
-    }, [seeking, rows, items, turns, virtualizer, cursor, loadEarlier]);
-    useEffect(() => registerItemJumper(keyOf(chatId), setSeeking), [keyOf, chatId]);
+    }, [seeking, rows, items, turns, virtualizer, cursor, loadEarlier, keyOf, chatId]);
+    useEffect(
+        () =>
+            registerItemJumper(keyOf(chatId), (itemId) => {
+                setLanding(null);
+                setSeeking({ itemId, key: keyOf(chatId) });
+            }),
+        [keyOf, chatId]
+    );
+    useLayoutEffect(() => {
+        if (!landing || landing.key !== keyOf(chatId)) {
+            return;
+        }
+        let frame = 0;
+        let attempts = 0;
+        const reveal = () => {
+            const scroller = scrollRef.current;
+            if (scroller && revealUiReplyBlock(scroller, landing.target)) {
+                useTimelineFlash.getState().flash(keyOf(chatId), landing.target.itemId, false, landing.target);
+                setLanding(null);
+            } else if (++attempts < 30) {
+                // Virtual rows mount after scrollToIndex updates the visible range.
+                frame = requestAnimationFrame(reveal);
+            } else {
+                setLanding(null);
+            }
+        };
+        frame = requestAnimationFrame(reveal);
+        return () => cancelAnimationFrame(frame);
+    }, [landing, keyOf, chatId]);
 
     useLayoutEffect(() => {
         if (revealing === null) {
@@ -562,7 +636,7 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
                                                     top={virtualRow.start}
                                                     ref={virtualizer.measureElement}
                                                 >
-                                                    {flash !== null && flash.key === keyOf(chatId) && flash.rowId === row.id && (
+                                                    {flash !== null && flash.key === keyOf(chatId) && flash.rowId === row.id && !flash.block && (
                                                         <span
                                                             key={flash.nonce}
                                                             className="chat-flash pointer-events-none absolute inset-0 rounded-lg"
@@ -574,19 +648,21 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
                                                             <ReplyHeader chatId={chatId} at={header.at} />
                                                         </div>
                                                     )}
-                                                    <FindRevealContext.Provider value={chatFind.reveal}>
-                                                        <MarkableRow row={row} chatId={chatId} bookmark={marks.get(row.id) ?? null}>
-                                                            <Row
-                                                                row={row}
-                                                                chatId={chatId}
-                                                                toggleGroup={groups.toggle}
-                                                                toggleTurn={turns.toggle}
-                                                                toggleSubagent={subagents.toggle}
-                                                                openSubagent={openSubagent}
-                                                                openConversation={openConversation}
-                                                            />
-                                                        </MarkableRow>
-                                                    </FindRevealContext.Provider>
+                                                    <UiReplyNavigationContext.Provider value={uiNavigation}>
+                                                        <FindRevealContext.Provider value={chatFind.reveal}>
+                                                            <MarkableRow row={row} chatId={chatId} bookmark={marks.get(row.id) ?? null}>
+                                                                <Row
+                                                                    row={row}
+                                                                    chatId={chatId}
+                                                                    toggleGroup={groups.toggle}
+                                                                    toggleTurn={turns.toggle}
+                                                                    toggleSubagent={subagents.toggle}
+                                                                    openSubagent={openSubagent}
+                                                                    openConversation={openConversation}
+                                                                />
+                                                            </MarkableRow>
+                                                        </FindRevealContext.Provider>
+                                                    </UiReplyNavigationContext.Provider>
                                                 </RowContainer>
                                             );
                                         })}

package/src/chat/ui/intelligent-ui/UiBlockFooter.tsx

@@ -0,0 +1,139 @@
+import { useId, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Lock, Radio, TriangleAlert, Wrench } from 'lucide-react';
+import { Icon, Spinner, Tooltip, useTickingText } from '@adecore/ui';
+import { formatAgo, formatMoment } from '@adecore/ui/format';
+import type { UiLiveStatus } from './render-context';
+import { useLater } from './use-later';
+
+/* Something the compiler repaired, such as a prop it dropped; never an error to a person. */
+export interface UiBlockFix {
+    code: string;
+    message: string;
+}
+
+export interface UiBlockFooterProps {
+    live?: UiLiveStatus | null;
+    /* The label of the Choice that answered the block, and when, in milliseconds since the epoch. */
+    answered?: { label: string; at: number } | null;
+    fixes?: readonly UiBlockFix[];
+    /* Why the whole block is drawn as its text, such as that it is too large. */
+    shownAsText?: string | null;
+}
+
+const NO_FIXES: readonly UiBlockFix[] = [];
+const READING_SPINNER_MS = 1000;
+
+/* The one sign of a live block: what it reads, and when it last read it. A reading spins only after a second. */
+function LivePart({ live }: { live: UiLiveStatus }) {
+    const { t } = useTranslation('agent-chat');
+    const slow = useLater(live.state === 'reading', READING_SPINNER_MS);
+    const { readAt } = live;
+    const fresh = live.state === 'fresh' || live.state === 'reading';
+    const ago = useTickingText(() => {
+        if (readAt === null) {
+            return '';
+        }
+        const time = formatAgo(Date.now() - readAt);
+        return fresh ? t('blocks.live.read', { time }) : time;
+    });
+    const source = live.source ?? live.sources[0] ?? '';
+    const icon = slow ? (
+        <Spinner size={12} />
+    ) : live.state === 'failed' ? (
+        <Icon icon={TriangleAlert} size={12} className="text-status-needs-you" />
+    ) : live.state === 'refused' ? (
+        <Icon icon={Lock} size={12} />
+    ) : (
+        <Icon icon={Radio} size={12} className="text-status-idle" />
+    );
+    const words =
+        live.state === 'failed'
+            ? t('blocks.live.failed', { source })
+            : live.state === 'refused'
+              ? t('blocks.live.refused', { source })
+              : t('blocks.live.label');
+    const hint =
+        live.state === 'failed' && live.reason !== undefined
+            ? live.reason
+            : live.sources.length > 0
+              ? t('blocks.live.sources', { sources: live.sources.join(', ') })
+              : null;
+    const body = (
+        <span tabIndex={hint === null ? undefined : 0} className="flex items-center gap-1.5">
+            {icon}
+            <span>{words}</span>
+            {readAt !== null && live.state !== 'refused' && (
+                <>
+                    <span aria-hidden>·</span>
+                    <time dateTime={new Date(readAt).toISOString()}>
+                        <span ref={ago} className="tabular-nums" />
+                    </time>
+                </>
+            )}
+            {readAt === null && fresh && (
+                <>
+                    <span aria-hidden>·</span>
+                    <span>{t('blocks.live.notRead')}</span>
+                </>
+            )}
+        </span>
+    );
+    return hint === null ? body : <Tooltip label={hint}>{body}</Tooltip>;
+}
+
+/*
+ * The line under a block, only when it has something to say: live, answered, repaired or drawn as
+ * text, in that order. A hairline of the soft border runs the full width of the card over it.
+ */
+export function UiBlockFooter({ live = null, answered = null, fixes = NO_FIXES, shownAsText = null }: UiBlockFooterProps) {
+    const { t } = useTranslation('agent-chat');
+    const [fixesOpen, setFixesOpen] = useState(false);
+    const listId = useId();
+    if (live === null && answered === null && fixes.length === 0 && shownAsText === null) {
+        return null;
+    }
+    return (
+        <div className="-mx-2.25 mt-2.25 -mb-2.25 flex flex-col gap-1.5 border-t border-border-soft px-4.25 py-2 text-xs text-text-faint">
+            <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
+                {live !== null && <LivePart live={live} />}
+                {answered !== null && (
+                    <span className="flex items-center gap-1.5">
+                        <span>{t('blocks.answered', { label: answered.label })}</span>
+                        <span aria-hidden>·</span>
+                        <time dateTime={new Date(answered.at).toISOString()}>{formatMoment(answered.at)}</time>
+                    </span>
+                )}
+                {fixes.length > 0 && (
+                    <button
+                        type="button"
+                        aria-expanded={fixesOpen}
+                        aria-controls={listId}
+                        className="flex items-center gap-1.5 rounded-sm hover:text-text-muted"
+                        onClick={() => setFixesOpen(!fixesOpen)}
+                    >
+                        <Icon icon={Wrench} size={12} />
+                        {t('blocks.fixes', { count: fixes.length })}
+                    </button>
+                )}
+                {shownAsText !== null && (
+                    <span className="flex items-center gap-1.5">
+                        <span>{t('blocks.shownAsText')}</span>
+                        <span aria-hidden>·</span>
+                        <span>{shownAsText}</span>
+                    </span>
+                )}
+            </div>
+            {fixes.length > 0 && (
+                <ul id={listId} hidden={!fixesOpen} className="flex flex-col gap-0.5 text-text-muted">
+                    {fixes.map((fix, index) => (
+                        <li key={index} className="flex gap-2">
+                            <span className="shrink-0 font-mono">{fix.code}</span>
+                            <span className="min-w-0">{fix.message}</span>
+                        </li>
+                    ))}
+                </ul>
+            )}
+        </div>
+    );
+}

package/src/chat/ui/intelligent-ui/UiBlockFrame.tsx

@@ -0,0 +1,89 @@
+import { useLayoutEffect, useRef, useState, type ReactNode, type RefObject } from 'react';
+import clsx from 'clsx';
+import { useTranslation } from 'react-i18next';
+import type { UiViewNode } from '@adecore/intelligent-ui';
+import { Skeleton } from '@adecore/ui';
+import { uiBlockHead } from './node-text';
+import { UiHeadContext } from './render-context';
+import { UiBlockFooter, type UiBlockFooterProps } from './UiBlockFooter';
+
+export interface UiBlockFrameProps extends UiBlockFooterProps {
+    /* The evaluated top-level nodes, read for the Summary that heads the block. */
+    nodes: readonly UiViewNode[];
+    phase: 'streaming' | 'final';
+    /* The rendered nodes, or the markdown of the whole block when it is shown as text. */
+    children: ReactNode;
+    className?: string;
+}
+
+const RELEASE_MS = 200;
+
+/*
+ * The tallest the card has been, while `active`: a streaming block grows and never shrinks until its
+ * last compile. Then the card eases down to its own height, or drops there for a person who asked
+ * for less motion.
+ */
+function useRisingFloor(active: boolean): [RefObject<HTMLDivElement | null>, number] {
+    const ref = useRef<HTMLDivElement>(null);
+    const held = useRef(0);
+    const [floor, setFloor] = useState(0);
+    useLayoutEffect(() => {
+        const element = ref.current;
+        if (element === null) {
+            return;
+        }
+        if (active) {
+            const observer = new ResizeObserver(() => {
+                const height = Math.ceil(element.getBoundingClientRect().height);
+                held.current = Math.max(held.current, height);
+                setFloor(held.current);
+            });
+            observer.observe(element);
+            return () => {
+                observer.disconnect();
+                setFloor(0);
+            };
+        }
+        // The final render already let go of the floor, so the card measures its own height here.
+        const from = held.current;
+        const to = element.getBoundingClientRect().height;
+        held.current = 0;
+        const reduced = element.ownerDocument.defaultView?.matchMedia('(prefers-reduced-motion: reduce)').matches === true;
+        if (from - to < 1 || reduced) {
+            return;
+        }
+        const release = element.animate([{ minHeight: `${from}px` }, { minHeight: `${to}px` }], { duration: RELEASE_MS, easing: 'ease-out' });
+        return () => release.cancel();
+    }, [active]);
+    return [ref, floor];
+}
+
+/*
+ * The card of one block, with its footer. Named by its Summary and busy while it streams, but never
+ * live: reading out every compile would be noise. A node fades in as it arrives, without a stagger,
+ * and for a person who asked for less motion it only fades; a node inside another only fades
+ * (`chat-ui-nodes`). Until the first node a skeleton holds the place of the head.
+ */
+export function UiBlockFrame({ nodes, phase, children, className, ...footer }: UiBlockFrameProps) {
+    const { t } = useTranslation('agent-chat');
+    const streaming = phase === 'streaming';
+    const head = uiBlockHead(nodes);
+    const [ref, floor] = useRisingFloor(streaming);
+    return (
+        <UiHeadContext value={head?.id ?? null}>
+            <div
+                ref={ref}
+                role="group"
+                aria-label={head === null || head.label === '' ? t('blocks.label') : head.label}
+                aria-busy={streaming || undefined}
+                className={clsx('flex min-h-11 flex-col rounded-2xl border border-border bg-surface-raised p-2.25', className)}
+                style={streaming && floor > 0 ? { minHeight: floor } : undefined}
+            >
+                <div className="flex flex-col gap-3 *:transition-[opacity,translate] *:duration-160 *:ease-out *:starting:opacity-0 motion-safe:*:starting:translate-y-0.5">
+                    {nodes.length === 0 && streaming ? <Skeleton className="mx-2 my-1 w-2/5" /> : children}
+                </div>
+                <UiBlockFooter {...footer} />
+            </div>
+        </UiHeadContext>
+    );
+}

package/src/chat/ui/intelligent-ui/UiFallbackPart.tsx

@@ -0,0 +1,21 @@
+import { useTranslation } from 'react-i18next';
+import { Markdown } from '../Markdown';
+
+/* Why a part is drawn as its text: a component this version does not know, or one it could not draw. */
+export type UiFallbackProblem = { kind: 'unknown'; component: string } | { kind: 'failed' };
+
+/*
+ * One part of a block as the markdown it stands for, in a quiet surface with a line that says why.
+ * A person sees it as a repair, never as an error, so nothing here is red.
+ */
+export function UiFallbackPart({ fallback, problem }: { fallback: string; problem: UiFallbackProblem }) {
+    const { t } = useTranslation('agent-chat');
+    return (
+        <div className="flex flex-col gap-1 rounded-md bg-surface-hover p-2">
+            <span className="text-xs text-text-faint">
+                {problem.kind === 'unknown' ? t('blocks.unknownComponent', { component: problem.component }) : t('blocks.renderFailed')}
+            </span>
+            {fallback !== '' && <Markdown text={fallback} fileLinks={false} />}
+        </div>
+    );
+}