@adecore/agents-react 0.37.3 → 0.38.0

package/src/chat/ui/VisualFrame.tsx

@@ -1,11 +1,11 @@
-import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import clsx from 'clsx';
-import { visualThemeFragment, type ChatVisual, type VisualAppearance, type VisualTheme } from '@adecore/agent-contracts/visual';
+import { VISUAL_LIMITS, visualThemeFragment, type ChatVisual, type VisualAppearance, type VisualTheme } from '@adecore/agent-contracts/visual';
 import { Spinner, useMeasuredWidth } from '@adecore/ui';
 import { useChatHost } from '../../host';
 import { useChatScope } from '../../scope';
-import { initialVisualContentHeight, rememberVisualHeight } from '../logic/visual-height';
+import { DEFAULT_HEIGHT_PX, initialVisualContentHeight, rememberVisualHeight } from '../logic/visual-height';
 import { VisualBridge } from '../visual-bridge';
 import { VisualViewportController } from '../visual-viewport';
 import { useVisualTheme } from './visual-theme';
@@ -18,6 +18,25 @@ export interface VisualFrameProps {
     className?: string;
 }
 
+export interface VisualPageFrameProps {
+    /* Reads the page's HTML each time the frame opens; the frame opens again when this changes, so keep it the same function while the page is. */
+    page: () => Promise<string>;
+    /* The frame's accessible name. */
+    title: string;
+    /* The tallest the page may grow on a host page without the viewport; left out, the limit of every visual. */
+    maxHeight?: number;
+    /* Fills its positioned parent and lets the page scroll inside it, rather than taking the height the page reports. */
+    fill?: boolean;
+    className?: string;
+}
+
+interface PageFrameProps extends VisualPageFrameProps {
+    maxHeight: number;
+    /* The height to start at before the page reports one, for a frame `width` pixels wide. */
+    initialHeight(width: number): number;
+    onHeight?(width: number, height: number): void;
+}
+
 /*
  * A link the page asks to open counts only while a person acts in the frame: it has the focus, and a
  * click or a key in it is recent. A page can take the focus by script, so this stops a link opened as
@@ -27,15 +46,43 @@ function personActsIn(frame: HTMLIFrameElement): boolean {
     return frame.ownerDocument.activeElement === frame && navigator.userActivation?.isActive !== false;
 }
 
+const defaultHeight = (): number => DEFAULT_HEIGHT_PX;
+
+/* A visual of a chat, its page read from the chat's attachments under the visual's id. */
+export function VisualFrame({ chatId, visual, fill = false, className }: VisualFrameProps) {
+    const { attachments } = useChatHost();
+    const scope = useChatScope();
+    // The frame opens again when its page changes, so the reader keeps its identity while the visual does.
+    const page = useCallback(() => attachments.read(scope.id, chatId, visual.id).then((blob) => blob.text()), [attachments, scope.id, chatId, visual.id]);
+    return (
+        <PageFrame
+            page={page}
+            title={visual.title}
+            maxHeight={visual.maxHeight}
+            fill={fill}
+            className={className}
+            initialHeight={(width) => initialVisualContentHeight(visual, width)}
+            onHeight={(width, height) => rememberVisualHeight(visual.id, width, height)}
+        />
+    );
+}
+
 /*
- * One visual's page in a frame that loads the app's sandbox host page; the bridge hands it the page and
- * the theme. The frame never gets `allow-same-origin`, which keeps the page on an opaque origin even
- * when the host page is served on the app's own. Its box keeps one height while it loads or fails.
+ * A visual's page outside a chat thread, such as one an app kept: the same sandboxed frame, theme and
+ * links as in a thread, with the page read through `page`. Draws nothing while the host has no `visuals`.
  */
