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

package/LICENSE

@@ -6,7 +6,7 @@ FSL-1.1-MIT
 
 ## Notice
 
-Copyright 2026 Bas Milius
+Copyright 2026 - present Bas Milius
 
 ## Terms and Conditions
 

package/README.md

@@ -1,53 +1,61 @@
 # @adecore/agents-react
 
-React agent chat threads, a CodeMirror composer, approvals/questions, provider account settings, and usage views. The host supplies a typed connection and adapters for files, permissions, login, task state, and navigation. Backend provider execution stays outside the browser.
+[![npm](https://img.shields.io/npm/v/@adecore/agents-react)](https://www.npmjs.com/package/@adecore/agents-react)
+[![Docs](https://img.shields.io/badge/docs-adecore.dev-blue)](https://adecore.dev/agents-react/)
 
-Import per module. There is no root barrel:
+React views for agent chats: the thread, the composer, approvals and questions, the agent CLIs and their accounts, and what they cost. They talk to a host of chats, such as [`@adecore/agents`](https://adecore.dev/agents/), over the requests of [`@adecore/agent-contracts`](https://adecore.dev/agent-contracts/). Built on React 19, [`@adecore/ui`](https://adecore.dev/ui/) and Tailwind 4.
 
-```tsx
-import { Composer } from '@adecore/agents-react/chat/ui/Composer';
-import { Timeline } from '@adecore/agents-react/chat/ui/Timeline';
-import { ChatClient } from '@adecore/agents-react/chat/chat-client';
-import { portTransport } from '@adecore/agents-react/port-transport';
+**[Documentation with live demos](https://adecore.dev/agents-react/)**
+
+## Install
 
-export const agentViews = { Composer, Timeline, ChatClient, portTransport };
+```sh
+bun add @adecore/agents-react @adecore/agent-contracts
 ```
 
-The host brings React/React DOM 19, i18next, react-i18next, and `@adecore/ui` as peers. The package depends on `@adecore/agent-contracts` and uses Zustand, CodeMirror, Shiki, and the diff library. Consult the manifest for exact peer ranges. Import `@adecore/ui/theme.css` before `@adecore/agents-react/theme.css`; use Tailwind 4, scan linked `src` or compiled `dist`, and load the typography plugin. Terminal/find colors need host tokens and utility mappings.
+`@adecore/ui`, React 19, `react-dom`, `i18next` and `react-i18next` are peer dependencies.
 
-Configure `setChatHost({ storage })` before any persistent store use. A `ChatScopeContext` supplies one stable transport/client per backend. The host singleton and persistence configuration are shared across scopes. Use unique chat IDs across scopes because drafts use raw IDs. `portTransport.close()` rejects waiting requests and stops frame listening; the owner also closes its native port. `ChatClient.dispose()` releases subscriptions and detaches views without stopping agents.
+## Set up
 
-## Documentation
+Import the theme after the one of `@adecore/ui`, let Tailwind scan the package, and load the typography plugin. The `@source` path is relative to the CSS file.
 
-- [Overview](../../docs/agents-react/index.md)
-- [Installation and setup](../../docs/agents-react/getting-started.md)
-- [Host adapters](../../docs/agents-react/host.md)
-- [Chat state and lifecycle](../../docs/agents-react/chat-lifecycle.md)
-- [Composer](../../docs/agents-react/composer.md)
-- [Attachments and mentions](../../docs/agents-react/attachments.md)
-- [Messages and timeline](../../docs/agents-react/timeline.md)
-- [Approvals and tasks](../../docs/agents-react/approvals-tasks.md)
-- [Accounts and models](../../docs/agents-react/accounts-models.md)
-- [Usage](../../docs/agents-react/usage.md)
-- [Persistence](../../docs/agents-react/persistence.md)
-- [CSS, theme, and translations](../../docs/agents-react/styling.md)
-- [Testing](../../docs/agents-react/testing.md)
-- [Migration](../../docs/agents-react/migration.md)
-- [Troubleshooting](../../docs/agents-react/troubleshooting.md)
-- [Runtime reference](../../docs/agents-react/reference-runtime.md)
-- [Chat reference](../../docs/agents-react/reference-chat.md)
-- [Settings reference](../../docs/agents-react/reference-settings.md)
+```css
+@import "tailwindcss";
+@import "@adecore/ui/theme.css";
+@import "@adecore/agents-react/theme.css";
+@plugin "@tailwindcss/typography";
+@source "../node_modules/@adecore/agents-react/dist";
+```
 
-The reference pages group all preserved module subpaths, including lower-level renderers, prompt/session helpers, account forms, and usage formatters. `DiffPool`, `EditDiff`, and `UnifiedDiff` use default exports.
+Add the words of `AGENTS_LOCALES` to your i18next, call `setChatHost` once, and render the views in a `ChatScopeContext`:
 
-## Compatibility and verification
+```tsx
+import { Composer } from '@adecore/agents-react/chat/ui/Composer';
+import { Timeline } from '@adecore/agents-react/chat/ui/Timeline';
+import { ChatScopeContext } from '@adecore/agents-react/scope';
+
+<ChatScopeContext.Provider value={scope}>
+    <Timeline chatId={chatId} composer={<Composer chatId={chatId} info={info} {...composerProps} />} />
+</ChatScopeContext.Provider>;
+```
+
+[Getting started](https://adecore.dev/agents-react/guide/getting-started) covers the words, the host, the scope and its transport.
 
-Storage keys default to `adecore.chat.drafts`, `adecore.chat.preferences`, `adecore.chat.stash`, and `adecore.usage`. Keep previous keys/namespace in place or configure ordered legacy keys to copy raw records unchanged, retaining their old copies. Setup after hydration throws. Custom synchronous storage and memory-only storage are supported; failed draft writes may omit attachment bytes. See the persistence guide for formats and cross-window listeners.
+Every module has its own subpath, `@adecore/agents-react/<path>`; there is no root import.
 
-Mention drags use `application/x-adecore-mention`. `writeMentionDrag` writes both new and transitional formats by default, and `carriesMentions`/`droppedMentions` read both. Migrate producers and receivers together before disabling legacy writes. The existing space-separated payload still cannot represent whitespace-containing paths as one token. The chat CodeMirror input is separate from the file editor.
+## Documentation
 
-`AGENTS_LOCALES` loads English/Dutch for `agent-chat`, `agent-prompts`, `agent-providers`, and `agent-usage`. Load them on the default i18next instance used by package helpers and React. `UIProvider` supplies UI words and formatter setup separately.
+| Page | What it covers |
+|---|---|
+| [Getting started](https://adecore.dev/agents-react/guide/getting-started) | Install, CSS, words, the host and a first chat |
+| [Host adapters](https://adecore.dev/agents-react/guide/host) | Everything `setChatHost` takes |
+| [Chat client and state](https://adecore.dev/agents-react/guide/chat-client) | The transport, `ChatClient` and the stores |
+| [Persistence](https://adecore.dev/agents-react/guide/persistence) | Drafts, preferences and their storage keys |
+| [Chat](https://adecore.dev/agents-react/chat/timeline) | The timeline, the composer, prompts and their parts, each with a live demo |
+| [Providers](https://adecore.dev/agents-react/providers/providers-pane) | The settings of the CLIs and their accounts |
+| [Usage](https://adecore.dev/agents-react/usage/usage-page) | Cost, charts and plan limits |
+| [Modules](https://adecore.dev/agents-react/reference) | Every subpath and its exports |
 
-Build dependencies before default-export checks. The [agent-port example](../../examples/agent-port) safely verifies `AgentHost`, a fake CLI, `FramePort`, `portTransport`, `ChatClient`, rendered scope context, locale loading, reply state, and structured refusals. `fixtures/storage.mjs` runs storage compatibility checks in a fresh process. Package typecheck/tests and source/default consumer checks are described in the testing guide.
+## License
 
-This package remains private at `0.0.0` pending publication setup. Source-condition imports support a linked checkout; default exports require built artifacts. The transferred code retains FSL-1.1-MIT; see [LICENSE](./LICENSE).
+FSL-1.1-MIT. See [LICENSE](./LICENSE).

package/dist/chat/chat-client.d.ts

@@ -1,4 +1,4 @@
-import type { AgentKind, ChatAttachmentUpload, ChatAttachResult, ChatBookmark, ChatPreferencesPayload, ChatSkill, ModelSelection, ProviderInfo, RuntimeMode } from '@adecore/agent-contracts';
+import type { AgentKind, ChatAttachmentUpload, ChatAttachResult, ChatBookmark, ChatPreferencesPayload, ChatSkill, ChatVisual, ModelSelection, ProviderInfo, RuntimeMode } from '@adecore/agent-contracts';
 import type { ChatSink } from '../state/chats.js';
 import { type ChatTransport } from '../transport.js';
 interface ChatOpenOptions {
@@ -40,6 +40,7 @@ export declare class ChatClient {
     addBookmark(chatId: string, itemId: string, name?: string): Promise<ChatBookmark[]>;
     renameBookmark(chatId: string, itemId: string, name: string): Promise<ChatBookmark[]>;
     removeBookmark(chatId: string, itemId: string): Promise<ChatBookmark[]>;
+    removeVisual(chatId: string, visualId: string): Promise<ChatVisual[]>;
     listSkills(chatId: string): Promise<ChatSkill[]>;
     clear(chatId: string, force?: boolean): Promise<void>;
     kill(chatId: string): Promise<void>;

package/dist/chat/chat-client.js

@@ -28,7 +28,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.subscribeStatus((status) => this.onStatus(status)));
+        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') {
             void this.loadProviders();
             void this.loadStatuses();
@@ -133,6 +133,11 @@ export class ChatClient {
         const { bookmarks } = await this.transport.request('chat.removeBookmark', { chatId, itemId });
         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, visualId) {
+        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) {
         const { skills } = await this.transport.request('skills.list', { chatId });
@@ -257,8 +262,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 ?? []);
     }
     sendPreferences() {
         if (this.preferences === null) {

package/dist/chat/logic/ansi.js

@@ -125,8 +125,8 @@ function applyRendition(state, parameters) {
 }
 function styleOf(state) {
     const style = {};
-    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/dist/chat/logic/fork.js

@@ -103,6 +103,8 @@ export function turnIdOfRow(row) {
             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/dist/chat/logic/thread-cards.d.ts

@@ -1,3 +1,12 @@
+import type { ChatVisual } from '@adecore/agent-contracts';
 import type { ThreadCard } from '../../host.js';
 import type { TimelineRow } from './timeline.js';
+export interface TimedRow {
+    at: number;
+    row: TimelineRow;
+}
+export declare function cardRows(cards: readonly ThreadCard[]): TimedRow[];
+export declare function visualRows(visuals: readonly ChatVisual[], heldFrom?: number | null): TimedRow[];
+export declare function withTimedRows(rows: TimelineRow[], timed: readonly TimedRow[]): TimelineRow[];
+export declare function timedRowsOf(cards: readonly ThreadCard[], visuals: readonly ChatVisual[] | null, heldFrom?: number | null): TimedRow[];
 export declare function withThreadCards(rows: TimelineRow[], cards: readonly ThreadCard[]): TimelineRow[];

package/dist/chat/logic/thread-cards.js

@@ -1,7 +1,7 @@
 /*
  * 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) {
     switch (row.kind) {
@@ -28,32 +28,54 @@ function rowTime(row) {
     }
 }
 /* Prefixed, so a card never shares a key with a row of the chat's own. */
-function cardRow(card) {
-    return { kind: 'app-card', id: `app-card-${card.id}`, card };
+export function cardRows(cards) {
+    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, cards) {
-    if (cards.length === 0) {
+export function visualRows(visuals, heldFrom = null) {
+    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, timed) {
+    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 = [];
     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, visuals, heldFrom = null) {
+    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, cards) {
+    return withTimedRows(rows, cardRows(cards));
+}

package/dist/chat/logic/timeline.d.ts

@@ -1,4 +1,4 @@
-import type { ChatApprovalItem, ChatAssistantItem, ChatCheckpointDiff, ChatItem, ChatQuestionItem, ChatSubagentItem, ChatThinkingItem, ChatToolItem, ChatTurnItem, ChatUserItem, ChatWorkflow } from '@adecore/agent-contracts';
+import type { ChatApprovalItem, ChatAssistantItem, ChatCheckpointDiff, ChatItem, ChatQuestionItem, ChatSubagentItem, ChatThinkingItem, ChatToolItem, ChatTurnItem, ChatUserItem, ChatVisual, ChatWorkflow } from '@adecore/agent-contracts';
 import type { ThreadCard } from '../../host.js';
 export interface SubagentBranch {
     id: string;
@@ -94,6 +94,10 @@ export type TimelineRow = {
     kind: 'app-card';
     id: string;
     card: ThreadCard;
+} | {
+    kind: 'visual';
+    id: string;
+    visual: ChatVisual;
 };
 interface TimelineOptions {
     expandedGroups: ReadonlySet<string>;

package/dist/chat/logic/timeline.js

@@ -9,7 +9,7 @@ import { hasFileChanges, isFileChange } from './tools.js';
  * 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(['assistant', 'report', 'thinking', 'changed-files', 'compaction', 'app-card']);
+const BLOCK_KINDS = new Set(['assistant', 'report', 'thinking', 'changed-files', 'compaction', 'app-card', 'visual']);
 export function isBlock(row) {
     return BLOCK_KINDS.has(row.kind);
 }

package/dist/chat/logic/visual-height.d.ts

@@ -0,0 +1,4 @@
+import { type ChatVisual } from '@adecore/agent-contracts/visual';
+export declare function clampVisualHeight(visual: Pick<ChatVisual, 'maxHeight'>, height: number): number;
+export declare function initialVisualHeight(visual: Pick<ChatVisual, 'id' | 'maxHeight' | 'heights'>, width: number): number;
+export declare function rememberVisualHeight(visualId: string, width: number, height: number): void;

package/dist/chat/logic/visual-height.js

@@ -0,0 +1,32 @@
+import { VISUAL_LIMITS, visualFrameHeight } 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();
+function keyOf(visualId, width) {
+    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, height) {
+    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, width) {
+    return remembered.get(keyOf(visual.id, width)) ?? visualFrameHeight(visual, width) ?? clampVisualHeight(visual, DEFAULT_HEIGHT_PX);
+}
+export function rememberVisualHeight(visualId, width, height) {
+    const key = keyOf(visualId, width);
+    remembered.delete(key);
+    remembered.set(key, height);
+    if (remembered.size > REMEMBERED_HEIGHTS) {
+        remembered.delete(remembered.keys().next().value);
+    }
+}

package/dist/chat/ui/Scrubber.js

@@ -112,7 +112,7 @@ export const Scrubber = memo(function Scrubber({ ticks, firstInView, lastInView,
                                 const distance = pointing && hoveredSlot !== null ? Math.abs(index - hoveredSlot) : null;
                                 // A bookmark is a place to find again from anywhere, so it never dims with the rest.
                                 const bright = slot.marked || slotInView(slot, inView) || distance === 0;
-                                return (_jsxs(Fragment, { children: [_jsx("span", { "aria-hidden": true, className: clsx('absolute left-1 rounded-full transition-[width,opacity] duration-100 ease-out motion-reduce:transition-none', slot.marked ? 'bg-accent' : slot.kind === 'wake' ? 'bg-text-muted' : 'bg-text', bright ? 'opacity-100' : 'opacity-30'), style: { top: slot.y, height: TICK_HEIGHT_PX, width: tickWidth(slot.kind, distance) } }), slot.found && (_jsx("span", { "aria-hidden": true, className: clsx('absolute right-0 rounded-full bg-find-current', index === currentSlot ? 'opacity-100' : 'opacity-50'), style: { top: slot.y, height: TICK_HEIGHT_PX, width: FOUND_WIDTH_PX } }))] }, slot.first));
+                                return (_jsxs(Fragment, { children: [_jsx("span", { "aria-hidden": true, className: clsx('absolute left-1 rounded-full transition-[width,opacity] duration-100 ease-out motion-reduce:transition-none', slot.marked ? 'bg-accent' : slot.kind === 'wake' ? 'bg-text-muted' : 'bg-text', bright ? 'opacity-100' : 'opacity-30'), style: { top: slot.y, height: TICK_HEIGHT_PX, width: tickWidth(slot.kind, distance) } }), slot.found && (_jsx("span", { "aria-hidden": true, 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 } }))] }, slot.first));
                             }) }), _jsx(PreviewCard.Popup, { anchor: anchor, side: "right", align: "center", sideOffset: 4, className: "w-72", children: hoveredTick !== null && (_jsxs(_Fragment, { children: [_jsxs("div", { className: "px-2.5 pt-1.5 pb-2", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3 text-xs text-text-faint", children: [hoveredTick.bookmark === null ? (_jsx("span", { children: hoveredTick.kind === 'person' ? t('rows.user.heading') : t('scrubber.tasks') })) : (_jsxs("span", { className: "flex min-w-0 items-center gap-1 self-center text-text-muted", children: [_jsx(Icon, { icon: Bookmark, size: 12, className: "shrink-0 text-accent" }), _jsx("span", { className: "truncate", children: hoveredTick.bookmark.name ?? t('bookmarks.unnamed') })] })), _jsx("time", { className: "tabular-nums", children: timeOf(hoveredTick.createdAt) })] }), _jsx("p", { className: "mt-1 line-clamp-4 text-sm break-words whitespace-pre-line text-text", children: hoveredTick.text.slice(0, PREVIEW_CHARS) || t('pickers.stash.noText') })] }), actions.length > 0 && (_jsxs(_Fragment, { children: [_jsx(Menu.Separator, {}), actions.map((action) => (_jsxs("button", { type: "button", className: "menu-item w-full hover:bg-surface-hover", onClick: () => action.run(hoveredTick, chat), children: [_jsx(Icon, { icon: action.icon, size: 14 }), " ", t(action.label)] }, action.label)))] }))] })) })] }) }), _jsxs(ContextMenu.Popup, { children: [menuTick !== null &&
                         actionsFor(menuTick).map((action) => (_jsxs(ContextMenu.Item, { onClick: () => action.run(menuTick, chat), children: [_jsx(Icon, { icon: action.icon, size: 14 }), " ", t(action.label)] }, action.label))), menuTick !== null && actionsFor(menuTick).length > 0 && menuMarkable !== null && _jsx(ContextMenu.Separator, {}), chat !== null && menuIndex !== null && menuMarkable !== null && (_jsx(BookmarkMenuItems, { chatId: chat.chatId, itemId: menuMarkable, onName: () => onPick(menuIndex) }))] })] }));
 });

package/dist/chat/ui/Timeline.js

@@ -7,7 +7,7 @@ import { LoaderCircle } from 'lucide-react';
 import { useForkedTurns } from '../forks.js';
 import { bookmarkRows } from '../logic/bookmarks.js';
 import { deriveTimelineRows, findSubagentBranch } from '../logic/timeline.js';
-import { withThreadCards } from '../logic/thread-cards.js';
+import { timedRowsOf, withTimedRows } from '../logic/thread-cards.js';
 import { openFromMain, useSubagentTrail } from '../subagent-view.js';
 import { registerItemJumper, registerMessageStepper, registerTimeline, registerTurnJumper, setTimelineAtEnd, wantsEarlier } from '../timeline-scroll.js';
 import { useTimelineFlash } from '../timeline-flash.js';
@@ -19,6 +19,7 @@ import { BookmarkMarker } from './BookmarkMarker.js';
 import { MessageActions } from './MessageActions.js';
 import { Scrubber } from './Scrubber.js';
 import { TimelineMenuPopup } from './TimelineMenu.js';
+import { VisualDialogs } from './VisualDialogs.js';
 import { FOLLOW_THRESHOLD_PX, replyHeader, rowRhythm } from './rows/row-rhythm.js';
 import { QuoteButton } from './QuoteButton.js';
 import { QuoteTakerContext } from './quote-selection.js';
@@ -67,6 +68,7 @@ export function Timeline({ chatId, composer, overlay }) {
     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);
@@ -127,7 +129,10 @@ export function Timeline({ chatId, composer, overlay }) {
         return deriveTimelineRows(order.map((id) => items[id]), { expandedGroups: groups.ids, expandedTurns: turns.ids, expandedSubagents: subagents.ids, activeTurnId, forkedTurns });
     }, [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;
     // A chat that took a turn before is one whose thread has not come in yet, not one to greet.
@@ -420,5 +425,5 @@ export function Timeline({ chatId, composer, overlay }) {
                                                 return (_jsxs("div", { "data-index": virtualRow.index, "data-item-id": row.id, ref: virtualizer.measureElement, className: clsx('absolute left-0 top-0 w-full', rowRhythm(row, previous), question && virtualRow.index > 0 && 'pt-(--chat-turn-gap)'), style: { transform: `translateY(${virtualRow.start}px)` }, children: [flash !== null && flash.key === keyOf(chatId) && flash.rowId === row.id && (_jsx("span", { className: "chat-flash pointer-events-none absolute inset-0 rounded-lg", "aria-hidden": true }, flash.nonce)), header !== null && _jsx(ReplyHeader, { chatId: chatId, at: header.at }), _jsx(FindRevealContext.Provider, { value: chatFind.reveal, children: _jsx(MarkableRow, { row: row, chatId: chatId, bookmark: marks.get(row.id) ?? null, children: _jsx(Row, { row: row, chatId: chatId, toggleGroup: groups.toggle, toggleTurn: turns.toggle, toggleSubagent: subagents.toggle, openSubagent: openSubagent, openConversation: openConversation }) }) })] }, row.id));
                                             }) })) }), _jsx(QuoteButton, { thread: threadRef, frame: contentRef, taker: quoteTakerRef }), _jsx("div", { ref: composerRef, 
                                         // The card is translucent so the thread shows through it, but the pb-3 strip under it must stay opaque.
-                                        className: clsx('relative z-10 shrink-0', composer && 'px-3 pb-3 pt-3 bg-[linear-gradient(to_bottom,transparent_calc(100%-12px),var(--surface)_calc(100%-12px))]'), style: { position: stickyComposer ? 'sticky' : 'relative', bottom: 0 }, children: _jsx(QuoteTakerContext.Provider, { value: registerQuoteTaker, children: composer }) })] }) }), _jsx(TimelineMenuPopup, { target: target, thread: threadRef, chatId: onMainAgent ? chatId : null })] }), loadingEarlier && !overlay && (_jsxs("div", { className: "pointer-events-none absolute inset-x-0 top-3 z-10 flex justify-center", role: "status", children: [_jsx(Icon, { icon: LoaderCircle, size: 16, className: "animate-spin text-text-faint" }), _jsx("span", { className: "sr-only", children: t('timeline.loadingEarlier') })] })), showsScrubber && !overlay && (_jsx("div", { className: "absolute top-4", style: { left: STRIP_INSET_PX, width: STRIP_WIDTH_PX, bottom: coveredHeight }, children: _jsx(ErrorBoundary, { label: t('timeline.stripFailed'), resetKeys: [ticks.length], children: _jsx(Scrubber, { ticks: ticks, firstInView: inView?.first ?? null, lastInView: inView?.last ?? null, onPick: pick, chat: cardChat, found: found, foundCurrent: foundCurrent }) }) })), overlay && (_jsx("div", { className: "absolute inset-0 z-5 flex flex-col bg-surface", style: { paddingBottom: coveredHeight }, children: overlay }))] }) }));
+                                        className: clsx('relative z-10 shrink-0', composer && 'px-3 pb-3 pt-3 bg-[linear-gradient(to_bottom,transparent_calc(100%-12px),var(--surface)_calc(100%-12px))]'), style: { position: stickyComposer ? 'sticky' : 'relative', bottom: 0 }, children: _jsx(QuoteTakerContext.Provider, { value: registerQuoteTaker, children: composer }) })] }) }), _jsx(TimelineMenuPopup, { target: target, thread: threadRef, chatId: onMainAgent ? chatId : null })] }), drawsVisuals && _jsx(VisualDialogs, { chatId: chatId }), loadingEarlier && !overlay && (_jsxs("div", { className: "pointer-events-none absolute inset-x-0 top-3 z-10 flex justify-center", role: "status", children: [_jsx(Icon, { icon: LoaderCircle, size: 16, className: "animate-spin text-text-faint" }), _jsx("span", { className: "sr-only", children: t('timeline.loadingEarlier') })] })), showsScrubber && !overlay && (_jsx("div", { className: "absolute top-4", style: { left: STRIP_INSET_PX, width: STRIP_WIDTH_PX, bottom: coveredHeight }, children: _jsx(ErrorBoundary, { label: t('timeline.stripFailed'), resetKeys: [ticks.length], children: _jsx(Scrubber, { ticks: ticks, firstInView: inView?.first ?? null, lastInView: inView?.last ?? null, onPick: pick, chat: cardChat, found: found, foundCurrent: foundCurrent }) }) })), overlay && (_jsx("div", { className: "absolute inset-0 z-5 flex flex-col bg-surface", style: { paddingBottom: coveredHeight }, children: overlay }))] }) }));
 }

package/dist/chat/ui/UnifiedDiff.js

@@ -32,10 +32,10 @@ pre > [data-code] { flex-grow: 1; align-self: stretch; align-content: start; }
 `;
 function lineClass(line) {
     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/dist/chat/ui/VisualDialogs.d.ts

@@ -0,0 +1,3 @@
+export declare function VisualDialogs({ chatId }: {
+    chatId: string;
+}): import("react").JSX.Element;

package/dist/chat/ui/VisualDialogs.js

@@ -0,0 +1,32 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { CloseButton, Dialog, ErrorBoundary, PromptDialog } from '@adecore/ui';
+import { useChatScope } from '../../scope.js';
+import { useChatRow } from '../../state/chats.js';
+import { useVisualDialog } from '../visuals.js';
+import { VisualFrame } from './VisualFrame.js';
+/*
+ * 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 }) {
+    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(visual);
+    if (visual !== null && visual !== shown) {
+        setShown(visual);
+    }
+    const close = () => useVisualDialog.getState().close();
+    return (_jsxs(_Fragment, { children: [_jsx(Dialog.Root, { open: kind === 'expand' && visual !== null, onOpenChange: (next) => !next && close(), children: _jsxs(Dialog.Popup, { className: "flex h-[calc(100dvh-96px)] w-[1200px] flex-col overflow-hidden", children: [_jsxs("div", { className: "flex h-11 shrink-0 items-center gap-2 border-b border-border pr-2 pl-4", children: [_jsx(Dialog.Title, { className: "min-w-0 grow truncate", children: shown?.title }), _jsx(CloseButton, { label: t('common.action.close'), kbd: "esc", dialog: true })] }), _jsx("div", { className: "min-h-0 grow p-5", children: _jsx("div", { className: "relative size-full", children: shown !== null && (_jsx(ErrorBoundary, { label: t('visuals.renderFailed'), resetKeys: [shown], children: _jsx(VisualFrame, { chatId: chatId, visual: shown, fill: true }) })) }) })] }) }), _jsx(PromptDialog, { open: kind === 'remove' && visual !== null, title: t('visuals.removeTitle'), description: t('visuals.removeDescription', { title: shown?.title ?? '' }), confirmLabel: t('common.action.remove'), danger: true, fallbackMessage: t('visuals.removeFailed'), onConfirm: async () => {
+                    if (visualId !== null) {
+                        await scope.chats.removeVisual(chatId, visualId);
+                    }
+                    close();
+                }, onOpenChange: close })] }));
+}

package/dist/chat/ui/VisualFrame.d.ts

@@ -0,0 +1,8 @@
+import { type ChatVisual } from '@adecore/agent-contracts/visual';
+export interface VisualFrameProps {
+    chatId: string;
+    visual: ChatVisual;
+    fill?: boolean;
+    className?: string;
+}
+export declare function VisualFrame({ chatId, visual, fill, className }: VisualFrameProps): import("react").JSX.Element;

package/dist/chat/ui/VisualFrame.js

@@ -0,0 +1,95 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import clsx from 'clsx';
+import { visualThemeFragment } from '@adecore/agent-contracts/visual';
+import { Spinner, useMeasuredWidth } from '@adecore/ui';
+import { chatHost } from '../../host.js';
+import { useChatScope } from '../../scope.js';
+import { initialVisualHeight, rememberVisualHeight } from '../logic/visual-height.js';
+import { VisualBridge } from '../visual-bridge.js';
+import { useVisualTheme } from './visual-theme.js';
+/*
+ * 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) {
+    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 }) {
+    const { t } = useTranslation('agent-chat');
+    const scope = useChatScope();
+    const frameUrl = chatHost().visuals?.frameUrl ?? null;
+    const boxRef = useRef(null);
+    const frameRef = useRef(null);
+    const bridgeRef = useRef(null);
+    const [measure, width] = useMeasuredWidth();
+    const setBox = useCallback((node) => {
+        boxRef.current = node;
+        measure(node);
+    }, [measure]);
+    const theme = useVisualTheme(boxRef);
+    const widthRef = useRef(width);
+    const [reported, setReported] = useState(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(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(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) => 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 (_jsxs("div", { ref: setBox, className: clsx(fill ? 'absolute inset-0' : 'relative w-full', className), style: { height }, children: [opening !== null && (_jsx("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 ? (_jsx("p", { className: "absolute inset-0 grid place-items-center px-4 text-center text-xs text-text-muted", children: t('visuals.failed', { title: visual.title }) })) : (drawn === null && (_jsx("span", { className: "chat-visual-wait pointer-events-none absolute inset-0 grid place-items-center text-text-faint", children: _jsx(Spinner, { size: 16, label: t('visuals.loading', { title: visual.title }) }) })))] }));
+}

package/dist/chat/ui/rows/Rows.js

@@ -4,6 +4,7 @@ import { ErrorBoundary } from '@adecore/ui';
 import { AgentTurnRow, ApprovalHistoryRow, AssistantRow, CompactionRow, NoteRow, QuestionHistoryRow, ReportRow, ThinkingRow, UserRow } from './MessageRows.js';
 import { ForksRow } from './ForksRow.js';
 import { SubagentBranchRow } from './SubagentRow.js';
+import { VisualRow } from './VisualRow.js';
 import { WorkflowRow } from './WorkflowRow.js';
 import { ChangedFilesRow, TurnFoldRow, WorkGroupRow, WorkLiveRow, WorkRow, WorkingRow } from './WorkRows.js';
 /* Its own component, so a card that throws while it renders is caught by the boundary around it. */
@@ -57,5 +58,7 @@ export function Row({ row, chatId, toggleGroup, toggleTurn, toggleSubagent, open
             return _jsx(WorkingRow, { startedAt: row.startedAt });
         case 'app-card':
             return _jsx(AppCardRow, { card: row.card });
+        case 'visual':
+            return _jsx(VisualRow, { chatId: chatId, visual: row.visual });
     }
 }

package/dist/chat/ui/rows/VisualRow.d.ts

@@ -0,0 +1,5 @@
+import type { ChatVisual } from '@adecore/agent-contracts';
+export declare function VisualRow({ chatId, visual }: {
+    chatId: string;
+    visual: ChatVisual;
+}): import("react").JSX.Element | null;

package/dist/chat/ui/rows/VisualRow.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useTranslation } from 'react-i18next';
+import { Ellipsis, Maximize2, Trash2 } from 'lucide-react';
+import { ButtonGroup, ErrorBoundary, Icon, IconButton, Menu, Surface } from '@adecore/ui';
+import { chatHost } from '../../../host.js';
+import { useChatScope } from '../../../scope.js';
+import { useVisualDialog } from '../../visuals.js';
+import { VisualFrame } from '../VisualFrame.js';
+/*
+ * A page an agent published, borderless on the thread's ground and as wide as the reply. Its few
+ * controls float over the page's top corner while the pointer or the focus is on it, and always on a
+ * touch screen, which has no hover. A click inside the page never reaches the thread's menu, so they
+ * sit here.
+ */
+export function VisualRow({ chatId, visual }) {
+    const { t } = useTranslation('agent-chat');
+    const { keyOf } = useChatScope();
+    if (chatHost().visuals === null) {
+        return null;
+    }
+    const open = (kind) => useVisualDialog.getState().open(keyOf(chatId), visual.id, kind);
+    return (_jsx(ErrorBoundary, { label: t('visuals.renderFailed'), resetKeys: [visual], compact: true, className: "relative rounded-lg", children: _jsxs("div", { className: "group/visual relative", children: [_jsx(VisualFrame, { chatId: chatId, visual: visual }), _jsx(Surface, { role: "toolbar", "aria-label": t('visuals.actions', { title: visual.title }), className: "absolute top-2 right-2 rounded-lg p-0.5 opacity-0 transition-opacity group-focus-within/visual:opacity-100 group-hover/visual:opacity-100 has-[[data-popup-open]]:opacity-100 pointer-coarse:opacity-100", children: _jsxs(ButtonGroup, { children: [_jsx(IconButton, { icon: Maximize2, size: "sm", label: t('visuals.expand'), onClick: () => open('expand') }), _jsxs(Menu.Root, { children: [_jsx(IconButton, { icon: Ellipsis, size: "sm", label: t('visuals.more'), render: _jsx(Menu.Trigger, {}) }), _jsx(Menu.Popup, { align: "end", children: _jsxs(Menu.Item, { onClick: () => open('remove'), children: [_jsx(Icon, { icon: Trash2, size: 14 }), " ", t('visuals.remove')] }) })] })] }) })] }) }));
+}