@adecore/agents-react 0.20.0 → 0.21.0

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) {
@@ -498,7 +572,7 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
         // A file an answer names is relative to the folder this chat runs in, which is a worktree as
         // often as it is the project itself.
         <FileLinkContext.Provider value={info?.cwd ?? null}>
-            <div ref={frameRef} className="relative flex min-h-0 grow flex-col">
+            <div ref={frameRef} className="relative flex min-h-0 grow flex-col" data-file-cwd={info?.cwd ?? ''} data-file-scope-id={scope.id}>
                 {searching && chatFind.bar}
                 <ContextMenu.Root>
                     <div
@@ -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/TimelineMenu.tsx

@@ -8,7 +8,7 @@ import type { TimelineTarget } from '../logic/timeline-target';
 import { chatHost } from '../../host';
 import { useChatScope } from '../../scope';
 import { useChatRow } from '../../state/chats';
-import { openFileLink, useFileLinkCwd } from './file-links';
+import { openFileLink, useFileLinkCwd, useFileLinkScopeId } from './file-links';
 import { ContextMenu, copyText, DisabledReason, EDIT_SHORTCUTS, Icon, Kbd, selectAllWithin } from '@adecore/ui';
 
 /*
@@ -34,10 +34,13 @@ export function TimelineMenuPopup({
     const markable = chatId !== null && (target.row?.kind === 'user' || target.row?.kind === 'assistant') ? target.row.id : null;
     // A thread outside a chat (a sub-agent's transcript) has no cwd of its own; the app answers for it then.
     const cwd = useFileLinkCwd();
+    const scopeId = useFileLinkScopeId();
     const { fork, fileLinks } = chatHost();
     const openInPreview = (): void => {
-        if (target.path !== null) {
-            openFileLink(cwd, { path: target.path, ...(target.line === null ? {} : { line: target.line }), directory: false });
+        if (target.file != null) {
+            openFileLink(target.file.cwd, target.file.ref, target.file.scopeId);
+        } else if (target.path !== null) {
+            openFileLink(cwd, { path: target.path, ...(target.line === null ? {} : { line: target.line }), directory: false }, scopeId);
         }
     };
     return (

package/src/chat/ui/file-links.ts

@@ -1,5 +1,6 @@
 import { createContext, useContext, useMemo } from 'react';
 import { chatHost, type FileRef } from '../../host';
+import { ChatScopeContext } from '../../scope';
 
 /*
  * The folder a relative reference in rendered text counts from: a chat's own cwd, which is a
@@ -12,13 +13,18 @@ export function useFileLinkCwd(): string | null {
     return useContext(FileLinkContext);
 }
 
+export function useFileLinkScopeId(): string | null {
+    return useContext(ChatScopeContext)?.id ?? null;
+}
+
 /* The reference a piece of text names, only where this spot on screen could open it. */
 export function useFileLinkTarget(text: string): FileRef | null {
     const cwd = useFileLinkCwd();
-    return useMemo(() => chatHost().fileLinks?.target(text, cwd) ?? null, [text, cwd]);
+    const scopeId = useFileLinkScopeId();
+    return useMemo(() => chatHost().fileLinks?.target(text, cwd, scopeId) ?? null, [text, cwd, scopeId]);
 }
 
 /* A reference followed, the way the app opens a file or a folder. */
-export function openFileLink(cwd: string | null, ref: FileRef): void {
-    chatHost().fileLinks?.open(cwd, ref);
+export function openFileLink(cwd: string | null, ref: FileRef, scopeId: string | null = null): void {
+    chatHost().fileLinks?.open(cwd, ref, scopeId);
 }

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>
+    );
+}