fix(web): inline HTML renders no longer trap the thread's scroll

apps/server/src/mcp/toolkits/html/tools.ts

@@ -68,15 +68,15 @@ export const HtmlPreviewTool = Tool.make("html_preview", {
 // touches no workspace, so plan mode and read-only sandboxes can use it.
 // Open-world, since the page may load remote resources, as in a preview.
 const HtmlRenderTool = Tool.make(HTML_RENDER_TOOL_NAME, {
-  description: `Show a finished HTML page (chart, table, diagram, collage, mockup) inline in this thread, above your final text reply; call it before writing that reply. The reader already sees the page, so the reply should not announce it, say where it is, or restate it: add only what the page doesn't say. Preview with html_preview first. T3 fits the frame to the page's height at each reader's width, up to height; anything taller scrolls inside the frame. ${PAGE_RULES} ${HTML_RENDER_LAYOUT_GUIDE} ${HTML_RENDER_THEME_GUIDE}`,
+  description: `Show a finished HTML page (chart, table, diagram, collage, mockup) inline in this thread, above your final text reply; call it before writing that reply. The reader already sees the page, so the reply should not announce it, say where it is, or restate it: add only what the page doesn't say. Preview with html_preview first. T3 fits the frame to the page's height at each reader's width. A height below the page's contentHeight caps the frame there, and the rest scrolls inside it. ${PAGE_RULES} ${HTML_RENDER_LAYOUT_GUIDE} ${HTML_RENDER_THEME_GUIDE}`,
   parameters: Schema.Struct({
     html: Html,
     title: Schema.String.check(
       Schema.isMinLength(1),
       Schema.isMaxLength(HTML_RENDER_MAX_TITLE_LENGTH),
     ).annotate({ description: "Short name for the page." }),
     height: Schema.Int.annotate({
-      description: `The most the frame may take, in CSS pixels, ${HTML_RENDER_MIN_HEIGHT}-${HTML_RENDER_MAX_HEIGHT}. Use html_preview's contentHeight, or less to make long content scroll inside the frame.`,
+      description: `The frame height in CSS pixels, ${HTML_RENDER_MIN_HEIGHT}-${HTML_RENDER_MAX_HEIGHT}. Use html_preview's contentHeight, or less to make long content scroll inside the frame.`,
     }),
   }),
   success: Schema.Struct({

apps/web/src/components/chat/HtmlRenderFrame.tsx

@@ -20,8 +20,9 @@ const MIN_URL_LIFE_MS = 5 * 60_000;
 
 /**
  * An agent's HTML render inline in the thread: the page itself on the thread's
- * own background, at its measured height for this width (capped at the agent's
- * height). Loading and failure hold the same box so nothing below it moves.
+ * own background, at the server's measured height for this width until the
+ * page reports its own. Loading and failure hold the same box so nothing below
+ * it moves.
  */
 export function HtmlRenderFrame(props: {
   readonly environmentId: EnvironmentId;
@@ -43,7 +44,10 @@ export function HtmlRenderFrame(props: {
     observer.observe(box);
     return () => observer.disconnect();
   }, []);
-  const height = htmlRenderFrameHeight(props.htmlRender, width);
+  // Client fonts can wrap a page taller than the server measured it; a frame
+  // left short would scroll inside the thread and take the reader's scroll.
+  const [contentHeight, setContentHeight] = useState<number>();
+  const height = htmlRenderFrameHeight(props.htmlRender, width, contentHeight);
   const fileName = htmlRenderFileName(title);
   const resource = useMemo(
     () => ({
@@ -91,7 +95,12 @@ export function HtmlRenderFrame(props: {
     <div ref={boxRef} className="group/html-render relative" style={{ height }}>
       {src !== null ? (
         <>
-          <HtmlRenderDocument src={src} title={title} className="block size-full" />
+          <HtmlRenderDocument
+            src={src}
+            title={title}
+            className="block size-full"
+            onContentHeight={setContentHeight}
+          />
           <div className="absolute end-2 top-2 opacity-0 transition-opacity duration-150 focus-within:opacity-100 group-hover/html-render:opacity-100 pointer-coarse:opacity-100">
             <Tooltip>
               <TooltipTrigger

apps/web/src/components/files/BrowserDocumentFrame.tsx

@@ -2,9 +2,10 @@ import {
   htmlRenderThemeFragment,
   htmlRenderThemeMessage,
   htmlRenderResult,
+  readHtmlRenderContentHeight,
   readHtmlRenderLinkRequest,
 } from "@t3tools/shared/htmlRender";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
 
 import { useHtmlRenderTheme } from "~/hooks/useHtmlRenderTheme";
 import { cn } from "~/lib/utils";
@@ -69,6 +70,8 @@ export function HtmlRenderDocument(props: {
   readonly src: string;
   readonly title: string;
   readonly className?: string;
+  /** Receives the page's content height whenever it changes, so an inline frame can fit it. */
+  readonly onContentHeight?: (height: number) => void;
 }) {
   const theme = useHtmlRenderTheme();
   const frameRef = useRef<HTMLIFrameElement>(null);
@@ -102,6 +105,20 @@ export function HtmlRenderDocument(props: {
     window.addEventListener("message", openLink);
     return () => window.removeEventListener("message", openLink);
   }, []);
+  const { onContentHeight } = props;
+  // A page posts its height once per change, so listen from the commit that
+  // inserts the frame; a passive effect could run after a fast page's first post.
+  useLayoutEffect(() => {
+    if (onContentHeight === undefined) return;
+    const resize = (event: MessageEvent) => {
+      const height = readHtmlRenderContentHeight(event.data);
+      if (height !== undefined && event.source === frameRef.current?.contentWindow) {
+        onContentHeight(height);
+      }
+    };
+    window.addEventListener("message", resize);
+    return () => window.removeEventListener("message", resize);
+  }, [onContentHeight]);
   return (
     <iframe
       ref={frameRef}

packages/shared/src/htmlRender.test.ts

@@ -1,12 +1,14 @@
 import { describe, expect, it } from "vite-plus/test";
 
 import {
+  HTML_RENDER_MAX_HEIGHT,
   htmlRenderFrameHeight,
   htmlRenderReferencesEqual,
   htmlRenderTheme,
   htmlRenderThemeFragment,
   injectHtmlRenderBootstrap,
   htmlRenderThemeMessage,
+  readHtmlRenderContentHeight,
   readHtmlRenderLinkRequest,
   readHtmlRenderReference,
 } from "./htmlRender.ts";
@@ -99,6 +101,22 @@ describe("readHtmlRenderLinkRequest", () => {
   });
 });
 
+describe("readHtmlRenderContentHeight", () => {
+  it("reads only the height of an MCP Apps size-changed notification", () => {
+    const notification = (params: unknown) => ({
+      jsonrpc: "2.0",
+      method: "ui/notifications/size-changed",
+      params,
+    });
+    expect(readHtmlRenderContentHeight(notification({ height: 412 }))).toBe(412);
+    expect(readHtmlRenderContentHeight(notification({ height: "412" }))).toBe(undefined);
+    expect(readHtmlRenderContentHeight(notification({ height: 0 }))).toBe(undefined);
+    expect(readHtmlRenderContentHeight({ ...notification({ height: 412 }), method: "x" })).toBe(
+      undefined,
+    );
+  });
+});
+
 describe("htmlRenderThemeMessage", () => {
   it("is an MCP Apps host-context-changed notification carrying the theme variables", () => {
     const theme = htmlRenderTheme(T3_CODE_DARK_THEME_COLORS, "dark");
@@ -193,9 +211,21 @@ describe("htmlRenderFrameHeight", () => {
     expect(htmlRenderFrameHeight(responsive, 640)).toBe(450);
   });
 
-  it("never exceeds the agent's height and falls back to it without measurements", () => {
-    expect(htmlRenderFrameHeight(measured, 1400)).toBe(1500);
+  it("fits a page the client lays out taller than the server measured", () => {
+    // The agent passed contentHeight at the column width, so the page should never scroll.
+    const fitted = { ...measured, height: 1403 };
+    expect(htmlRenderFrameHeight(fitted, 728, 1415)).toBe(1415);
+    expect(htmlRenderFrameHeight(fitted, 1400)).toBe(1660);
+    expect(htmlRenderFrameHeight(fitted, 728, 5000)).toBe(HTML_RENDER_MAX_HEIGHT);
+  });
+
+  it("keeps the agent's height when it asked for a scrolling frame or the page is unmeasured", () => {
+    const scrolling = { ...measured, height: 600 };
+    expect(htmlRenderFrameHeight(scrolling, 728, 1415)).toBe(600);
+    expect(htmlRenderFrameHeight(scrolling, 1400)).toBe(600);
     expect(htmlRenderFrameHeight(reference, 728)).toBe(reference.height);
+    expect(htmlRenderFrameHeight(reference, 728, 900)).toBe(reference.height);
+    expect(htmlRenderFrameHeight(reference, 728, 300)).toBe(300);
   });
 
   it("drops a malformed table and compares tables by value", () => {

packages/shared/src/htmlRender.ts

@@ -98,22 +98,37 @@ export function htmlRenderReferencesEqual(left: HtmlRenderReference, right: Html
   );
 }
 
-/**
- * The frame height for a page at a frame width: the taller of the heights
- * measured at the nearest widths on each side, capped at the agent's height.
- * A breakpoint between two measured widths can make the page as tall as
- * either, so the frame takes the taller. A page whose height grows with its
- * width inside one layout can still run slightly past the frame between
- * measured widths.
- */
-export function htmlRenderFrameHeight(reference: HtmlRenderReference, width: number) {
-  const heights = reference.heights;
-  if (heights === undefined || heights.length === 0) return reference.height;
+// The taller of the heights measured at the nearest widths on each side. A
+// breakpoint between two measured widths can make the page as tall as either.
+function measuredHeight(heights: NonNullable<HtmlRenderReference["heights"]>, width: number) {
   const above = heights.findIndex(([measuredWidth]) => measuredWidth >= width);
   const high = above === -1 ? heights.length - 1 : above;
   const low = heights[high]![0] === width ? high : Math.max(0, high - 1);
-  const measured = Math.max(heights[low]![1], heights[high]![1]);
-  return clampHtmlRenderHeight(Math.min(reference.height, measured));
+  return Math.max(heights[low]![1], heights[high]![1]);
+}
+
+/**
+ * The frame height for a page at a frame width. It is the page's own reported
+ * `contentHeight` when the client has one, else the server's measurement for
+ * that width. A page even a few pixels taller than its frame scrolls inside it
+ * and takes the reader's scroll, so the frame fits the page. The agent's height
+ * caps it only when it is below the page's height at the column width (the
+ * agent asked for a scrolling frame) or when the page was never measured.
+ */
+export function htmlRenderFrameHeight(
+  reference: HtmlRenderReference,
+  width: number,
+  contentHeight?: number,
+) {
+  const heights = reference.heights;
+  if (heights === undefined || heights.length === 0) {
+    return clampHtmlRenderHeight(Math.min(reference.height, contentHeight ?? reference.height));
+  }
+  const cap =
+    measuredHeight(heights, HTML_RENDER_COLUMN_WIDTH) > reference.height
+      ? reference.height
+      : HTML_RENDER_MAX_HEIGHT;
+  return clampHtmlRenderHeight(Math.min(cap, contentHeight ?? measuredHeight(heights, width)));
 }
 
 /** A readable download name: the title without characters file systems reject. */
@@ -248,13 +263,27 @@ export const HTML_RENDER_LAYOUT_GUIDE = [
   `The frame is borderless on the thread's background, as wide as the reply column (${HTML_RENDER_COLUMN_WIDTH}px on desktop by default, wider if the reader widens chat, about 360px on phones), and its left edge lines up with your reply text.`,
   "Use a fluid width with no horizontal padding on the outermost element, and no outer card, border, or banner title: the page is part of your reply.",
   "Give charts fixed pixel heights rather than heights that scale with width.",
+  "Let content set the page's height. Avoid viewport-based heights such as 100vh or height:100% on html or body; the frame grows to fit the page, so they can make it grow again and again.",
 ].join(" ");
 
 // The bridge between a render and its client speaks the MCP Apps protocol
 // (JSON-RPC over postMessage), so the same host code can later drive upstream
 // MCP apps: https://github.com/modelcontextprotocol/ext-apps
 const HOST_CONTEXT_CHANGED_METHOD = "ui/notifications/host-context-changed";
 const OPEN_LINK_METHOD = "ui/open-link";
+const SIZE_CHANGED_METHOD = "ui/notifications/size-changed";
+
+/** The content height in a framed render's `ui/notifications/size-changed` notification. */
+export function readHtmlRenderContentHeight(data: unknown): number | undefined {
+  if (typeof data !== "object" || data === null) return undefined;
+  const { jsonrpc, method, params } = data as Record<string, unknown>;
+  if (jsonrpc !== "2.0" || method !== SIZE_CHANGED_METHOD) return undefined;
+  const height =
+    typeof params === "object" && params !== null
+      ? (params as { height?: unknown }).height
+      : undefined;
+  return typeof height === "number" && Number.isFinite(height) && height > 0 ? height : undefined;
+}
 
 /** A render's `ui/open-link` request, if `data` is one with an http(s) URL. */
 export function readHtmlRenderLinkRequest(
@@ -309,8 +338,10 @@ function rootRule(theme: HtmlRenderTheme): string {
 // then drops the fragment so a page's own hash routing never sees it. A link
 // the reader clicks to another page never replaces the page inside the thread:
 // a framed page asks its client to open it, and a top-level page (mobile)
-// opens it as a new window, which the client sends to the browser.
-const BOOTSTRAP_SCRIPT = `(function(){var s=document.getElementById("t3-theme"),n=0;if(!s)return;var b=${JSON.stringify(BASE_CSS)};function a(t){if(!t||typeof t!=="object"||!t.variables||typeof t.variables!=="object")return;var c=":root{color-scheme:"+(t.appearance==="light"?"light":"dark")+";";for(var k in t.variables){if(/^--[a-z0-9-]+$/.test(k))c+=k+":"+String(t.variables[k]).replace(/[;{}<>]/g,"")+";";}s.textContent=c+"}"+b;}try{var m=/[#&]${THEME_FRAGMENT_KEY}=([^&]*)/.exec(location.hash);if(m){a(JSON.parse(decodeURIComponent(m[1])));history.replaceState(history.state,"",location.pathname+location.search);}}catch(e){}window.addEventListener("message",function(e){var d=e.data,p=d&&d.params;if(d&&d.jsonrpc==="2.0"&&d.method===${JSON.stringify(HOST_CONTEXT_CHANGED_METHOD)}&&p&&p.styles)a({appearance:p.theme,variables:p.styles.variables});});document.addEventListener("click",function(e){var l=e.isTrusted?e.composedPath().find(function(t){return t&&t.matches&&t.matches("a[href]");}):null,u;if(!l)return;try{u=new URL(l.getAttribute("href"),document.baseURI);}catch(x){return;}if(!/^https?:$/.test(u.protocol)||u.href.split("#")[0]===location.href.split("#")[0])return;if(window.parent!==window){e.preventDefault();window.parent.postMessage({jsonrpc:"2.0",id:"t3-link-"+(++n),method:${JSON.stringify(OPEN_LINK_METHOD)},params:{url:u.href}},"*");}else{l.setAttribute("target","_blank");l.setAttribute("rel","noopener");}},true);})();`;
+// opens it as a new window, which the client sends to the browser. A framed
+// page also reports its content height, measured as the server measures it,
+// so its client can fit the frame to the page.
+const BOOTSTRAP_SCRIPT = `(function(){var s=document.getElementById("t3-theme"),n=0;if(!s)return;var b=${JSON.stringify(BASE_CSS)};function a(t){if(!t||typeof t!=="object"||!t.variables||typeof t.variables!=="object")return;var c=":root{color-scheme:"+(t.appearance==="light"?"light":"dark")+";";for(var k in t.variables){if(/^--[a-z0-9-]+$/.test(k))c+=k+":"+String(t.variables[k]).replace(/[;{}<>]/g,"")+";";}s.textContent=c+"}"+b;}try{var m=/[#&]${THEME_FRAGMENT_KEY}=([^&]*)/.exec(location.hash);if(m){a(JSON.parse(decodeURIComponent(m[1])));history.replaceState(history.state,"",location.pathname+location.search);}}catch(e){}window.addEventListener("message",function(e){var d=e.data,p=d&&d.params;if(d&&d.jsonrpc==="2.0"&&d.method===${JSON.stringify(HOST_CONTEXT_CHANGED_METHOD)}&&p&&p.styles)a({appearance:p.theme,variables:p.styles.variables});});document.addEventListener("click",function(e){var l=e.isTrusted?e.composedPath().find(function(t){return t&&t.matches&&t.matches("a[href]");}):null,u;if(!l)return;try{u=new URL(l.getAttribute("href"),document.baseURI);}catch(x){return;}if(!/^https?:$/.test(u.protocol)||u.href.split("#")[0]===location.href.split("#")[0])return;if(window.parent!==window){e.preventDefault();window.parent.postMessage({jsonrpc:"2.0",id:"t3-link-"+(++n),method:${JSON.stringify(OPEN_LINK_METHOD)},params:{url:u.href}},"*");}else{l.setAttribute("target","_blank");l.setAttribute("rel","noopener");}},true);if(window.parent!==window){var h,o,z=function(){var r=document.documentElement,v=Math.ceil(r.scrollHeight>r.clientHeight?r.scrollHeight:r.getBoundingClientRect().height);if(v===h)return;h=v;window.parent.postMessage({jsonrpc:"2.0",method:${JSON.stringify(SIZE_CHANGED_METHOD)},params:{height:v}},"*");};if(window.ResizeObserver){o=new ResizeObserver(z);o.observe(document.documentElement);}document.addEventListener("DOMContentLoaded",function(){if(o&&document.body)o.observe(document.body);z();});window.addEventListener("load",z);}})();`;
 
 function bootstrapMarkup(markup: string): string {
   const dark = htmlRenderTheme(T3_CODE_DARK_THEME_COLORS, "dark");