@adecore/agents-react 0.17.0-beta.1 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agents-react",
-  "version": "0.17.0-beta.1",
+  "version": "0.17.0",
   "description": "React agent chat threads, composers, approvals, provider accounts and usage views.",
   "type": "module",
   "exports": {
@@ -184,6 +184,11 @@
       "types": "./dist/chat/logic/tools.d.ts",
       "default": "./dist/chat/logic/tools.js"
     },
+    "./chat/logic/visual-height": {
+      "source": "./src/chat/logic/visual-height.ts",
+      "types": "./dist/chat/logic/visual-height.d.ts",
+      "default": "./dist/chat/logic/visual-height.js"
+    },
     "./chat/logic/welcome": {
       "source": "./src/chat/logic/welcome.ts",
       "types": "./dist/chat/logic/welcome.d.ts",
@@ -269,6 +274,16 @@
       "types": "./dist/chat/timeline-scroll.d.ts",
       "default": "./dist/chat/timeline-scroll.js"
     },
+    "./chat/visual-bridge": {
+      "source": "./src/chat/visual-bridge.ts",
+      "types": "./dist/chat/visual-bridge.d.ts",
+      "default": "./dist/chat/visual-bridge.js"
+    },
+    "./chat/visuals": {
+      "source": "./src/chat/visuals.ts",
+      "types": "./dist/chat/visuals.d.ts",
+      "default": "./dist/chat/visuals.js"
+    },
     "./chat/ui/AccountPill": {
       "source": "./src/chat/ui/AccountPill.tsx",
       "types": "./dist/chat/ui/AccountPill.d.ts",
@@ -419,6 +434,16 @@
       "types": "./dist/chat/ui/UploadThumb.d.ts",
       "default": "./dist/chat/ui/UploadThumb.js"
     },
+    "./chat/ui/VisualDialogs": {
+      "source": "./src/chat/ui/VisualDialogs.tsx",
+      "types": "./dist/chat/ui/VisualDialogs.d.ts",
+      "default": "./dist/chat/ui/VisualDialogs.js"
+    },
+    "./chat/ui/VisualFrame": {
+      "source": "./src/chat/ui/VisualFrame.tsx",
+      "types": "./dist/chat/ui/VisualFrame.d.ts",
+      "default": "./dist/chat/ui/VisualFrame.js"
+    },
     "./chat/ui/Welcome": {
       "source": "./src/chat/ui/Welcome.tsx",
       "types": "./dist/chat/ui/Welcome.d.ts",
@@ -549,6 +574,11 @@
       "types": "./dist/chat/ui/rows/TaskRow.d.ts",
       "default": "./dist/chat/ui/rows/TaskRow.js"
     },
+    "./chat/ui/rows/VisualRow": {
+      "source": "./src/chat/ui/rows/VisualRow.tsx",
+      "types": "./dist/chat/ui/rows/VisualRow.d.ts",
+      "default": "./dist/chat/ui/rows/VisualRow.js"
+    },
     "./chat/ui/rows/WorkRows": {
       "source": "./src/chat/ui/rows/WorkRows.tsx",
       "types": "./dist/chat/ui/rows/WorkRows.d.ts",
@@ -569,6 +599,11 @@
       "types": "./dist/chat/ui/useToggleSet.d.ts",
       "default": "./dist/chat/ui/useToggleSet.js"
     },