-export function VisualFrame({ chatId, visual, fill = false, className }: VisualFrameProps) {
-    const { visuals, attachments } = useChatHost();
+export function VisualPageFrame({ maxHeight = VISUAL_LIMITS.maxHeight, ...props }: VisualPageFrameProps) {
+    return <PageFrame {...props} maxHeight={maxHeight} initialHeight={defaultHeight} />;
+}
+
+/*
+ * One page in a frame that loads the app's sandbox host page; the bridge hands it the page and the
+ * theme. The frame never gets `allow-same-origin`, which keeps the page on an opaque origin even when
+ * the host page is served on the app's own. Its box keeps one height while it loads or fails.
+ */
+function PageFrame({ page, title, maxHeight, fill = false, className, initialHeight, onHeight }: PageFrameProps) {
+    const { visuals } = useChatHost();
     const { t } = useTranslation('agent-chat');
-    const scope = useChatScope();
     const frameUrl = visuals?.frameUrl ?? null;
     const boxRef = useRef<HTMLDivElement | null>(null);
     const frameRef = useRef<HTMLIFrameElement>(null);
@@ -50,6 +97,7 @@ export function VisualFrame({ chatId, visual, fill = false, className }: VisualF
     };
     const theme = useVisualTheme(boxRef);
     const widthRef = useRef(width);
+    const onHeightRef = useRef(onHeight);
     const [reported, setReported] = useState<number | null>(null);
     // The appearance the page is drawn in once it runs; until then the frame matches the sandbox host page, which declares none.
     const [drawn, setDrawn] = useState<VisualAppearance | null>(null);
@@ -59,11 +107,12 @@ export function VisualFrame({ chatId, visual, fill = false, className }: VisualF
     if (opening === null && frameUrl !== null && theme !== null && width > 0) {
         setOpening({ src: frameUrl + visualThemeFragment(theme), theme });
     }
-    const height = fill || width === 0 ? undefined : (reported ?? initialVisualContentHeight(visual, width));
+    const height = fill || width === 0 ? undefined : (reported ?? initialHeight(width));
 
     useLayoutEffect(() => {
         widthRef.current = width;
-    }, [width]);
+        onHeightRef.current = onHeight;
+    }, [width, onHeight]);
 
     useLayoutEffect(() => {
         const frame = frameRef.current;
@@ -72,8 +121,8 @@ export function VisualFrame({ chatId, visual, fill = false, className }: VisualF
         }
         const bridge = new VisualBridge({
             frame: () => frame.contentWindow,
-            visual: { maxHeight: visual.maxHeight },
-            page: attachments.read(scope.id, chatId, visual.id).then((blob) => blob.text()),
+            visual: { maxHeight },
+            page: page(),
             theme: opening.theme,
             mayOpenLink: () => personActsIn(frame),
             openLink: (url) => visuals?.openLink(url),
@@ -82,7 +131,7 @@ export function VisualFrame({ chatId, visual, fill = false, className }: VisualF
                     return;
                 }
                 setReported(next);
-                rememberVisualHeight(visual.id, widthRef.current, next);
+                onHeightRef.current?.(widthRef.current, next);
             },
             ...(!fill
                 ? {
@@ -102,7 +151,7 @@ export function VisualFrame({ chatId, visual, fill = false, className }: VisualF
             bridge.dispose();
             bridgeRef.current = null;
         };
-    }, [opening, scope.id, chatId, visual.id, visual.maxHeight, fill, visuals, attachments]);
+    }, [opening, page, maxHeight, fill, visuals]);
 
     useLayoutEffect(() => {
         const box = boxRef.current;
@@ -118,7 +167,7 @@ export function VisualFrame({ chatId, visual, fill = false, className }: VisualF
             controller.dispose();
             controllerRef.current = null;
         };
-    }, [fill, viewportReady, opening, scope.id, chatId, visual.id, visual.maxHeight]);
+    }, [fill, viewportReady, opening, page, maxHeight]);
 
     useLayoutEffect(() => controllerRef.current?.refresh(), [height, width]);
 
@@ -135,7 +184,7 @@ export function VisualFrame({ chatId, visual, fill = false, className }: VisualF
                     <iframe
                         ref={frameRef}
                         src={opening.src}
-                        title={visual.title}
+                        title={title}
                         loading="lazy"
                         sandbox="allow-scripts allow-forms"
                         className={clsx('block size-full border-0', failed && 'invisible')}
@@ -145,13 +194,11 @@ export function VisualFrame({ chatId, visual, fill = false, className }: VisualF
                     />
                 )}
                 {failed ? (
-                    <p className="absolute inset-0 grid place-items-center px-4 text-center text-xs text-text-muted">
-                        {t('visuals.failed', { title: visual.title })}
-                    </p>
+                    <p className="absolute inset-0 grid place-items-center px-4 text-center text-xs text-text-muted">{t('visuals.failed', { title })}</p>
                 ) : (
                     drawn === null && (
                         <span className="chat-visual-wait pointer-events-none absolute inset-0 grid place-items-center text-text-faint">
-                            <Spinner size={16} label={t('visuals.loading', { title: visual.title })} />
+                            <Spinner size={16} label={t('visuals.loading', { title })} />
                         </span>
                     )
                 )}

