@adecore/agent-contracts 0.18.4 → 0.19.0

package/dist/chat.d.ts

@@ -3383,6 +3383,10 @@ export declare const ChatVisualsResultSchema: z.ZodObject<{
         title: z.ZodString;
         at: z.ZodNumber;
         maxHeight: z.ZodNumber;
+        layout: z.ZodOptional<z.ZodEnum<{
+            inline: "inline";
+            wide: "wide";
+        }>>;
         heights: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
         size: z.ZodNumber;
         turnId: z.ZodOptional<z.ZodString>;
@@ -3396,6 +3400,10 @@ export declare const ChatVisualsEventSchema: z.ZodObject<{
         title: z.ZodString;
         at: z.ZodNumber;
         maxHeight: z.ZodNumber;
+        layout: z.ZodOptional<z.ZodEnum<{
+            inline: "inline";
+            wide: "wide";
+        }>>;
         heights: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
         size: z.ZodNumber;
         turnId: z.ZodOptional<z.ZodString>;
@@ -4815,6 +4823,10 @@ export declare const ChatAttachResultSchema: z.ZodObject<{
         title: z.ZodString;
         at: z.ZodNumber;
         maxHeight: z.ZodNumber;
+        layout: z.ZodOptional<z.ZodEnum<{
+            inline: "inline";
+            wide: "wide";
+        }>>;
         heights: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
         size: z.ZodNumber;
         turnId: z.ZodOptional<z.ZodString>;

package/dist/protocol.d.ts

@@ -1838,6 +1838,10 @@ export declare const AGENT_REQUEST_SCHEMAS: {
                 title: z.ZodString;
                 at: z.ZodNumber;
                 maxHeight: z.ZodNumber;
+                layout: z.ZodOptional<z.ZodEnum<{
+                    inline: "inline";
+                    wide: "wide";
+                }>>;
                 heights: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
                 size: z.ZodNumber;
                 turnId: z.ZodOptional<z.ZodString>;
@@ -2881,6 +2885,10 @@ export declare const AGENT_REQUEST_SCHEMAS: {
                 title: z.ZodString;
                 at: z.ZodNumber;
                 maxHeight: z.ZodNumber;
+                layout: z.ZodOptional<z.ZodEnum<{
+                    inline: "inline";
+                    wide: "wide";
+                }>>;
                 heights: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
                 size: z.ZodNumber;
                 turnId: z.ZodOptional<z.ZodString>;
@@ -4514,6 +4522,10 @@ export declare const AGENT_EVENT_SCHEMAS: {
             title: z.ZodString;
             at: z.ZodNumber;
             maxHeight: z.ZodNumber;
+            layout: z.ZodOptional<z.ZodEnum<{
+                inline: "inline";
+                wide: "wide";
+            }>>;
             heights: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
             size: z.ZodNumber;
             turnId: z.ZodOptional<z.ZodString>;

package/dist/visual-viewport.d.ts

@@ -0,0 +1,5 @@
+export declare function visualViewportScript(methods: {
+    viewportReady: string;
+    viewportChanged: string;
+    scrollRequest: string;
+}): string;

package/dist/visual-viewport.js

@@ -0,0 +1,128 @@
+// Installed by the host on every load, including pages saved with an older bootstrap.
+export function visualViewportScript(methods) {
+    return `(function () {
+var methods = ${JSON.stringify(methods)};
+var viewport = null;
+var expected = 0;
+var touch = null;
+var momentum = 0;
+var style = document.createElement('style');
+document.head.appendChild(style);
+function request(value) {
+    window.parent.postMessage({ jsonrpc: '2.0', method: methods.scrollRequest, params: value }, '*');
+}
+function stopMomentum() {
+    if (momentum) { cancelAnimationFrame(momentum); momentum = 0; }
+}
+function apply(top) {
+    window.scrollTo({ top: top, left: window.scrollX, behavior: 'instant' });
+    expected = window.scrollY;
+}
+window.addEventListener('message', function (event) {
+    var data = event.data;
+    if (event.source !== window.parent || !data || data.jsonrpc !== '2.0' || data.method !== methods.viewportChanged) { return; }
+    var next = data.params;
+    if (next === null) {
+        viewport = null;
+        style.textContent = '';
+        stopMomentum();
+        return;
+    }
+    if (!next || !Number.isFinite(next.top) || next.top < 0 || !Number.isFinite(next.height) || next.height <= 0) { return; }
+    if (viewport === null) {
+        style.textContent = 'html{overflow:hidden!important;scroll-behavior:auto!important;overflow-anchor:none!important}';
+    }
+    viewport = next;
+    apply(next.top);
+});
+function nestedScroll(path, delta, axis) {
+    for (var i = 0; i < path.length; i++) {
+        var node = path[i];
+        if (node === document.body || node === document.documentElement) { break; }
+        if (!node || node.nodeType !== 1) { continue; }
+        var css = getComputedStyle(node);
+        var horizontal = axis === 'x';
+        var overflow = horizontal ? css.overflowX : css.overflowY;
+        if (!/^(auto|scroll|overlay)$/.test(overflow)) { continue; }
+        var end = horizontal ? node.scrollWidth - node.clientWidth : node.scrollHeight - node.clientHeight;
+        if (end <= 1) { continue; }
+        var position = horizontal ? node.scrollLeft : node.scrollTop;
+        var overscroll = horizontal ? css.overscrollBehaviorX : css.overscrollBehaviorY;
+        if (overscroll === 'contain' || overscroll === 'none' || (delta < 0 ? position > 0 : position < end - 1)) { return true; }
+    }
+    return false;
+}
+window.addEventListener('wheel', function (event) {
+    if (!viewport || !event.isTrusted || event.defaultPrevented || event.ctrlKey || event.metaKey || event.shiftKey) { return; }
+    if (!event.deltaY || Math.abs(event.deltaX) > Math.abs(event.deltaY)) { return; }
+    if (nestedScroll(event.composedPath(), event.deltaY, 'y') || !event.cancelable) { return; }
+    event.preventDefault();
+    stopMomentum();
+    var unit = event.deltaMode === 2 ? viewport.height : event.deltaMode === 1 ? 16 : 1;
+    request({ by: event.deltaY * unit });
+}, { passive: false });
+window.addEventListener('keydown', function (event) {
+    if (!viewport || !event.isTrusted || event.defaultPrevented || event.ctrlKey || event.metaKey || event.altKey) { return; }
+    var target = event.target;
+    if (target && (target.isContentEditable || (typeof target.closest === 'function' && target.closest('input,textarea,select,[role="slider"],[role="spinbutton"],[role="listbox"],[role="combobox"],[role="tree"],[role="grid"],[role="menu"]')))) { return; }
+    if (event.key === ' ' && target && typeof target.closest === 'function' && target.closest('button,[role="button"]')) { return; }
+    var page = Math.max(40, viewport.height * 0.9);
+    var delta = event.key === 'ArrowDown' ? 40 : event.key === 'ArrowUp' ? -40 : event.key === 'PageDown' ? page : event.key === 'PageUp' ? -page : event.key === ' ' ? (event.shiftKey ? -page : page) : 0;
+    var edge = event.key === 'Home' ? 'start' : event.key === 'End' ? 'end' : null;
+    if ((!delta && !edge) || nestedScroll(event.composedPath(), delta || (edge === 'start' ? -1 : 1), 'y')) { return; }
+    event.preventDefault();
+    stopMomentum();
+    request(edge ? { edge: edge } : { by: delta });
+});
+window.addEventListener('touchstart', function (event) {
+    stopMomentum();
+    touch = null;
+    if (!viewport || !event.isTrusted || event.touches.length !== 1) { return; }
+    var point = event.touches[0];
+    touch = { x: point.clientX, y: point.clientY, time: performance.now(), velocity: 0, own: null, path: event.composedPath() };
+}, { passive: true });
+window.addEventListener('touchmove', function (event) {
+    if (!viewport || !touch || event.defaultPrevented || event.touches.length !== 1) { touch = null; return; }
+    var point = event.touches[0];
+    var delta = touch.y - point.clientY;
+    var horizontal = touch.x - point.clientX;
+    if (touch.own === null) {
+        if (Math.max(Math.abs(delta), Math.abs(horizontal)) < 4) { return; }
+        touch.own = Math.abs(delta) >= Math.abs(horizontal) && !nestedScroll(touch.path, delta, 'y');
+    }
+    if (!touch.own || !event.cancelable) { return; }
+    event.preventDefault();
+    var now = performance.now();
+    touch.velocity = Math.max(-4, Math.min(4, delta / Math.max(1, now - touch.time)));
+    touch.x = point.clientX;
+    touch.y = point.clientY;
+    touch.time = now;
+    request({ by: delta });
+}, { passive: false });
+window.addEventListener('touchend', function () {
+    if (!touch) { return; }
+    var velocity = touch.own && performance.now() - touch.time < 80 ? touch.velocity : 0;
+    touch = null;
+    var last = performance.now();
+    var tick = function (now) {
+        momentum = 0;
+        if (!viewport || Math.abs(velocity) < 0.02) { return; }
+        var elapsed = Math.min(32, now - last);
+        last = now;
+        var decay = Math.exp(-elapsed / 180);
+        request({ by: velocity * 180 * (1 - decay) });
+        velocity *= decay;
+        momentum = requestAnimationFrame(tick);
+    };
+    if (Math.abs(velocity) >= 0.02) { momentum = requestAnimationFrame(tick); }
+}, { passive: true });
+window.addEventListener('touchcancel', function () { touch = null; stopMomentum(); }, { passive: true });
+window.addEventListener('scroll', function () {
+    if (!viewport || Math.abs(window.scrollY - expected) < 1) { return; }
+    // Focus, fragment links and scrollIntoView can scroll an overflow-hidden document.
+    expected = window.scrollY;
+    request({ to: expected });
+}, { passive: true });
+window.parent.postMessage({ jsonrpc: '2.0', method: methods.viewportReady }, '*');
+})();`;
+}

package/dist/visual.d.ts

@@ -9,11 +9,20 @@ export declare const VISUAL_LIMITS: {
 export declare const VISUAL_MEASURE_WIDTHS: readonly number[];
 export declare const VisualHeightSchema: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
 export type VisualHeight = z.infer<typeof VisualHeightSchema>;
+export declare const VisualLayoutSchema: z.ZodEnum<{
+    inline: "inline";
+    wide: "wide";
+}>;
+export type VisualLayout = z.infer<typeof VisualLayoutSchema>;
 export declare const ChatVisualSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
     at: z.ZodNumber;
     maxHeight: z.ZodNumber;
+    layout: z.ZodOptional<z.ZodEnum<{
+        inline: "inline";
+        wide: "wide";
+    }>>;
     heights: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
     size: z.ZodNumber;
     turnId: z.ZodOptional<z.ZodString>;
@@ -24,6 +33,10 @@ export declare const ChatVisualsSchema: z.ZodArray<z.ZodObject<{
     title: z.ZodString;
     at: z.ZodNumber;
     maxHeight: z.ZodNumber;
+    layout: z.ZodOptional<z.ZodEnum<{
+        inline: "inline";
+        wide: "wide";
+    }>>;
     heights: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
     size: z.ZodNumber;
     turnId: z.ZodOptional<z.ZodString>;
@@ -35,6 +48,9 @@ export declare const VISUAL_BRIDGE_METHODS: {
     readonly hostContextChanged: 'ui/notifications/host-context-changed';
     readonly sizeChanged: 'ui/notifications/size-changed';
     readonly openLink: 'ui/open-link';
+    readonly viewportReady: 'adecore/visual/viewport-ready';
+    readonly viewportChanged: 'adecore/visual/viewport-changed';
+    readonly scrollRequest: 'adecore/visual/scroll-request';
 };
 export type VisualAppearance = 'light' | 'dark';
 export interface VisualTheme {
@@ -42,6 +58,27 @@ export interface VisualTheme {
     variables: Readonly<Record<string, string>>;
 }
 export type VisualRequestId = string | number;
+export interface VisualViewport {
+    top: number;
+    height: number;
+}
+export type VisualScrollRequest = {
+    by: number;
+} | {
+    to: number;
+} | {
+    edge: 'start' | 'end';
+};
+export declare function visualViewportMessage(viewport: VisualViewport | null): {
+    readonly jsonrpc: '2.0';
+    readonly method: "adecore/visual/viewport-changed";
+    readonly params: VisualViewport | null;
+};
+export declare function visualScrollMessage(request: VisualScrollRequest): {
+    readonly jsonrpc: '2.0';
+    readonly method: "adecore/visual/scroll-request";
+    readonly params: VisualScrollRequest;
+};
 export type VisualMessage = {
     method: typeof VISUAL_BRIDGE_METHODS.sandboxProxyReady;
 } | {
@@ -58,6 +95,14 @@ export type VisualMessage = {
     method: typeof VISUAL_BRIDGE_METHODS.openLink;
     id: VisualRequestId;
     url: string;
+} | {
+    method: typeof VISUAL_BRIDGE_METHODS.viewportReady;
+} | {
+    method: typeof VISUAL_BRIDGE_METHODS.viewportChanged;
+    viewport: VisualViewport | null;
+} | {
+    method: typeof VISUAL_BRIDGE_METHODS.scrollRequest;
+    request: VisualScrollRequest;
 };
 export declare function visualProxyReadyMessage(): {
     readonly jsonrpc: '2.0';

package/dist/visual.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { visualViewportScript } from './visual-viewport.js';
 /*
  * What a host accepts when an agent publishes a visual. The schemas below check shapes only, so a
  * host that widens a limit never makes an older client refuse a whole attach.
@@ -17,6 +18,7 @@ export const VISUAL_LIMITS = {
 export const VISUAL_MEASURE_WIDTHS = [320, 400, 480, 560, 640, 720, 800, 900, 1000, 1200];
 // `[width, height]` of a page measured in a frame that wide, in CSS pixels.
 export const VisualHeightSchema = z.tuple([z.number().positive(), z.number().nonnegative()]);
+export const VisualLayoutSchema = z.enum(['inline', 'wide']);
 /*
  * A page an agent published in a chat, shown in the thread at `at`. It lives beside the chat in the
  * host's data folder and goes with the chat, a clear of it, or a person who removes it.
@@ -28,6 +30,8 @@ export const ChatVisualSchema = z.object({
     // On the clock of an item's `createdAt`, which is what places the visual among the items.
     at: z.number(),
     maxHeight: z.number().positive(),
+    // Absent on older visuals, which keep the reply column's width.
+    layout: VisualLayoutSchema.optional(),
     // Ascending by width; absent while nobody measured the page.
     heights: z.array(VisualHeightSchema).optional(),
     // Bytes of the stored page.
@@ -74,8 +78,18 @@ export const VISUAL_BRIDGE_METHODS = {
     // From the page to the app: the size of its document.
     sizeChanged: 'ui/notifications/size-changed',
     // From the page to the app, as a request: a link to open outside the frame.
-    openLink: 'ui/open-link'
+    openLink: 'ui/open-link',
+    // Host extensions, independent of the bootstrap stored with a page.
+    viewportReady: 'adecore/visual/viewport-ready',
+    viewportChanged: 'adecore/visual/viewport-changed',
+    scrollRequest: 'adecore/visual/scroll-request'
 };
+export function visualViewportMessage(viewport) {
+    return { jsonrpc: '2.0', method: VISUAL_BRIDGE_METHODS.viewportChanged, params: viewport };
+}
+export function visualScrollMessage(request) {
+    return { jsonrpc: '2.0', method: VISUAL_BRIDGE_METHODS.scrollRequest, params: request };
+}
 export function visualProxyReadyMessage() {
     return { jsonrpc: '2.0', method: VISUAL_BRIDGE_METHODS.sandboxProxyReady };
 }
@@ -146,6 +160,26 @@ export function parseVisualMessage(data) {
             }
             return width === undefined ? { method: data.method, height } : { method: data.method, width, height };
         }
+        case VISUAL_BRIDGE_METHODS.viewportReady:
+            return { method: data.method };
+        case VISUAL_BRIDGE_METHODS.viewportChanged: {
+            if (data.params === null) {
+                return { method: data.method, viewport: null };
+            }
+            const top = sizeOf(params.top);
+            const height = sizeOf(params.height);
+            return top !== undefined && height !== undefined && height > 0 ? { method: data.method, viewport: { top, height } } : undefined;
+        }
+        case VISUAL_BRIDGE_METHODS.scrollRequest: {
+            if (typeof params.by === 'number' && Number.isFinite(params.by)) {
+                return { method: data.method, request: { by: Math.max(-100_000, Math.min(params.by, 100_000)) } };
+            }
+            const top = sizeOf(params.to);
+            if (top !== undefined) {
+                return { method: data.method, request: { to: top } };
+            }
+            return params.edge === 'start' || params.edge === 'end' ? { method: data.method, request: { edge: params.edge } } : undefined;
+        }
         case VISUAL_BRIDGE_METHODS.openLink: {
             const url = webUrl(params.url);
             const id = data.id;
@@ -302,8 +336,9 @@ export function visualThemeFragment(theme) {
 export const VISUAL_PAGE_RULES = `A visual is one self-contained HTML document of at most ${VISUAL_LIMITS.bytes / 1024 / 1024} MiB: styles in an inline <style>, code in an inline <script>, ` +
     'and the data it shows inlined. Public http(s) URLs load as they are, so a chart library from a CDN or an image on the web works; ' +
     'relative paths and local files do not. Prefer inline SVG or a canvas when the drawing needs no library. A link to an http(s) page opens in the browser.';
-export const VISUAL_LAYOUT_GUIDE = "The page appears in the reply as a borderless frame on the thread's own background, as wide as the reply column: " +
-    'about 360px on a phone and up to about 1200px on a wide screen. Lay it out at a fluid width (percentages, flex, grid) ' +
+export const VISUAL_LAYOUT_GUIDE = "The page appears as a borderless frame on the thread's own background. By default it follows the reply column (up to 768px in a chat view). " +
+    'Opt into the wide layout for application mockups or dashboards that need more space: the host uses the available chat pane width with side margins. ' +
+    'Both layouts shrink on narrow screens. Lay the page out at a fluid width (percentages, flex, grid) ' +
     'with no horizontal padding on the outermost element. Draw no outer card, border, shadow or banner title: the page is part of the reply. ' +
     'The frame takes the height of the page, so give a chart a fixed height in pixels, never one relative to the viewport.';
 export const VISUAL_THEME_GUIDE = `The page is themed through CSS custom properties on :root that follow the app's light and dark appearance live: ${VISUAL_THEME_VARIABLES.join(', ')}. ` +
@@ -603,6 +638,9 @@ window.addEventListener('message', function (event) {
     document.open();
     document.write(params.html);
     document.close();
+    var viewport = document.createElement('script');
+    viewport.textContent = ${inlineJson(visualViewportScript(VISUAL_BRIDGE_METHODS))};
+    document.head.appendChild(viewport);
 });
 window.parent.postMessage({ jsonrpc: '2.0', method: methods.ready }, '*');
 })();`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agent-contracts",
-  "version": "0.18.4",
+  "version": "0.19.0",
   "description": "Schemas and port contracts for agent chats, provider accounts, models and usage.",
   "type": "module",
   "exports": {

package/src/visual-viewport.ts

@@ -0,0 +1,128 @@
+// Installed by the host on every load, including pages saved with an older bootstrap.
+export function visualViewportScript(methods: { viewportReady: string; viewportChanged: string; scrollRequest: string }): string {
+    return `(function () {
+var methods = ${JSON.stringify(methods)};
+var viewport = null;
+var expected = 0;
+var touch = null;
+var momentum = 0;
+var style = document.createElement('style');
+document.head.appendChild(style);
+function request(value) {
+    window.parent.postMessage({ jsonrpc: '2.0', method: methods.scrollRequest, params: value }, '*');
+}
+function stopMomentum() {
+    if (momentum) { cancelAnimationFrame(momentum); momentum = 0; }
+}
+function apply(top) {
+    window.scrollTo({ top: top, left: window.scrollX, behavior: 'instant' });
+    expected = window.scrollY;
+}
+window.addEventListener('message', function (event) {
+    var data = event.data;
+    if (event.source !== window.parent || !data || data.jsonrpc !== '2.0' || data.method !== methods.viewportChanged) { return; }
+    var next = data.params;
+    if (next === null) {
+        viewport = null;
+        style.textContent = '';
+        stopMomentum();
+        return;
+    }
+    if (!next || !Number.isFinite(next.top) || next.top < 0 || !Number.isFinite(next.height) || next.height <= 0) { return; }
+    if (viewport === null) {
+        style.textContent = 'html{overflow:hidden!important;scroll-behavior:auto!important;overflow-anchor:none!important}';
+    }
+    viewport = next;
+    apply(next.top);
+});
+function nestedScroll(path, delta, axis) {
+    for (var i = 0; i < path.length; i++) {
+        var node = path[i];
+        if (node === document.body || node === document.documentElement) { break; }
+        if (!node || node.nodeType !== 1) { continue; }
+        var css = getComputedStyle(node);
+        var horizontal = axis === 'x';
+        var overflow = horizontal ? css.overflowX : css.overflowY;
+        if (!/^(auto|scroll|overlay)$/.test(overflow)) { continue; }
+        var end = horizontal ? node.scrollWidth - node.clientWidth : node.scrollHeight - node.clientHeight;
+        if (end <= 1) { continue; }
+        var position = horizontal ? node.scrollLeft : node.scrollTop;
+        var overscroll = horizontal ? css.overscrollBehaviorX : css.overscrollBehaviorY;
+        if (overscroll === 'contain' || overscroll === 'none' || (delta < 0 ? position > 0 : position < end - 1)) { return true; }
+    }
+    return false;
+}
+window.addEventListener('wheel', function (event) {
+    if (!viewport || !event.isTrusted || event.defaultPrevented || event.ctrlKey || event.metaKey || event.shiftKey) { return; }
+    if (!event.deltaY || Math.abs(event.deltaX) > Math.abs(event.deltaY)) { return; }
+    if (nestedScroll(event.composedPath(), event.deltaY, 'y') || !event.cancelable) { return; }
+    event.preventDefault();
+    stopMomentum();
+    var unit = event.deltaMode === 2 ? viewport.height : event.deltaMode === 1 ? 16 : 1;
+    request({ by: event.deltaY * unit });
+}, { passive: false });
+window.addEventListener('keydown', function (event) {
+    if (!viewport || !event.isTrusted || event.defaultPrevented || event.ctrlKey || event.metaKey || event.altKey) { return; }
+    var target = event.target;
+    if (target && (target.isContentEditable || (typeof target.closest === 'function' && target.closest('input,textarea,select,[role="slider"],[role="spinbutton"],[role="listbox"],[role="combobox"],[role="tree"],[role="grid"],[role="menu"]')))) { return; }
+    if (event.key === ' ' && target && typeof target.closest === 'function' && target.closest('button,[role="button"]')) { return; }
+    var page = Math.max(40, viewport.height * 0.9);
+    var delta = event.key === 'ArrowDown' ? 40 : event.key === 'ArrowUp' ? -40 : event.key === 'PageDown' ? page : event.key === 'PageUp' ? -page : event.key === ' ' ? (event.shiftKey ? -page : page) : 0;
+    var edge = event.key === 'Home' ? 'start' : event.key === 'End' ? 'end' : null;
+    if ((!delta && !edge) || nestedScroll(event.composedPath(), delta || (edge === 'start' ? -1 : 1), 'y')) { return; }
+    event.preventDefault();
+    stopMomentum();
+    request(edge ? { edge: edge } : { by: delta });
+});
+window.addEventListener('touchstart', function (event) {
+    stopMomentum();
+    touch = null;
+    if (!viewport || !event.isTrusted || event.touches.length !== 1) { return; }
+    var point = event.touches[0];
+    touch = { x: point.clientX, y: point.clientY, time: performance.now(), velocity: 0, own: null, path: event.composedPath() };
+}, { passive: true });
+window.addEventListener('touchmove', function (event) {
+    if (!viewport || !touch || event.defaultPrevented || event.touches.length !== 1) { touch = null; return; }
+    var point = event.touches[0];
+    var delta = touch.y - point.clientY;
+    var horizontal = touch.x - point.clientX;
+    if (touch.own === null) {
+        if (Math.max(Math.abs(delta), Math.abs(horizontal)) < 4) { return; }
+        touch.own = Math.abs(delta) >= Math.abs(horizontal) && !nestedScroll(touch.path, delta, 'y');
+    }
+    if (!touch.own || !event.cancelable) { return; }
+    event.preventDefault();
+    var now = performance.now();
+    touch.velocity = Math.max(-4, Math.min(4, delta / Math.max(1, now - touch.time)));
+    touch.x = point.clientX;
+    touch.y = point.clientY;
+    touch.time = now;
+    request({ by: delta });
+}, { passive: false });
+window.addEventListener('touchend', function () {
+    if (!touch) { return; }
+    var velocity = touch.own && performance.now() - touch.time < 80 ? touch.velocity : 0;
+    touch = null;
+    var last = performance.now();
+    var tick = function (now) {
+        momentum = 0;
+        if (!viewport || Math.abs(velocity) < 0.02) { return; }
+        var elapsed = Math.min(32, now - last);
+        last = now;
+        var decay = Math.exp(-elapsed / 180);
+        request({ by: velocity * 180 * (1 - decay) });
+        velocity *= decay;
+        momentum = requestAnimationFrame(tick);
+    };
+    if (Math.abs(velocity) >= 0.02) { momentum = requestAnimationFrame(tick); }
+}, { passive: true });
+window.addEventListener('touchcancel', function () { touch = null; stopMomentum(); }, { passive: true });
+window.addEventListener('scroll', function () {
+    if (!viewport || Math.abs(window.scrollY - expected) < 1) { return; }
+    // Focus, fragment links and scrollIntoView can scroll an overflow-hidden document.
+    expected = window.scrollY;
+    request({ to: expected });
+}, { passive: true });
+window.parent.postMessage({ jsonrpc: '2.0', method: methods.viewportReady }, '*');
+})();`;
+}

package/src/visual.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { visualViewportScript } from './visual-viewport.ts';
 
 /*
  * What a host accepts when an agent publishes a visual. The schemas below check shapes only, so a
@@ -22,6 +23,9 @@ export const VISUAL_MEASURE_WIDTHS: readonly number[] = [320, 400, 480, 560, 640
 export const VisualHeightSchema = z.tuple([z.number().positive(), z.number().nonnegative()]);
 export type VisualHeight = z.infer<typeof VisualHeightSchema>;
 
+export const VisualLayoutSchema = z.enum(['inline', 'wide']);
+export type VisualLayout = z.infer<typeof VisualLayoutSchema>;
+
 /*
  * A page an agent published in a chat, shown in the thread at `at`. It lives beside the chat in the
  * host's data folder and goes with the chat, a clear of it, or a person who removes it.
@@ -33,6 +37,8 @@ export const ChatVisualSchema = z.object({
     // On the clock of an item's `createdAt`, which is what places the visual among the items.
     at: z.number(),
     maxHeight: z.number().positive(),
+    // Absent on older visuals, which keep the reply column's width.
+    layout: VisualLayoutSchema.optional(),
     // Ascending by width; absent while nobody measured the page.
     heights: z.array(VisualHeightSchema).optional(),
     // Bytes of the stored page.
@@ -84,7 +90,11 @@ export const VISUAL_BRIDGE_METHODS = {
     // From the page to the app: the size of its document.
     sizeChanged: 'ui/notifications/size-changed',
     // From the page to the app, as a request: a link to open outside the frame.
-    openLink: 'ui/open-link'
+    openLink: 'ui/open-link',
+    // Host extensions, independent of the bootstrap stored with a page.
+    viewportReady: 'adecore/visual/viewport-ready',
+    viewportChanged: 'adecore/visual/viewport-changed',
+    scrollRequest: 'adecore/visual/scroll-request'
 } as const;
 
 export type VisualAppearance = 'light' | 'dark';
@@ -97,13 +107,31 @@ export interface VisualTheme {
 
 export type VisualRequestId = string | number;
 
+export interface VisualViewport {
+    top: number;
+    height: number;
+}
+
+export type VisualScrollRequest = { by: number } | { to: number } | { edge: 'start' | 'end' };
+
+export function visualViewportMessage(viewport: VisualViewport | null) {
+    return { jsonrpc: '2.0', method: VISUAL_BRIDGE_METHODS.viewportChanged, params: viewport } as const;
+}
+
+export function visualScrollMessage(request: VisualScrollRequest) {
+    return { jsonrpc: '2.0', method: VISUAL_BRIDGE_METHODS.scrollRequest, params: request } as const;
+}
+
 // A message of the bridge as one side reads it from the other.
 export type VisualMessage =
     | { method: typeof VISUAL_BRIDGE_METHODS.sandboxProxyReady }
     | { method: typeof VISUAL_BRIDGE_METHODS.sandboxResourceReady; html: string }
     | { method: typeof VISUAL_BRIDGE_METHODS.hostContextChanged; theme: VisualTheme }
     | { method: typeof VISUAL_BRIDGE_METHODS.sizeChanged; width?: number; height: number }
-    | { method: typeof VISUAL_BRIDGE_METHODS.openLink; id: VisualRequestId; url: string };
+    | { method: typeof VISUAL_BRIDGE_METHODS.openLink; id: VisualRequestId; url: string }
+    | { method: typeof VISUAL_BRIDGE_METHODS.viewportReady }
+    | { method: typeof VISUAL_BRIDGE_METHODS.viewportChanged; viewport: VisualViewport | null }
+    | { method: typeof VISUAL_BRIDGE_METHODS.scrollRequest; request: VisualScrollRequest };
 
 export function visualProxyReadyMessage() {
     return { jsonrpc: '2.0', method: VISUAL_BRIDGE_METHODS.sandboxProxyReady } as const;
@@ -186,6 +214,26 @@ export function parseVisualMessage(data: unknown): VisualMessage | undefined {
             }
             return width === undefined ? { method: data.method, height } : { method: data.method, width, height };
         }
+        case VISUAL_BRIDGE_METHODS.viewportReady:
+            return { method: data.method };
+        case VISUAL_BRIDGE_METHODS.viewportChanged: {
+            if (data.params === null) {
+                return { method: data.method, viewport: null };
+            }
+            const top = sizeOf(params.top);
+            const height = sizeOf(params.height);
+            return top !== undefined && height !== undefined && height > 0 ? { method: data.method, viewport: { top, height } } : undefined;
+        }
+        case VISUAL_BRIDGE_METHODS.scrollRequest: {
+            if (typeof params.by === 'number' && Number.isFinite(params.by)) {
+                return { method: data.method, request: { by: Math.max(-100_000, Math.min(params.by, 100_000)) } };
+            }
+            const top = sizeOf(params.to);
+            if (top !== undefined) {
+                return { method: data.method, request: { to: top } };
+            }
+            return params.edge === 'start' || params.edge === 'end' ? { method: data.method, request: { edge: params.edge } } : undefined;
+        }
         case VISUAL_BRIDGE_METHODS.openLink: {
             const url = webUrl(params.url);
             const id = data.id;
@@ -356,8 +404,9 @@ export const VISUAL_PAGE_RULES =
     'relative paths and local files do not. Prefer inline SVG or a canvas when the drawing needs no library. A link to an http(s) page opens in the browser.';
 
 export const VISUAL_LAYOUT_GUIDE =
-    "The page appears in the reply as a borderless frame on the thread's own background, as wide as the reply column: " +
-    'about 360px on a phone and up to about 1200px on a wide screen. Lay it out at a fluid width (percentages, flex, grid) ' +
+    "The page appears as a borderless frame on the thread's own background. By default it follows the reply column (up to 768px in a chat view). " +
+    'Opt into the wide layout for application mockups or dashboards that need more space: the host uses the available chat pane width with side margins. ' +
+    'Both layouts shrink on narrow screens. Lay the page out at a fluid width (percentages, flex, grid) ' +
     'with no horizontal padding on the outermost element. Draw no outer card, border, shadow or banner title: the page is part of the reply. ' +
     'The frame takes the height of the page, so give a chart a fixed height in pixels, never one relative to the viewport.';
 
@@ -678,6 +727,9 @@ window.addEventListener('message', function (event) {
     document.open();
     document.write(params.html);
     document.close();
+    var viewport = document.createElement('script');
+    viewport.textContent = ${inlineJson(visualViewportScript(VISUAL_BRIDGE_METHODS))};
+    document.head.appendChild(viewport);
 });
 window.parent.postMessage({ jsonrpc: '2.0', method: methods.ready }, '*');
 })();`;