@adecore/agents-react 0.18.3 → 0.19.0

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

@@ -14,6 +14,7 @@ export declare const SCRUBBER_MIN_TICKS = 3;
 export declare const TICK_HEIGHT_PX = 2;
 export declare const STRIP_WIDTH_PX = 24;
 export declare const STRIP_INSET_PX = 8;
+export declare const STRIP_CLEARANCE_PX: number;
 export declare function ticksOf(rows: readonly TimelineRow[], marks?: ReadonlyMap<string, ChatBookmark>): ScrubberTick[];
 export interface TickSlot {
     first: number;

package/dist/chat/logic/scrubber.js

@@ -9,7 +9,7 @@ const THREAD_PADDING_PX = 16;
 export const STRIP_WIDTH_PX = 24;
 /* The strip's distance from the view's left edge, and the air it keeps between itself and the thread's text. */
 export const STRIP_INSET_PX = 8;
-const STRIP_CLEARANCE_PX = STRIP_INSET_PX + STRIP_WIDTH_PX + STRIP_INSET_PX;
+export const STRIP_CLEARANCE_PX = STRIP_INSET_PX + STRIP_WIDTH_PX + STRIP_INSET_PX;
 const WIDTH_HOVERED_PX = 16;
 const WIDTH_NEAR_PERSON_PX = 12;
 const WIDTH_NEAR_WAKE_PX = 8;

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

@@ -1,4 +1,6 @@
 import { type ChatVisual } from '@adecore/agent-contracts/visual';
 export declare function clampVisualHeight(visual: Pick<ChatVisual, 'maxHeight'>, height: number): number;
+export declare function visualContentHeight(height: number): number;
+export declare function initialVisualContentHeight(visual: Pick<ChatVisual, 'id' | 'heights'>, width: 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

@@ -3,6 +3,8 @@ import { VISUAL_LIMITS, visualFrameHeight } from '@adecore/agent-contracts/visua
 const DEFAULT_HEIGHT_PX = 240;
 /* Plenty for the visuals of a long session; the oldest goes first. */
 const REMEMBERED_HEIGHTS = 500;
+// Stay within browser layout coordinates even if a page reports a bogus finite size.
+const MAX_CONTENT_HEIGHT_PX = 10_000_000;
 /*
  * 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.
@@ -15,6 +17,18 @@ function keyOf(visualId, width) {
 export function clampVisualHeight(visual, height) {
     return Math.min(Math.max(Math.ceil(Math.min(height, visual.maxHeight)), VISUAL_LIMITS.minHeight), VISUAL_LIMITS.maxHeight);
 }
+export function visualContentHeight(height) {
+    return Math.min(MAX_CONTENT_HEIGHT_PX, Math.max(VISUAL_LIMITS.minHeight, Math.ceil(height)));
+}
+export function initialVisualContentHeight(visual, width) {
+    const cached = remembered.get(keyOf(visual.id, width));
+    if (cached !== undefined) {
+        return cached;
+    }
+    const below = visual.heights?.filter(([measured]) => measured <= width).sort((left, right) => right[0] - left[0])[0];
+    const above = visual.heights?.filter(([measured]) => measured >= width).sort((left, right) => left[0] - right[0])[0];
+    return below || above ? visualContentHeight(Math.max(below?.[1] ?? 0, above?.[1] ?? 0)) : DEFAULT_HEIGHT_PX;
+}
 /*
  * 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.

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

@@ -0,0 +1,5 @@
+export interface VisualViewportGeometry {
+    height: number;
+    top: number;
+}
+export declare function visualViewportGeometry(contentHeight: number, availableHeight: number, top: number): VisualViewportGeometry;

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

@@ -0,0 +1,4 @@
+export function visualViewportGeometry(contentHeight, availableHeight, top) {
+    const height = Math.max(1, Math.min(contentHeight, availableHeight));
+    return { height, top: Math.max(0, Math.min(-top, contentHeight - height)) };
+}

package/dist/chat/ui/Timeline.js

@@ -11,7 +11,7 @@ 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';
-import { SCRUBBER_MIN_TICKS, STRIP_INSET_PX, STRIP_WIDTH_PX, messagesInView, stepMessage, threadPaddingLeft, tickOfRow, ticksOf, ticksWithHits } from '../logic/scrubber.js';
+import { SCRUBBER_MIN_TICKS, STRIP_INSET_PX, STRIP_WIDTH_PX, messagesInView, stepMessage, threadPaddingLeft, STRIP_CLEARANCE_PX, tickOfRow, ticksOf, ticksWithHits } from '../logic/scrubber.js';
 import { EMPTY_TARGET, readTimelineTarget, withCurrentText } from '../logic/timeline-target.js';
 import { forkRefusal } from '../logic/fork.js';
 import { FindRevealContext } from './find-reveal.js';
@@ -20,12 +20,13 @@ 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 { FOLLOW_THRESHOLD_PX, replyHeader } from './rows/row-rhythm.js';
 import { QuoteButton } from './QuoteButton.js';
 import { QuoteTakerContext } from './quote-selection.js';
 import { useToggleSet } from './useToggleSet.js';
 import { WelcomeGreeting } from './Welcome.js';
 import { Row } from './rows/Rows.js';
+import { RowContainer } from './rows/RowContainer.js';
 import { ReplyHeader } from './rows/MessageRows.js';
 import { useChatRow, useChats } from '../../state/chats.js';
 import { chatHost } from '../../host.js';
@@ -416,13 +417,14 @@ export function Timeline({ chatId, composer, overlay }) {
                                 if (wantsEarlier(el)) {
                                     loadEarlier();
                                 }
-                            }, children: _jsxs("div", { ref: contentRef, className: clsx('relative flex min-h-full flex-col', welcome && 'justify-center'), children: [_jsx(ContextMenu.Trigger, { ref: threadRef, className: clsx('chat-thread flex flex-col px-4 pt-4', !welcome && 'grow'), style: { paddingLeft }, inert: overlay ? true : undefined, onContextMenu: (e) => setTarget(readTimelineTarget(e.target, threadRef.current, withCurrentText(rows, fullItems()))), children: welcome ? (_jsx(WelcomeGreeting, { chatId: chatId })) : empty ? (_jsx(EmptyThread, { chatId: chatId })) : (_jsx("div", { className: "chat-column-content relative w-full shrink-0", style: { height: virtualizer.getTotalSize() }, children: virtualizer.getVirtualItems().map((virtualRow) => {
+                            }, children: _jsxs("div", { ref: contentRef, className: clsx('relative flex min-h-full flex-col', welcome && 'justify-center'), children: [_jsx(ContextMenu.Trigger, { ref: threadRef, className: clsx('chat-thread flex flex-col px-4 pt-4', !welcome && 'grow'), style: {
+                                            paddingLeft,
+                                            '--chat-wide-inset': `${2 * (showsScrubber ? STRIP_CLEARANCE_PX : paddingLeft) - paddingLeft}px`
+                                        }, inert: overlay ? true : undefined, onContextMenu: (e) => setTarget(readTimelineTarget(e.target, threadRef.current, withCurrentText(rows, fullItems()))), children: welcome ? (_jsx(WelcomeGreeting, { chatId: chatId })) : empty ? (_jsx(EmptyThread, { chatId: chatId })) : (_jsx("div", { className: "relative w-full shrink-0", style: { height: virtualizer.getTotalSize() }, children: virtualizer.getVirtualItems().map((virtualRow) => {
                                                 const row = rows[virtualRow.index];
-                                                // Put turn gaps inside the measured row so the virtualizer includes them.
-                                                const question = row.kind === 'user';
                                                 const previous = virtualRow.index > 0 ? rows[virtualRow.index - 1] : null;
                                                 const header = replyHeader(row, previous);
-                                                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));
+                                                return (_jsxs(RowContainer, { row: row, previous: previous, index: virtualRow.index, top: virtualRow.start, ref: virtualizer.measureElement, 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("div", { className: "chat-column-content w-full", children: _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 })] }), 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/VisualFrame.js

@@ -6,8 +6,9 @@ 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 { initialVisualContentHeight, rememberVisualHeight } from '../logic/visual-height.js';
 import { VisualBridge } from '../visual-bridge.js';
+import { VisualViewportController } from '../visual-viewport.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
@@ -30,6 +31,9 @@ export function VisualFrame({ chatId, visual, fill = false, className }) {
     const boxRef = useRef(null);
     const frameRef = useRef(null);
     const bridgeRef = useRef(null);
+    const viewportRef = useRef(null);
+    const controllerRef = useRef(null);
+    const [viewportReady, setViewportReady] = useState(false);
     const [measure, width] = useMeasuredWidth();
     const setBox = useCallback((node) => {
         boxRef.current = node;
@@ -46,7 +50,7 @@ export function VisualFrame({ chatId, visual, fill = false, className }) {
     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));
+    const height = fill || width === 0 ? undefined : (reported ?? initialVisualContentHeight(visual, width));
     useLayoutEffect(() => {
         widthRef.current = width;
     }, [width]);
@@ -71,6 +75,12 @@ export function VisualFrame({ chatId, visual, fill = false, className }) {
                 setReported(next);
                 rememberVisualHeight(visual.id, widthRef.current, next);
             },
+            ...(!fill
+                ? {
+                    onViewportReady: () => setViewportReady(true),
+                    onScroll: (request) => controllerRef.current?.scroll(request)
+                }
+                : {}),
             onAppearance: setDrawn,
             onFailure: () => setFailed(true)
         });
@@ -84,12 +94,28 @@ export function VisualFrame({ chatId, visual, fill = false, className }) {
             bridgeRef.current = null;
         };
     }, [opening, scope.id, chatId, visual.id, visual.maxHeight, fill]);
+    useLayoutEffect(() => {
+        const box = boxRef.current;
+        const viewport = viewportRef.current;
+        const bridge = bridgeRef.current;
+        const scroller = box?.closest('.chat-scroll');
+        if (fill || !viewportReady || !box || !viewport || !bridge || !scroller) {
+            return;
+        }
+        const controller = new VisualViewportController(box, viewport, scroller, bridge);
+        controllerRef.current = controller;
+        return () => {
+            controller.dispose();
+            controllerRef.current = null;
+        };
+    }, [fill, viewportReady, opening, scope.id, chatId, visual.id, visual.maxHeight]);
+    useLayoutEffect(() => controllerRef.current?.refresh(), [height, width]);
     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 }) }) })))] }));
+    return (_jsx("div", { ref: setBox, className: clsx(fill ? 'absolute inset-0' : 'relative w-full', className), style: { height }, children: _jsxs("div", { ref: viewportRef, className: fill ? 'absolute inset-0' : 'sticky top-0 w-full', style: fill ? undefined : { height: '100%' }, 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/RowContainer.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode, Ref } from 'react';
+import type { TimelineRow } from '../../logic/timeline.js';
+export interface RowContainerProps {
+    row: TimelineRow;
+    previous: TimelineRow | null;
+    index: number;
+    top: number;
+    ref?: Ref<HTMLDivElement>;
+    children: ReactNode;
+}
+export declare function RowContainer({ row, previous, index, top, ref, children }: RowContainerProps): import("react").JSX.Element;

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

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from 'clsx';
+import { rowPosition, rowRhythm } from './row-rhythm.js';
+export function RowContainer({ row, previous, index, top, ref, children }) {
+    const wide = row.kind === 'visual' && row.visual.layout === 'wide';
+    return (_jsx("div", { "data-index": index, "data-item-id": row.id, ref: ref, className: clsx('absolute inset-x-0 top-0 mx-auto w-full', wide ? 'chat-wide-content' : 'chat-column-content', rowRhythm(row, previous), 
+        // Turn gaps belong inside the measurement used by the virtualizer.
+        row.kind === 'user' && index > 0 && 'pt-(--chat-turn-gap)'), style: rowPosition(row.kind, top), children: children }));
+}

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

@@ -7,7 +7,7 @@ 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
+ * A page an agent published, borderless on the thread's ground, with its width set by the row. 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.

package/dist/chat/ui/rows/row-rhythm.d.ts

@@ -1,6 +1,8 @@
+import type { CSSProperties } from 'react';
 import { type TimelineRow } from '../../logic/timeline.js';
 export declare const FOLLOW_THRESHOLD_PX = 40;
 export declare function rowRhythm(row: TimelineRow, previous: TimelineRow | null): string;
 export declare function replyHeader(row: TimelineRow, previous: TimelineRow | null): {
     at: number | null;
 } | null;
+export declare function rowPosition(kind: TimelineRow['kind'], top: number): CSSProperties;

package/dist/chat/ui/rows/row-rhythm.js

@@ -32,3 +32,7 @@ export function replyHeader(row, previous) {
     }
     return null;
 }
+// A transform also shifts a descendant's sticky position after it was resolved against the scrollport.
+export function rowPosition(kind, top) {
+    return kind === 'visual' ? { top } : { transform: `translateY(${top}px)` };
+}

package/dist/chat/visual-bridge.d.ts

@@ -1,4 +1,4 @@
-import { type ChatVisual, type VisualAppearance, type VisualTheme } from '@adecore/agent-contracts/visual';
+import { type ChatVisual, type VisualAppearance, type VisualScrollRequest, type VisualViewport, type VisualTheme } from '@adecore/agent-contracts/visual';
 export interface VisualFrameWindow {
     postMessage(message: unknown, targetOrigin: string): void;
 }
@@ -10,6 +10,8 @@ export interface VisualBridgeOptions {
     mayOpenLink(): boolean;
     openLink(url: string): void;
     onHeight(height: number): void;
+    onViewportReady?(): void;
+    onScroll?(request: VisualScrollRequest): void;
     onAppearance(appearance: VisualAppearance): void;
     onFailure(): void;
     after?(ms: number, run: () => void): () => void;
@@ -22,6 +24,8 @@ export declare class VisualBridge {
     private waiting;
     private sent;
     private live;
+    private viewportReady;
+    private viewport;
     private disposed;
     private cancelSilence;
     constructor(options: VisualBridgeOptions);
@@ -29,6 +33,7 @@ export declare class VisualBridge {
         source: unknown;
         data: unknown;
     }): void;
+    setViewport(viewport: VisualViewport | null): void;
     setTheme(theme: VisualTheme): void;
     loaded(): void;
     dispose(): void;

package/dist/chat/visual-bridge.js

@@ -1,5 +1,5 @@
-import { VISUAL_BRIDGE_METHODS, parseVisualMessage, visualHostContextMessage, visualOpenLinkResult, visualResourceReadyMessage } from '@adecore/agent-contracts/visual';
-import { clampVisualHeight } from './logic/visual-height.js';
+import { VISUAL_BRIDGE_METHODS, parseVisualMessage, visualHostContextMessage, visualOpenLinkResult, visualResourceReadyMessage, visualViewportMessage } from '@adecore/agent-contracts/visual';
+import { clampVisualHeight, visualContentHeight } from './logic/visual-height.js';
 /*
  * How long a frame that finished loading may stay silent before it counts as failed. The sandbox host
  * page speaks while it loads, so silence means the address served something else; the margin is for
@@ -28,6 +28,8 @@ export class VisualBridge {
     sent = null;
     /* Whether the page reported a size since it was sent, which says it runs and is drawn. */
     live = false;
+    viewportReady = false;
+    viewport = null;
     disposed = false;
     cancelSilence = () => undefined;
     constructor(options) {
@@ -56,6 +58,7 @@ export class VisualBridge {
                 this.waiting = true;
                 this.sent = null;
                 this.live = false;
+                this.viewportReady = false;
                 this.cancelSilence();
                 this.sendPage();
                 return;
@@ -67,7 +70,20 @@ export class VisualBridge {
                     this.live = true;
                     this.options.onAppearance(this.sent.appearance);
                 }
-                this.options.onHeight(clampVisualHeight(this.options.visual, message.height));
+                this.options.onHeight(this.options.onViewportReady ? visualContentHeight(message.height) : clampVisualHeight(this.options.visual, message.height));
+                return;
+            case VISUAL_BRIDGE_METHODS.viewportReady:
+                if (this.sent === null) {
+                    return;
+                }
+                this.viewportReady = true;
+                this.options.onViewportReady?.();
+                this.setViewport(this.viewport);
+                return;
+            case VISUAL_BRIDGE_METHODS.scrollRequest:
+                if (this.sent !== null && this.viewportReady && this.viewport !== null) {
+                    this.options.onScroll?.(message.request);
+                }
                 return;
             case VISUAL_BRIDGE_METHODS.openLink:
                 if (this.sent === null) {
@@ -82,6 +98,12 @@ export class VisualBridge {
                 return;
         }
     }
+    setViewport(viewport) {
+        this.viewport = viewport;
+        if (!this.disposed && this.sent !== null && this.viewportReady) {
+            this.options.frame()?.postMessage(visualViewportMessage(viewport), '*');
+        }
+    }
     /* The app's theme changed; a page that was sent follows it at once, without loading again. */
     setTheme(theme) {
         this.theme = theme;

package/dist/chat/visual-viewport.d.ts

@@ -0,0 +1,22 @@
+import type { VisualScrollRequest } from '@adecore/agent-contracts/visual';
+import type { VisualBridge } from './visual-bridge.js';
+/** Keeps one small frame in a full-height timeline row, without rendering React on scroll. */
+export declare class VisualViewportController {
+    private readonly box;
+    private readonly viewport;
+    private readonly scroller;
+    private readonly bridge;
+    private readonly observer;
+    private readonly attributes;
+    private readonly view;
+    private frame;
+    private disposed;
+    private last;
+    private pendingDelta;
+    private readonly onScroll;
+    constructor(box: HTMLElement, viewport: HTMLElement, scroller: HTMLElement, bridge: VisualBridge);
+    refresh(): void;
+    scroll(request: VisualScrollRequest): void;
+    dispose(): void;
+    private schedule;
+}

package/dist/chat/visual-viewport.js

@@ -0,0 +1,91 @@
+import { visualViewportGeometry } from './logic/visual-viewport.js';
+/** Keeps one small frame in a full-height timeline row, without rendering React on scroll. */
+export class VisualViewportController {
+    box;
+    viewport;
+    scroller;
+    bridge;
+    observer;
+    attributes;
+    view;
+    frame = 0;
+    disposed = false;
+    last = '';
+    pendingDelta = 0;
+    onScroll;
+    constructor(box, viewport, scroller, bridge) {
+        this.box = box;
+        this.viewport = viewport;
+        this.scroller = scroller;
+        this.bridge = bridge;
+        this.view = box.ownerDocument.defaultView;
+        this.onScroll = () => this.refresh();
+        this.observer = new ResizeObserver(this.onScroll);
+        this.observer.observe(box);
+        this.observer.observe(scroller);
+        this.attributes = new MutationObserver(this.onScroll);
+        const row = box.closest('[data-index]');
+        if (row) {
+            this.attributes.observe(row, { attributes: true, attributeFilter: ['style'] });
+        }
+        scroller.addEventListener('scroll', this.onScroll, { passive: true });
+        this.refresh();
+    }
+    refresh() {
+        if (this.disposed) {
+            return;
+        }
+        const outer = this.scroller.getBoundingClientRect();
+        const box = this.box.getBoundingClientRect();
+        // A chat on a canvas can be scaled; messages inside its frame use unscaled CSS pixels.
+        const scale = outer.height / this.scroller.offsetHeight || 1;
+        const top = (box.top - outer.top) / scale - this.scroller.clientTop;
+        const available = this.scroller.clientHeight;
+        const geometry = visualViewportGeometry(this.box.offsetHeight, available, top);
+        this.viewport.style.height = `${geometry.height}px`;
+        const key = `${geometry.top}:${geometry.height}`;
+        if (key !== this.last) {
+            this.last = key;
+            this.bridge.setViewport(geometry);
+        }
+    }
+    scroll(request) {
+        const outer = this.scroller.getBoundingClientRect();
+        const box = this.box.getBoundingClientRect();
+        if (this.disposed || box.bottom <= outer.top || box.top >= outer.bottom) {
+            return;
+        }
+        if ('by' in request) {
+            this.pendingDelta += request.by;
+            this.schedule();
+            return;
+        }
+        this.pendingDelta = 0;
+        const scale = outer.height / this.scroller.offsetHeight || 1;
+        const start = this.scroller.scrollTop + (box.top - outer.top) / scale - this.scroller.clientTop;
+        const top = 'to' in request ? start + request.to : request.edge === 'start' ? 0 : this.scroller.scrollHeight;
+        this.scroller.scrollTo({ top, behavior: 'instant' });
+        this.refresh();
+    }
+    dispose() {
+        this.disposed = true;
+        this.view.cancelAnimationFrame(this.frame);
+        this.observer.disconnect();
+        this.attributes.disconnect();
+        this.scroller.removeEventListener('scroll', this.onScroll);
+        this.bridge.setViewport(null);
+    }
+    schedule() {
+        if (this.frame || this.disposed) {
+            return;
+        }
+        this.frame = this.view.requestAnimationFrame(() => {
+            this.frame = 0;
+            if (this.pendingDelta !== 0) {
+                this.scroller.scrollBy({ top: this.pendingDelta, behavior: 'instant' });
+                this.pendingDelta = 0;
+            }
+            this.refresh();
+        });
+    }
+}

package/dist/theme.css

@@ -96,6 +96,8 @@
      * thread grows past a screenful; only the rows and the composer inside it are centered.
      */
     .chat-column .chat-column-content { margin-inline: auto; max-width: 768px; }
+    /* Wide pages clear the scrubber even when the reply column needs no extra padding. */
+    .chat-wide-content { max-width: calc(100% - 2 * var(--chat-wide-inset, 0px)); }
     /* Wider by the input's inset (`.composer-input .cm-content` padding plus the card's border), so what is typed lines up with the thread. */
     .chat-column .chat-composer-content { margin-inline: auto; max-width: calc(768px + 2 * 21px); }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agents-react",
-  "version": "0.18.3",
+  "version": "0.19.0",
   "description": "React agent chat threads, composers, approvals, provider accounts and usage views.",
   "type": "module",
   "exports": {
@@ -559,6 +559,11 @@
       "types": "./dist/chat/ui/rows/MessageRows.d.ts",
       "default": "./dist/chat/ui/rows/MessageRows.js"
     },
+    "./chat/ui/rows/RowContainer": {
+      "source": "./src/chat/ui/rows/RowContainer.tsx",
+      "types": "./dist/chat/ui/rows/RowContainer.d.ts",
+      "default": "./dist/chat/ui/rows/RowContainer.js"
+    },
     "./chat/ui/rows/Rows": {
       "source": "./src/chat/ui/rows/Rows.tsx",
       "types": "./dist/chat/ui/rows/Rows.d.ts",
@@ -867,12 +872,23 @@
       "source": "./src/storage.ts",
       "types": "./dist/storage.d.ts",
       "default": "./dist/storage.js"
+    },
+    "./chat/logic/visual-viewport": {
+      "source": "./src/chat/logic/visual-viewport.ts",
+      "types": "./dist/chat/logic/visual-viewport.d.ts",
+      "default": "./dist/chat/logic/visual-viewport.js"
+    },
+    "./chat/visual-viewport": {
+      "source": "./src/chat/visual-viewport.ts",
+      "types": "./dist/chat/visual-viewport.d.ts",
+      "default": "./dist/chat/visual-viewport.js"
     }
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.ts",
-    "test": "bun --conditions=source test"
+    "test": "bun --conditions=source test",
+    "test:visuals": "bun --config=integration.bunfig.toml --conditions=source test ./src/chat/visual-viewport.integration.test.ts"
   },
   "dependencies": {
     "@codemirror/commands": "^6.11.1",
@@ -883,7 +899,7 @@
     "@lezer/highlight": "^1.2.3",
     "@lezer/markdown": "^1.7.2",
     "@pierre/diffs": "^1.4.3",
-    "@adecore/agent-contracts": "0.18.3",
+    "@adecore/agent-contracts": "0.19.0",
     "@tanstack/react-virtual": "^3.14.13",
     "clsx": "^2.1.1",
     "lucide-react": "^1.47.0",
@@ -896,7 +912,7 @@
     "zustand": "^5.0.15"
   },
   "peerDependencies": {
-    "@adecore/ui": "^0.18.3",
+    "@adecore/ui": "^0.19.0",
     "i18next": "^26.4.2",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",

package/src/chat/logic/scrubber.ts

@@ -36,7 +36,7 @@ const THREAD_PADDING_PX = 16;
 export const STRIP_WIDTH_PX = 24;
 /* The strip's distance from the view's left edge, and the air it keeps between itself and the thread's text. */
 export const STRIP_INSET_PX = 8;
-const STRIP_CLEARANCE_PX = STRIP_INSET_PX + STRIP_WIDTH_PX + STRIP_INSET_PX;
+export const STRIP_CLEARANCE_PX = STRIP_INSET_PX + STRIP_WIDTH_PX + STRIP_INSET_PX;
 
 const WIDTH_HOVERED_PX = 16;
 const WIDTH_NEAR_PERSON_PX = 12;

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

@@ -4,6 +4,8 @@ import { VISUAL_LIMITS, visualFrameHeight, type ChatVisual } from '@adecore/agen
 const DEFAULT_HEIGHT_PX = 240;
 /* Plenty for the visuals of a long session; the oldest goes first. */
 const REMEMBERED_HEIGHTS = 500;
+// Stay within browser layout coordinates even if a page reports a bogus finite size.
+const MAX_CONTENT_HEIGHT_PX = 10_000_000;
 
 /*
  * The heights frames reported, by visual and width. The thread draws only the rows in view, so a row
@@ -20,6 +22,20 @@ export function clampVisualHeight(visual: Pick<ChatVisual, 'maxHeight'>, height:
     return Math.min(Math.max(Math.ceil(Math.min(height, visual.maxHeight)), VISUAL_LIMITS.minHeight), VISUAL_LIMITS.maxHeight);
 }
 
+export function visualContentHeight(height: number): number {
+    return Math.min(MAX_CONTENT_HEIGHT_PX, Math.max(VISUAL_LIMITS.minHeight, Math.ceil(height)));
+}
+
+export function initialVisualContentHeight(visual: Pick<ChatVisual, 'id' | 'heights'>, width: number): number {
+    const cached = remembered.get(keyOf(visual.id, width));
+    if (cached !== undefined) {
+        return cached;
+    }
+    const below = visual.heights?.filter(([measured]) => measured <= width).sort((left, right) => right[0] - left[0])[0];
+    const above = visual.heights?.filter(([measured]) => measured >= width).sort((left, right) => left[0] - right[0])[0];
+    return below || above ? visualContentHeight(Math.max(below?.[1] ?? 0, above?.[1] ?? 0)) : DEFAULT_HEIGHT_PX;
+}
+
 /*
  * 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.

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

@@ -0,0 +1,9 @@
+export interface VisualViewportGeometry {
+    height: number;
+    top: number;
+}
+
+export function visualViewportGeometry(contentHeight: number, availableHeight: number, top: number): VisualViewportGeometry {
+    const height = Math.max(1, Math.min(contentHeight, availableHeight));
+    return { height, top: Math.max(0, Math.min(-top, contentHeight - height)) };
+}

package/src/chat/ui/Timeline.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import { type CSSProperties, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useVirtualizer } from '@tanstack/react-virtual';
 import clsx from 'clsx';
@@ -27,6 +27,7 @@ import {
     messagesInView,
     stepMessage,
     threadPaddingLeft,
+    STRIP_CLEARANCE_PX,
     tickOfRow,
     ticksOf,
     ticksWithHits
@@ -39,12 +40,13 @@ 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 { FOLLOW_THRESHOLD_PX, replyHeader } from './rows/row-rhythm';
 import { QuoteButton } from './QuoteButton';
 import { QuoteTakerContext, type QuoteTaker } from './quote-selection';
 import { useToggleSet } from './useToggleSet';
 import { WelcomeGreeting } from './Welcome';
 import { Row } from './rows/Rows';
+import { RowContainer } from './rows/RowContainer';
 import { ReplyHeader } from './rows/MessageRows';
 import { useChatRow, useChats } from '../../state/chats';
 import { chatHost } from '../../host';
@@ -530,7 +532,12 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
                             <ContextMenu.Trigger
                                 ref={threadRef}
                                 className={clsx('chat-thread flex flex-col px-4 pt-4', !welcome && 'grow')}
-                                style={{ paddingLeft }}
+                                style={
+                                    {
+                                        paddingLeft,
+                                        '--chat-wide-inset': `${2 * (showsScrubber ? STRIP_CLEARANCE_PX : paddingLeft) - paddingLeft}px`
+                                    } as CSSProperties
+                                }
                                 inert={overlay ? true : undefined}
                                 onContextMenu={(e) =>
                                     setTarget(readTimelineTarget(e.target as HTMLElement, threadRef.current, withCurrentText(rows, fullItems())))
@@ -541,25 +548,19 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
                                 ) : empty ? (
                                     <EmptyThread chatId={chatId} />
                                 ) : (
-                                    <div className="chat-column-content relative w-full shrink-0" style={{ height: virtualizer.getTotalSize() }}>
+                                    <div className="relative w-full shrink-0" style={{ height: virtualizer.getTotalSize() }}>
                                         {virtualizer.getVirtualItems().map((virtualRow) => {
                                             const row = rows[virtualRow.index]!;
-                                            // Put turn gaps inside the measured row so the virtualizer includes them.
-                                            const question = row.kind === 'user';
                                             const previous = virtualRow.index > 0 ? rows[virtualRow.index - 1]! : null;
                                             const header = replyHeader(row, previous);
                                             return (
-                                                <div
+                                                <RowContainer
                                                     key={row.id}
-                                                    data-index={virtualRow.index}
-                                                    data-item-id={row.id}
+                                                    row={row}
+                                                    previous={previous}
+                                                    index={virtualRow.index}
+                                                    top={virtualRow.start}
                                                     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)` }}
                                                 >
                                                     {flash !== null && flash.key === keyOf(chatId) && flash.rowId === row.id && (
                                                         <span
@@ -568,7 +569,11 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
                                                             aria-hidden
                                                         />
                                                     )}
-                                                    {header !== null && <ReplyHeader chatId={chatId} at={header.at} />}
+                                                    {header !== null && (
+                                                        <div className="chat-column-content w-full">
+                                                            <ReplyHeader chatId={chatId} at={header.at} />
+                                                        </div>
+                                                    )}
                                                     <FindRevealContext.Provider value={chatFind.reveal}>
                                                         <MarkableRow row={row} chatId={chatId} bookmark={marks.get(row.id) ?? null}>
                                                             <Row
@@ -582,7 +587,7 @@ export function Timeline({ chatId, composer, overlay }: { chatId: string; compos
                                                             />
                                                         </MarkableRow>
                                                     </FindRevealContext.Provider>
-                                                </div>
+                                                </RowContainer>
                                             );
                                         })}
                                     </div>

package/src/chat/ui/VisualFrame.tsx

@@ -5,8 +5,9 @@ import { visualThemeFragment, type ChatVisual, type VisualAppearance, type Visua
 import { Spinner, useMeasuredWidth } from '@adecore/ui';
 import { chatHost } from '../../host';
 import { useChatScope } from '../../scope';
-import { initialVisualHeight, rememberVisualHeight } from '../logic/visual-height';
+import { initialVisualContentHeight, rememberVisualHeight } from '../logic/visual-height';
 import { VisualBridge } from '../visual-bridge';
+import { VisualViewportController } from '../visual-viewport';
 import { useVisualTheme } from './visual-theme';
 
 export interface VisualFrameProps {
@@ -39,6 +40,9 @@ export function VisualFrame({ chatId, visual, fill = false, className }: VisualF
     const boxRef = useRef<HTMLDivElement | null>(null);
     const frameRef = useRef<HTMLIFrameElement>(null);
     const bridgeRef = useRef<VisualBridge | null>(null);
+    const viewportRef = useRef<HTMLDivElement | null>(null);
+    const controllerRef = useRef<VisualViewportController | null>(null);
+    const [viewportReady, setViewportReady] = useState(false);
     const [measure, width] = useMeasuredWidth();
     const setBox = useCallback(
         (node: HTMLDivElement | null) => {
@@ -58,7 +62,7 @@ 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 ?? initialVisualHeight(visual, width));
+    const height = fill || width === 0 ? undefined : (reported ?? initialVisualContentHeight(visual, width));
 
     useLayoutEffect(() => {
         widthRef.current = width;
@@ -85,6 +89,12 @@ export function VisualFrame({ chatId, visual, fill = false, className }: VisualF
                 setReported(next);
                 rememberVisualHeight(visual.id, widthRef.current, next);
             },
+            ...(!fill
+                ? {
+                      onViewportReady: () => setViewportReady(true),
+                      onScroll: (request) => controllerRef.current?.scroll(request)
+                  }
+                : {}),
             onAppearance: setDrawn,
             onFailure: () => setFailed(true)
         });
@@ -99,6 +109,24 @@ export function VisualFrame({ chatId, visual, fill = false, className }: VisualF
         };
     }, [opening, scope.id, chatId, visual.id, visual.maxHeight, fill]);
 
+    useLayoutEffect(() => {
+        const box = boxRef.current;
+        const viewport = viewportRef.current;
+        const bridge = bridgeRef.current;
+        const scroller = box?.closest<HTMLElement>('.chat-scroll');
+        if (fill || !viewportReady || !box || !viewport || !bridge || !scroller) {
+            return;
+        }
+        const controller = new VisualViewportController(box, viewport, scroller, bridge);
+        controllerRef.current = controller;
+        return () => {
+            controller.dispose();
+            controllerRef.current = null;
+        };
+    }, [fill, viewportReady, opening, scope.id, chatId, visual.id, visual.maxHeight]);
+
+    useLayoutEffect(() => controllerRef.current?.refresh(), [height, width]);
+
     useEffect(() => {
         if (theme !== null) {
             bridgeRef.current?.setTheme(theme);
@@ -107,30 +135,32 @@ export function VisualFrame({ chatId, visual, fill = false, className }: VisualF
 
     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 ref={viewportRef} className={fill ? 'absolute inset-0' : 'sticky top-0 w-full'} style={fill ? undefined : { height: '100%' }}>
+                {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>
         </div>
     );
 }

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

@@ -0,0 +1,34 @@
+import type { ReactNode, Ref } from 'react';
+import clsx from 'clsx';
+import type { TimelineRow } from '../../logic/timeline';
+import { rowPosition, rowRhythm } from './row-rhythm';
+
+export interface RowContainerProps {
+    row: TimelineRow;
+    previous: TimelineRow | null;
+    index: number;
+    top: number;
+    ref?: Ref<HTMLDivElement>;
+    children: ReactNode;
+}
+
+export function RowContainer({ row, previous, index, top, ref, children }: RowContainerProps) {
+    const wide = row.kind === 'visual' && row.visual.layout === 'wide';
+    return (
+        <div
+            data-index={index}
+            data-item-id={row.id}
+            ref={ref}
+            className={clsx(
+                'absolute inset-x-0 top-0 mx-auto w-full',
+                wide ? 'chat-wide-content' : 'chat-column-content',
+                rowRhythm(row, previous),
+                // Turn gaps belong inside the measurement used by the virtualizer.
+                row.kind === 'user' && index > 0 && 'pt-(--chat-turn-gap)'
+            )}
+            style={rowPosition(row.kind, top)}
+        >
+            {children}
+        </div>
+    );
+}

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

@@ -8,7 +8,7 @@ import { useVisualDialog } from '../../visuals';
 import { VisualFrame } from '../VisualFrame';
 
 /*
- * A page an agent published, borderless on the thread's ground and as wide as the reply. Its few
+ * A page an agent published, borderless on the thread's ground, with its width set by the row. 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.

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

@@ -1,3 +1,4 @@
+import type { CSSProperties } from 'react';
 import clsx from 'clsx';
 import { isBlock, type TimelineRow } from '../../logic/timeline';
 
@@ -35,3 +36,8 @@ export function replyHeader(row: TimelineRow, previous: TimelineRow | null): { a
     }
     return null;
 }
+
+// A transform also shifts a descendant's sticky position after it was resolved against the scrollport.
+export function rowPosition(kind: TimelineRow['kind'], top: number): CSSProperties {
+    return kind === 'visual' ? { top } : { transform: `translateY(${top}px)` };
+}

package/src/chat/visual-bridge.ts

@@ -4,11 +4,14 @@ import {
     visualHostContextMessage,
     visualOpenLinkResult,
     visualResourceReadyMessage,
+    visualViewportMessage,
     type ChatVisual,
     type VisualAppearance,
+    type VisualScrollRequest,
+    type VisualViewport,
     type VisualTheme
 } from '@adecore/agent-contracts/visual';
-import { clampVisualHeight } from './logic/visual-height';
+import { clampVisualHeight, visualContentHeight } from './logic/visual-height';
 
 /*
  * How long a frame that finished loading may stay silent before it counts as failed. The sandbox host
@@ -34,6 +37,8 @@ export interface VisualBridgeOptions {
     mayOpenLink(): boolean;
     openLink(url: string): void;
     onHeight(height: number): void;
+    onViewportReady?(): void;
+    onScroll?(request: VisualScrollRequest): void;
     /* The appearance the page is drawn in, from the first size it reports and after every theme it gets since. */
     onAppearance(appearance: VisualAppearance): void;
     /* The page could not be read, or the frame's address answered with something other than the sandbox host page. */
@@ -65,6 +70,8 @@ export class VisualBridge {
     private sent: VisualTheme | null = null;
     /* Whether the page reported a size since it was sent, which says it runs and is drawn. */
     private live = false;
+    private viewportReady = false;
+    private viewport: VisualViewport | null = null;
     private disposed = false;
     private cancelSilence: () => void = () => undefined;
 
@@ -98,6 +105,7 @@ export class VisualBridge {
                 this.waiting = true;
                 this.sent = null;
                 this.live = false;
+                this.viewportReady = false;
                 this.cancelSilence();
                 this.sendPage();
                 return;
@@ -109,7 +117,22 @@ export class VisualBridge {
                     this.live = true;
                     this.options.onAppearance(this.sent.appearance);
                 }
-                this.options.onHeight(clampVisualHeight(this.options.visual, message.height));
+                this.options.onHeight(
+                    this.options.onViewportReady ? visualContentHeight(message.height) : clampVisualHeight(this.options.visual, message.height)
+                );
+                return;
+            case VISUAL_BRIDGE_METHODS.viewportReady:
+                if (this.sent === null) {
+                    return;
+                }
+                this.viewportReady = true;
+                this.options.onViewportReady?.();
+                this.setViewport(this.viewport);
+                return;
+            case VISUAL_BRIDGE_METHODS.scrollRequest:
+                if (this.sent !== null && this.viewportReady && this.viewport !== null) {
+                    this.options.onScroll?.(message.request);
+                }
                 return;
             case VISUAL_BRIDGE_METHODS.openLink:
                 if (this.sent === null) {
@@ -125,6 +148,13 @@ export class VisualBridge {
         }
     }
 
+    setViewport(viewport: VisualViewport | null): void {
+        this.viewport = viewport;
+        if (!this.disposed && this.sent !== null && this.viewportReady) {
+            this.options.frame()?.postMessage(visualViewportMessage(viewport), '*');
+        }
+    }
+
     /* The app's theme changed; a page that was sent follows it at once, without loading again. */
     setTheme(theme: VisualTheme): void {
         this.theme = theme;

package/src/chat/visual-viewport.ts

@@ -0,0 +1,99 @@
+import type { VisualScrollRequest } from '@adecore/agent-contracts/visual';
+import { visualViewportGeometry } from './logic/visual-viewport';
+import type { VisualBridge } from './visual-bridge';
+
+/** Keeps one small frame in a full-height timeline row, without rendering React on scroll. */
+export class VisualViewportController {
+    private readonly box: HTMLElement;
+    private readonly viewport: HTMLElement;
+    private readonly scroller: HTMLElement;
+    private readonly bridge: VisualBridge;
+    private readonly observer: ResizeObserver;
+    private readonly attributes: MutationObserver;
+    private readonly view: Window;
+    private frame = 0;
+    private disposed = false;
+    private last = '';
+    private pendingDelta = 0;
+    private readonly onScroll: () => void;
+
+    constructor(box: HTMLElement, viewport: HTMLElement, scroller: HTMLElement, bridge: VisualBridge) {
+        this.box = box;
+        this.viewport = viewport;
+        this.scroller = scroller;
+        this.bridge = bridge;
+        this.view = box.ownerDocument.defaultView!;
+        this.onScroll = () => this.refresh();
+        this.observer = new ResizeObserver(this.onScroll);
+        this.observer.observe(box);
+        this.observer.observe(scroller);
+        this.attributes = new MutationObserver(this.onScroll);
+        const row = box.closest('[data-index]');
+        if (row) {
+            this.attributes.observe(row, { attributes: true, attributeFilter: ['style'] });
+        }
+        scroller.addEventListener('scroll', this.onScroll, { passive: true });
+        this.refresh();
+    }
+
+    refresh(): void {
+        if (this.disposed) {
+            return;
+        }
+        const outer = this.scroller.getBoundingClientRect();
+        const box = this.box.getBoundingClientRect();
+        // A chat on a canvas can be scaled; messages inside its frame use unscaled CSS pixels.
+        const scale = outer.height / this.scroller.offsetHeight || 1;
+        const top = (box.top - outer.top) / scale - this.scroller.clientTop;
+        const available = this.scroller.clientHeight;
+        const geometry = visualViewportGeometry(this.box.offsetHeight, available, top);
+        this.viewport.style.height = `${geometry.height}px`;
+        const key = `${geometry.top}:${geometry.height}`;
+        if (key !== this.last) {
+            this.last = key;
+            this.bridge.setViewport(geometry);
+        }
+    }
+
+    scroll(request: VisualScrollRequest): void {
+        const outer = this.scroller.getBoundingClientRect();
+        const box = this.box.getBoundingClientRect();
+        if (this.disposed || box.bottom <= outer.top || box.top >= outer.bottom) {
+            return;
+        }
+        if ('by' in request) {
+            this.pendingDelta += request.by;
+            this.schedule();
+            return;
+        }
+        this.pendingDelta = 0;
+        const scale = outer.height / this.scroller.offsetHeight || 1;
+        const start = this.scroller.scrollTop + (box.top - outer.top) / scale - this.scroller.clientTop;
+        const top = 'to' in request ? start + request.to : request.edge === 'start' ? 0 : this.scroller.scrollHeight;
+        this.scroller.scrollTo({ top, behavior: 'instant' });
+        this.refresh();
+    }
+
+    dispose(): void {
+        this.disposed = true;
+        this.view.cancelAnimationFrame(this.frame);
+        this.observer.disconnect();
+        this.attributes.disconnect();
+        this.scroller.removeEventListener('scroll', this.onScroll);
+        this.bridge.setViewport(null);
+    }
+
+    private schedule(): void {
+        if (this.frame || this.disposed) {
+            return;
+        }
+        this.frame = this.view.requestAnimationFrame(() => {
+            this.frame = 0;
+            if (this.pendingDelta !== 0) {
+                this.scroller.scrollBy({ top: this.pendingDelta, behavior: 'instant' });
+                this.pendingDelta = 0;
+            }
+            this.refresh();
+        });
+    }
+}

package/src/theme.css

@@ -96,6 +96,8 @@
      * thread grows past a screenful; only the rows and the composer inside it are centered.
      */
     .chat-column .chat-column-content { margin-inline: auto; max-width: 768px; }
+    /* Wide pages clear the scrubber even when the reply column needs no extra padding. */
+    .chat-wide-content { max-width: calc(100% - 2 * var(--chat-wide-inset, 0px)); }
     /* Wider by the input's inset (`.composer-input .cm-content` padding plus the card's border), so what is typed lines up with the thread. */
     .chat-column .chat-composer-content { margin-inline: auto; max-width: calc(768px + 2 * 21px); }