package/src/chat/ui/index.ts

@@ -22,6 +22,7 @@ export { Timeline } from './Timeline';
 export { TimelineMenuPopup } from './TimelineMenu';
 export { default as UnifiedDiff } from './UnifiedDiff';
 export { UploadThumb } from './UploadThumb';
+export { VisualPageFrame, type VisualPageFrameProps } from './VisualFrame';
 export { WelcomeGreeting } from './Welcome';
 export { externalChange, composerEditorExtensions } from './composer/editor';
 export {

package/src/chat/ui/rows/GeneratedImageRow.tsx

@@ -13,6 +13,7 @@ import { attachmentAspect, generatedImageView, type GeneratedImageFailure } from
 import { toolStartedAt } from '../../logic/tools';
 import { CHIP_IN_MESSAGE, MENTION_TONE } from '../chips';
 import { useFileLinkCwd, useOpenFileLink } from '../file-links';
+import { HostMenuItems } from '../HostMenuItems';
 import { ImageThumb } from '../ImageView';
 import { ROW_GUTTER } from '../icons';
 import { RunningFor, WorkRow } from './WorkRows';
@@ -104,6 +105,7 @@ function ReadyImage({ chatId, attachment, prompt, transparent }: { chatId: strin
     const missing = source.failure !== null;
     const aspect = attachmentAspect(attachment);
     const { open, saveToProject } = attachments;
+    const extra = attachments.actions?.(scopeId, chatId, attachment) ?? [];
 
     const detail = [
         attachment.width !== undefined && attachment.height !== undefined
@@ -171,13 +173,16 @@ function ReadyImage({ chatId, attachment, prompt, transparent }: { chatId: strin
                         >
                             <ButtonGroup>
                                 <IconButton icon={Maximize2} size="sm" label={t('generatedImage.openLarge')} onClick={() => setLightbox(true)} />
-                                {prompt !== null && (
+                                {(prompt !== null || extra.length > 0) && (
                                     <Menu.Root>
                                         <IconButton icon={Ellipsis} size="sm" label={t('generatedImage.more')} render={<Menu.Trigger />} />
                                         <Menu.Popup align="end">
-                                            <Menu.Item onClick={() => copyText(prompt)}>
-                                                <Icon icon={Copy} size={14} /> {t('generatedImage.copyPrompt')}
-                                            </Menu.Item>
+                                            {prompt !== null && (
+                                                <Menu.Item onClick={() => copyText(prompt)}>
+                                                    <Icon icon={Copy} size={14} /> {t('generatedImage.copyPrompt')}
+                                                </Menu.Item>
+                                            )}
+                                            <HostMenuItems actions={extra} />
                                         </Menu.Popup>
                                     </Menu.Root>
                                 )}

package/src/chat/ui/rows/VisualRow.tsx

@@ -5,6 +5,7 @@ import { ButtonGroup, ErrorBoundary, Icon, IconButton, Menu, Surface } from '@ad
 import { useChatHost } from '../../../host';
 import { useChatScope } from '../../../scope';
 import { useVisualDialog } from '../../visuals';
+import { HostMenuItems } from '../HostMenuItems';
 import { VisualFrame } from '../VisualFrame';
 
 /*
@@ -16,10 +17,11 @@ import { VisualFrame } from '../VisualFrame';
 export function VisualRow({ chatId, visual }: { chatId: string; visual: ChatVisual }) {
     const host = useChatHost();
     const { t } = useTranslation('agent-chat');
-    const { keyOf } = useChatScope();
+    const { id: scopeId, keyOf } = useChatScope();
     if (host.visuals === null) {
         return null;
     }
+    const extra = host.visuals.actions?.(scopeId, chatId, visual) ?? [];
     const open = (kind: 'expand' | 'remove'): void => useVisualDialog.getState().open(keyOf(chatId), visual.id, kind);
     return (
         <ErrorBoundary label={t('visuals.renderFailed')} resetKeys={[visual]} compact className="relative rounded-lg">
@@ -35,6 +37,8 @@ export function VisualRow({ chatId, visual }: { chatId: string; visual: ChatVisu
                         <Menu.Root>
                             <IconButton icon={Ellipsis} size="sm" label={t('visuals.more')} render={<Menu.Trigger />} />
                             <Menu.Popup align="end">
+                                <HostMenuItems actions={extra} />
+                                {extra.length > 0 && <Menu.Separator />}
                                 <Menu.Item onClick={() => open('remove')}>
                                     <Icon icon={Trash2} size={14} /> {t('visuals.remove')}
                                 </Menu.Item>

package/src/chat/ui/rows/row-rhythm.ts

@@ -7,13 +7,15 @@ export const FOLLOW_THRESHOLD_PX = 40;
 
 /*
  * The gaps a row wears for where it sits: a question is followed by its answer gap, and a seam where
- * the list rhythm of tool lines meets the block rhythm of prose gets the block gap. A visual has no
- * margin of its own like prose does, so the row under one takes the block gap too. A question
- * already carries the gap before it, and the row after one is the answer, so neither takes a seam.
+ * the list rhythm of tool lines meets the block rhythm of prose gets the block gap. A visual and an
+ * app's card have no margin of their own like prose does, so the row under one takes the block gap
+ * too. A question already carries the gap before it, and the row after one is the answer, so neither
+ * takes a seam.
  */
 export function rowRhythm(row: TimelineRow, previous: TimelineRow | null): string {
     const question = row.kind === 'user';
-    const seam = !question && previous !== null && previous.kind !== 'user' && (isBlock(row) !== isBlock(previous) || previous.kind === 'visual');
+    const bare = previous?.kind === 'visual' || previous?.kind === 'app-card';
+    const seam = !question && previous !== null && previous.kind !== 'user' && (isBlock(row) !== isBlock(previous) || bare);
     return clsx(question && 'pb-(--chat-answer-gap)', seam && 'pt-(--chat-block-gap)');
 }
 

package/src/host.ts

@@ -2,9 +2,11 @@ import { createContext, createElement, useContext, useState, type ComponentProps
 import type { Extension } from '@codemirror/state';
 import type { EditorView } from '@codemirror/view';
 import type { Highlighter, ThemeRegistration } from 'shiki';
+import type { LucideIcon } from 'lucide-react';
 import type { EditorEngine } from '@adecore/editor';
 import type {
     AgentKind,
+    ChatAttachment,
     ChatCheckpointDiff,
     ChatConfigurePayload,
     ChatGoalAction,
@@ -15,6 +17,7 @@ import type {
     ChatUiQueryReading,
     ChatUiLinkPayload,
     ChatUiLinkReading,
+    ChatVisual,
     ProviderPlatform
 } from '@adecore/agent-contracts';
 import { isApplePlatform } from '@adecore/ui';
@@ -188,6 +191,19 @@ export interface VisualHost {
     frameUrl: string;
     /* Opens an http or https link a person followed in a visual, outside the app. */
     openLink(url: string): void;
+    /* Actions of the app's own in a visual's menu, above Remove; left out, the menu holds Remove alone. */
+    actions?(scopeId: string, chatId: string, visual: ChatVisual): readonly HostMenuAction[];
+}
+
+/* An action of the app's own in the menu of something a chat made, such as keeping a copy somewhere of the app's. */
+export interface HostMenuAction {
+    /* Unique among the actions of one menu. */
+    id: string;
+    label: string;
+    icon?: LucideIcon;
+    disabled?: boolean;
+    /* Runs once a person picks it; the host shows a failure itself. */
+    run(): void;
 }
 
 /* Who writes a chat's replies, as the header over each one names them. */
@@ -329,6 +345,8 @@ export interface ChatHost {
          * Resolves with the path as a file link opens it, or null when the person cancels; left out, a generated image offers no Save.
          */
         saveToProject?(scopeId: string, chatId: string, attachmentId: string, suggestedName: string): Promise<string | null>;
+        /* Actions of the app's own in a generated image's menu, after the chat's own; left out, the menu holds those alone. */
+        actions?(scopeId: string, chatId: string, attachment: ChatAttachment): readonly HostMenuAction[];
     };
     /* The image a tool read, drawn under its row; null draws none. */
     ReadImage: ComponentType<{ path: string }> | null;

package/src/index.ts

@@ -12,6 +12,7 @@ export {
     type SubagentSlotProps,
     type ThreadCard,
     type VisualHost,
+    type HostMenuAction,
     type ReplyAuthor,
     type ChatHost,
     type UiMapSource,