+    "./chat/ui/visual-theme": {
+      "source": "./src/chat/ui/visual-theme.ts",
+      "types": "./dist/chat/ui/visual-theme.d.ts",
+      "default": "./dist/chat/ui/visual-theme.js"
+    },
     "./host": {
       "source": "./src/host.ts",
       "types": "./dist/host.d.ts",
@@ -848,7 +883,7 @@
     "@lezer/highlight": "^1.2.3",
     "@lezer/markdown": "^1.7.2",
     "@pierre/diffs": "^1.4.3",
-    "@adecore/agent-contracts": "0.17.0-beta.1",
+    "@adecore/agent-contracts": "0.17.0",
     "@tanstack/react-virtual": "^3.14.13",
     "clsx": "^2.1.1",
     "lucide-react": "^1.47.0",
@@ -861,7 +896,7 @@
     "zustand": "^5.0.15"
   },
   "peerDependencies": {
-    "@adecore/ui": "^0.17.0-beta.1",
+    "@adecore/ui": "^0.17.0",
     "i18next": "^26.4.2",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",

package/src/chat/chat-client.ts

@@ -5,6 +5,7 @@ import type {
     ChatBookmark,
     ChatPreferencesPayload,
     ChatSkill,
+    ChatVisual,
     ModelSelection,
     ProviderInfo,
     RuntimeMode
@@ -78,6 +79,7 @@ export class ChatClient {
             // Every chat on the machine, attached or not, so a node waiting on a person says so on a view nobody has open.
             transport.on('chat.status', ({ chatId, info }) => this.sink.status(chatId, info)),
             transport.on('chat.bookmarks', ({ chatId, bookmarks }) => this.sink.bookmarks(chatId, bookmarks)),
+            transport.on('chat.visuals', ({ chatId, visuals }) => this.sink.visuals(chatId, visuals)),
             transport.subscribeStatus((status) => this.onStatus(status))
         );
         if (transport.status === 'open') {
@@ -192,6 +194,12 @@ export class ChatClient {
         return bookmarks;
     }
 
+    /* Takes a visual and its page out of the chat for good; the list every client of the chat holds comes back as `chat.visuals`. */
+    async removeVisual(chatId: string, visualId: string): Promise<ChatVisual[]> {
+        const { visuals } = await this.transport.request('chat.removeVisual', { chatId, visualId });
+        return visuals;
+    }
+
     /* What this chat's CLI would run as a skill, for the composer's `$` picker. */
     async listSkills(chatId: string): Promise<ChatSkill[]> {
         const { skills } = await this.transport.request('skills.list', { chatId });
@@ -321,8 +329,9 @@ export class ChatClient {
             const page = result.history === undefined ? undefined : { history: result.history, pending: result.pending ?? [] };
             this.sink.reset(chatId, result.info, result.items, page);
         }
-        // A host without bookmarks sends none, and then this chat has none.
+        // A host without bookmarks or visuals sends none, and then this chat has none.
         this.sink.bookmarks(chatId, result.bookmarks ?? []);
+        this.sink.visuals(chatId, result.visuals ?? []);
     }
 
     private sendPreferences(): void {

package/src/chat/logic/ansi.ts

@@ -144,8 +144,8 @@ function applyRendition(state: AnsiState, parameters: string): AnsiState {
 
 function styleOf(state: AnsiState): CSSProperties {
     const style: CSSProperties = {};
-    const color = state.inverse ? (state.background ?? 'var(--term-bg)') : state.foreground;
-    const background = state.inverse ? (state.foreground ?? 'var(--term-fg)') : state.background;
+    const color = state.inverse ? (state.background ?? 'var(--chat-code-bg)') : state.foreground;
+    const background = state.inverse ? (state.foreground ?? 'var(--chat-output)') : state.background;
     if (color !== undefined || state.dim) {
         style.color = state.dim ? `color-mix(in srgb, ${color ?? 'currentColor'} 65%, transparent)` : color;
     }

package/src/chat/logic/fork.ts

@@ -128,6 +128,8 @@ export function turnIdOfRow(row: TimelineRow): string | null {
             return row.tool.turnId;
         case 'work-group':
             return row.tools[0]?.turnId ?? null;
+        case 'visual':
+            return row.visual.turnId ?? null;
         case 'user':
         case 'assistant':
         case 'thinking':

package/src/chat/logic/thread-cards.ts

@@ -1,10 +1,18 @@
+import type { ChatVisual } from '@adecore/agent-contracts';
 import type { ThreadCard } from '../../host';
 import type { TimelineRow } from './timeline';
 
+/* A row that belongs to a moment rather than to an item of the thread: an app's card, or a visual an agent published. */
+export interface TimedRow {
+    /* In milliseconds on the clock of a chat item's `createdAt`. */
+    at: number;
+    row: TimelineRow;
+}
+
 /*
  * When what a row shows began, or null for a row that only follows the one before it: a turn's
- * changed files and forks, a note, a report. The working row closes the thread, so every card goes
- * above it.
+ * changed files and forks, a note, a report. The working row closes the thread, so every timed row
+ * goes above it.
  */
 function rowTime(row: TimelineRow): number | null {
     switch (row.kind) {
@@ -32,33 +40,58 @@ function rowTime(row: TimelineRow): number | null {
 }
 
 /* Prefixed, so a card never shares a key with a row of the chat's own. */
-function cardRow(card: ThreadCard): TimelineRow {
-    return { kind: 'app-card', id: `app-card-${card.id}`, card };
+export function cardRows(cards: readonly ThreadCard[]): TimedRow[] {
+    return cards.map((card) => ({ at: card.at, row: { kind: 'app-card', id: `app-card-${card.id}`, card } }));
 }
 
 /*
- * The thread's rows with an app's cards among them: a card goes right before the first row that
- * began after it, so in a folded turn it lands under the fold, and in an open one between its calls.
- * Without cards the rows come back as they are, the same array.
+ * The visuals as rows, keyed apart from the chat's own rows. `heldFrom` is when the first item this
+ * client holds began, while there is a page before it: a visual from before then belongs to that
+ * page and waits for it, rather than stacking up at the top of the thread.
  */
-export function withThreadCards(rows: TimelineRow[], cards: readonly ThreadCard[]): TimelineRow[] {
-    if (cards.length === 0) {
+export function visualRows(visuals: readonly ChatVisual[], heldFrom: number | null = null): TimedRow[] {
+    return visuals
+        .filter((visual) => heldFrom === null || visual.at >= heldFrom)
+        .map((visual) => ({ at: visual.at, row: { kind: 'visual', id: `visual-${visual.id}`, visual } }));
+}
+
+/*
+ * The thread's rows with timed rows among them: each goes right before the first row that began after
+ * it, so in a folded turn it lands under the fold, above the answer that closed the turn, and in an
+ * open one between its calls. Rows of the same moment keep the order they were handed in. Without
+ * timed rows the rows come back as they are, the same array.
+ */
+export function withTimedRows(rows: TimelineRow[], timed: readonly TimedRow[]): TimelineRow[] {
+    if (timed.length === 0) {
         return rows;
     }
-    // Sorting is stable, so cards of the same moment keep the order the app gave them.
-    const pending = [...cards].sort((first, second) => first.at - second.at);
+    // Sorting is stable, which is what keeps rows of the same moment in the order they came.
+    const pending = [...timed].sort((first, second) => first.at - second.at);
     const merged: TimelineRow[] = [];
     let next = 0;
     for (const row of rows) {
         const time = rowTime(row);
         while (time !== null && next < pending.length && pending[next]!.at < time) {
-            merged.push(cardRow(pending[next]!));
+            merged.push(pending[next]!.row);
             next += 1;
         }
         merged.push(row);
     }
     for (; next < pending.length; next++) {
-        merged.push(cardRow(pending[next]!));
+        merged.push(pending[next]!.row);
     }
     return merged;
 }
+
+/*
+ * What goes among a thread's rows by its moment: the visuals, then the app's cards, so a visual comes
+ * first among rows of the same moment. `visuals` is null where the host draws none.
+ */
+export function timedRowsOf(cards: readonly ThreadCard[], visuals: readonly ChatVisual[] | null, heldFrom: number | null = null): TimedRow[] {
+    return [...(visuals === null ? [] : visualRows(visuals, heldFrom)), ...cardRows(cards)];
+}
+
+/* The thread's rows with an app's cards among them, the way `withTimedRows` places them. */
+export function withThreadCards(rows: TimelineRow[], cards: readonly ThreadCard[]): TimelineRow[] {
+    return withTimedRows(rows, cardRows(cards));
+}

package/src/chat/logic/timeline.ts

@@ -10,6 +10,7 @@ import type {
     ChatToolItem,
     ChatTurnItem,
     ChatUserItem,
+    ChatVisual,
     ChatWorkflow
 } from '@adecore/agent-contracts';
 import { abortedByMachine } from '@adecore/agent-contracts';
@@ -55,7 +56,9 @@ export type TimelineRow =
     | { kind: 'forks'; id: string; turnId: string }
     | { kind: 'working'; id: string; startedAt: number }
     // A card of the app's own (`thread-cards.ts`), never derived from an item.
-    | { kind: 'app-card'; id: string; card: ThreadCard };
+    | { kind: 'app-card'; id: string; card: ThreadCard }
+    // A page an agent published, placed by when it was published (`thread-cards.ts`), never derived from an item.
+    | { kind: 'visual'; id: string; visual: ChatVisual };
 
 interface TimelineOptions {
     expandedGroups: ReadonlySet<string>;
@@ -71,7 +74,7 @@ interface TimelineOptions {
  * against each other; prose and cards are blocks and need room around them. Where the two meet,
  * the block gap marks the seam, so an answer never looks glued to the call above it.
  */
-const BLOCK_KINDS = new Set<TimelineRow['kind']>(['assistant', 'report', 'thinking', 'changed-files', 'compaction', 'app-card']);
+const BLOCK_KINDS = new Set<TimelineRow['kind']>(['assistant', 'report', 'thinking', 'changed-files', 'compaction', 'app-card', 'visual']);
 
 export function isBlock(row: TimelineRow): boolean {
     return BLOCK_KINDS.has(row.kind);

package/src/chat/logic/visual-height.ts

@@ -0,0 +1,38 @@
+import { VISUAL_LIMITS, visualFrameHeight, type ChatVisual } from '@adecore/agent-contracts/visual';
+
+/* A frame before anything measured its page: room for a chart, never taller than the page may grow. */
+const DEFAULT_HEIGHT_PX = 240;
+/* Plenty for the visuals of a long session; the oldest goes first. */
+const REMEMBERED_HEIGHTS = 500;
+
+/*
+ * The heights frames reported, by visual and width. The thread draws only the rows in view, so a row
+ * that scrolls back in mounts a new frame, which starts at the height its page had there before.
+ */
+const remembered = new Map<string, number>();
+
+function keyOf(visualId: string, width: number): string {
+    return `${visualId}@${Math.round(width)}`;
+}
+
+/* A height a page reported, held to the visual's own maximum and the limits, in whole pixels. */
+export function clampVisualHeight(visual: Pick<ChatVisual, 'maxHeight'>, height: number): number {
+    return Math.min(Math.max(Math.ceil(Math.min(height, visual.maxHeight)), VISUAL_LIMITS.minHeight), VISUAL_LIMITS.maxHeight);
+}
+
+/*
+ * The height a frame `width` CSS pixels wide starts at: what the page reported in a frame that wide
+ * before, else what the host measured, else a modest default.
+ */
+export function initialVisualHeight(visual: Pick<ChatVisual, 'id' | 'maxHeight' | 'heights'>, width: number): number {
+    return remembered.get(keyOf(visual.id, width)) ?? visualFrameHeight(visual, width) ?? clampVisualHeight(visual, DEFAULT_HEIGHT_PX);
+}
+
+export function rememberVisualHeight(visualId: string, width: number, height: number): void {
+    const key = keyOf(visualId, width);
+    remembered.delete(key);
+    remembered.set(key, height);
+    if (remembered.size > REMEMBERED_HEIGHTS) {
+        remembered.delete(remembered.keys().next().value!);
+    }
+}

package/src/chat/ui/Scrubber.tsx

@@ -198,10 +198,7 @@ export const Scrubber = memo(function Scrubber({
                                     {slot.found && (
                                         <span
                                             aria-hidden
-                                            className={clsx(
-                                                'absolute right-0 rounded-full bg-find-current',
-                                                index === currentSlot ? 'opacity-100' : 'opacity-50'
-                                            )}
+                                            className={clsx('absolute right-0 rounded-full bg-chat-find', index === currentSlot ? 'opacity-100' : 'opacity-50')}
                                             style={{ top: slot.y, height: TICK_HEIGHT_PX, width: FOUND_WIDTH_PX }}
                                         />
                                     )}

package/src/chat/ui/Timeline.tsx

@@ -7,7 +7,7 @@ import type { ChatBookmark } from '@adecore/agent-contracts';
 import { useForkedTurns } from '../forks';
 import { bookmarkRows } from '../logic/bookmarks';
 import { deriveTimelineRows, findSubagentBranch, type TimelineRow } from '../logic/timeline';
-import { withThreadCards } from '../logic/thread-cards';
+import { timedRowsOf, withTimedRows } from '../logic/thread-cards';
 import { openFromMain, useSubagentTrail, type SubagentStep } from '../subagent-view';
 import {
     registerItemJumper,
@@ -38,6 +38,7 @@ import { BookmarkMarker } from './BookmarkMarker';
 import { MessageActions } from './MessageActions';
 import { Scrubber, type CardChat } from './Scrubber';
 import { TimelineMenuPopup } from './TimelineMenu';
+import { VisualDialogs } from './VisualDialogs';
 import { FOLLOW_THRESHOLD_PX, replyHeader, rowRhythm } from './rows/row-rhythm';
 import { QuoteButton } from './QuoteButton';
 import { QuoteTakerContext, type QuoteTaker } from './quote-selection';
@@ -123,6 +124,7 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
     const items = useChatRow(chatId, (row) => row?.structure);
     const activeTurnId = useChatRow(chatId, (row) => row?.info.activeTurnId ?? null);
     const bookmarks = useChatRow(chatId, (row) => row?.bookmarks);
+    const visuals = useChatRow(chatId, (row) => row?.visuals);
     const forkedTurns = useForkedTurns(chatId);
     const info = useChatRow(chatId, (row) => row?.info ?? null);
     const cursor = useChatRow(chatId, (row) => row?.history?.cursor ?? null);
@@ -188,7 +190,13 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
         );
     }, [order, items, groups.ids, turns.ids, subagents.ids, activeTurnId, forkedTurns]);
     const cards = chatHost().useThreadCards(scopeId, chatId);
-    const rows = useMemo(() => withThreadCards(threadRows, cards), [threadRows, cards]);
+    const drawsVisuals = chatHost().visuals !== null;
+    // Where the part of the thread this client holds begins, while there is a page before it.
+    const heldFrom = cursor === null ? null : (items?.[order?.[0] ?? '']?.createdAt ?? null);
+    const rows = useMemo(
+        () => withTimedRows(threadRows, timedRowsOf(cards, drawsVisuals ? (visuals ?? []) : null, heldFrom)),
+        [threadRows, cards, drawsVisuals, visuals, heldFrom]
+    );
     const welcomes = chatHost().useWelcome(chatId);
 
     const empty = rows.length === 0;
@@ -596,6 +604,7 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
                     </div>
                     <TimelineMenuPopup target={target} thread={threadRef} chatId={onMainAgent ? chatId : null} />
                 </ContextMenu.Root>
+                {drawsVisuals && <VisualDialogs chatId={chatId} />}
                 {loadingEarlier && !overlay && (
                     <div className="pointer-events-none absolute inset-x-0 top-3 z-10 flex justify-center" role="status">
                         <Icon icon={LoaderCircle} size={16} className="animate-spin text-text-faint" />

package/src/chat/ui/UnifiedDiff.tsx

@@ -35,10 +35,10 @@ pre > [data-code] { flex-grow: 1; align-self: stretch; align-content: start; }
 
 function lineClass(line: string): string {
     if (line.startsWith('+')) {
-        return 'text-term-green';
+        return 'text-chat-added';
     }
     if (line.startsWith('-')) {
-        return 'text-term-red';
+        return 'text-chat-removed';
     }
     return 'text-text-muted';
 }

package/src/chat/ui/VisualDialogs.tsx

@@ -0,0 +1,64 @@
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import type { ChatVisual } from '@adecore/agent-contracts';
+import { CloseButton, Dialog, ErrorBoundary, PromptDialog } from '@adecore/ui';
+import { useChatScope } from '../../scope';
+import { useChatRow } from '../../state/chats';
+import { useVisualDialog } from '../visuals';
+import { VisualFrame } from './VisualFrame';
+
+/*
+ * The large view of one of the chat's visuals and the question before one goes, opened from its row.
+ * A visual that goes while either is up closes it. Removing cannot be undone: the page is deleted.
+ */
+export function VisualDialogs({ chatId }: { chatId: string }) {
+    const { t } = useTranslation('agent-chat');
+    const scope = useChatScope();
+    const key = scope.keyOf(chatId);
+    const kind = useVisualDialog((s) => (s.chatKey === key ? s.kind : null));
+    const visualId = useVisualDialog((s) => (s.chatKey === key ? s.visualId : null));
+    const visual = useChatRow(chatId, (row) => (visualId === null ? null : (row?.visuals?.find((candidate) => candidate.id === visualId) ?? null)));
+    // The dialog fades out after it closes, and draws what it showed until then.
+    const [shown, setShown] = useState<ChatVisual | null>(visual);
+    if (visual !== null && visual !== shown) {
+        setShown(visual);
+    }
+    const close = (): void => useVisualDialog.getState().close();
+
+    return (
+        <>
+            <Dialog.Root open={kind === 'expand' && visual !== null} onOpenChange={(next) => !next && close()}>
+                <Dialog.Popup className="flex h-[calc(100dvh-96px)] w-[1200px] flex-col overflow-hidden">
+                    <div className="flex h-11 shrink-0 items-center gap-2 border-b border-border pr-2 pl-4">
+                        <Dialog.Title className="min-w-0 grow truncate">{shown?.title}</Dialog.Title>
+                        <CloseButton label={t('common.action.close')} kbd="esc" dialog />
+                    </div>
+                    <div className="min-h-0 grow p-5">
+                        <div className="relative size-full">
+                            {shown !== null && (
+                                <ErrorBoundary label={t('visuals.renderFailed')} resetKeys={[shown]}>
+                                    <VisualFrame chatId={chatId} visual={shown} fill />
+                                </ErrorBoundary>
+                            )}
+                        </div>
+                    </div>
+                </Dialog.Popup>
+            </Dialog.Root>
+            <PromptDialog
+                open={kind === 'remove' && visual !== null}
+                title={t('visuals.removeTitle')}
+                description={t('visuals.removeDescription', { title: shown?.title ?? '' })}
+                confirmLabel={t('common.action.remove')}
+                danger
+                fallbackMessage={t('visuals.removeFailed')}
+                onConfirm={async () => {
+                    if (visualId !== null) {
+                        await scope.chats.removeVisual(chatId, visualId);
+                    }
+                    close();
+                }}
+                onOpenChange={close}
+            />
+        </>
+    );
+}

package/src/chat/ui/VisualFrame.tsx

@@ -0,0 +1,136 @@
+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 { Spinner, useMeasuredWidth } from '@adecore/ui';
+import { chatHost } from '../../host';
+import { useChatScope } from '../../scope';
+import { initialVisualHeight, rememberVisualHeight } from '../logic/visual-height';
+import { VisualBridge } from '../visual-bridge';
+import { useVisualTheme } from './visual-theme';
+
+export interface VisualFrameProps {
+    chatId: string;
+    visual: ChatVisual;
+    /* Fills its positioned parent and lets the page scroll inside it, rather than taking the height the page reports. */
+    fill?: boolean;
+    className?: string;
+}
+
+/*
+ * 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
+ * the page loads, and not one opened while a person works in the frame.
+ */
+function personActsIn(frame: HTMLIFrameElement): boolean {
+    return frame.ownerDocument.activeElement === frame && navigator.userActivation?.isActive !== false;
+}
+
+/*
+ * One visual's page in a frame on the thread's own ground. The frame loads the app's sandbox host
+ * page and 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 the page loads and when it fails, so nothing under it moves.
+ */
+export function VisualFrame({ chatId, visual, fill = false, className }: VisualFrameProps) {
+    const { t } = useTranslation('agent-chat');
+    const scope = useChatScope();
+    const frameUrl = chatHost().visuals?.frameUrl ?? null;
+    const boxRef = useRef<HTMLDivElement | null>(null);
+    const frameRef = useRef<HTMLIFrameElement>(null);
+    const bridgeRef = useRef<VisualBridge | null>(null);
+    const [measure, width] = useMeasuredWidth();
+    const setBox = useCallback(
+        (node: HTMLDivElement | null) => {
+            boxRef.current = node;
+            measure(node);
+        },
+        [measure]
+    );
+    const theme = useVisualTheme(boxRef);
+    const widthRef = useRef(width);
+    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);
+    const [failed, setFailed] = useState(false);
+    // The frame keeps the address it opened with: a later theme goes over the bridge, since a new address would load the page again.
+    const [opening, setOpening] = useState<{ src: string; theme: VisualTheme } | null>(null);
+    if (opening === null && frameUrl !== null && theme !== null && width > 0) {
+        setOpening({ src: frameUrl + visualThemeFragment(theme), theme });
+    }
+    const height = fill || width === 0 ? undefined : (reported ?? initialVisualHeight(visual, width));
+
+    useLayoutEffect(() => {
+        widthRef.current = width;
+    }, [width]);
+
+    useLayoutEffect(() => {
+        const frame = frameRef.current;
+        if (opening === null || frame === null) {
+            return;
+        }
+        const bridge = new VisualBridge({
+            frame: () => frame.contentWindow,
+            visual: { maxHeight: visual.maxHeight },
+            page: chatHost()
+                .attachments.read(scope.id, chatId, visual.id)
+                .then((blob) => blob.text()),
+            theme: opening.theme,
+            mayOpenLink: () => personActsIn(frame),
+            openLink: (url) => chatHost().visuals?.openLink(url),
+            onHeight: (next) => {
+                if (fill) {
+                    return;
+                }
+                setReported(next);
+                rememberVisualHeight(visual.id, widthRef.current, next);
+            },
+            onAppearance: setDrawn,
+            onFailure: () => setFailed(true)
+        });
+        bridgeRef.current = bridge;
+        const view = frame.ownerDocument.defaultView ?? window;
+        const listen = (event: MessageEvent): void => bridge.receive(event);
+        view.addEventListener('message', listen);
+        return () => {
+            view.removeEventListener('message', listen);
+            bridge.dispose();
+            bridgeRef.current = null;
+        };
+    }, [opening, scope.id, chatId, visual.id, visual.maxHeight, fill]);
+
+    useEffect(() => {
+        if (theme !== null) {
+            bridgeRef.current?.setTheme(theme);
+        }
+    }, [theme]);
+
+    return (
+        <div ref={setBox} className={clsx(fill ? 'absolute inset-0' : 'relative w-full', className)} style={{ height }}>
+            {opening !== null && (
+                <iframe
+                    ref={frameRef}
+                    src={opening.src}
+                    title={visual.title}
+                    loading="lazy"
+                    sandbox="allow-scripts allow-forms"
+                    className={clsx('block size-full border-0', failed && 'invisible')}
+                    // A frame whose color scheme differs from its document's paints an opaque ground behind it.
+                    style={{ colorScheme: drawn ?? 'normal' }}
+                    onLoad={() => bridgeRef.current?.loaded()}
+                />
+            )}
+            {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>
+            ) : (
+                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 })} />
+                    </span>
+                )
+            )}
+        </div>
+    );
+}

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

@@ -6,6 +6,7 @@ import type { SubagentStep } from '../../subagent-view';
 import { AgentTurnRow, ApprovalHistoryRow, AssistantRow, CompactionRow, NoteRow, QuestionHistoryRow, ReportRow, ThinkingRow, UserRow } from './MessageRows';
 import { ForksRow } from './ForksRow';
 import { SubagentBranchRow } from './SubagentRow';
+import { VisualRow } from './VisualRow';
 import { WorkflowRow } from './WorkflowRow';
 import { ChangedFilesRow, TurnFoldRow, WorkGroupRow, WorkLiveRow, WorkRow, WorkingRow } from './WorkRows';
 
@@ -77,5 +78,7 @@ export function Row({ row, chatId, toggleGroup, toggleTurn, toggleSubagent, open
             return <WorkingRow startedAt={row.startedAt} />;
         case 'app-card':
             return <AppCardRow card={row.card} />;
+        case 'visual':
+            return <VisualRow chatId={chatId} visual={row.visual} />;
     }
 }