@devries-cameron20 / t3code-1 / commits / 500a52e839
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

fix(web): HTML visualizations show their full height instead of cropping and scrolling (#22131)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Theo Browne committed Oct 20, 2026 at 01:03 UTC 500a52e839b5ee16e0c697ac04694068a2e084eb
7 files changed +147 -14
apps/server/src/htmlRender/HtmlRender.test.ts
+22
@@ -123,6 +123,28 @@ describe("HtmlRender", () => {
123 }).pipe(Effect.provide(layerTest)),
124 );
125
126 + it.effect("rejects viewport height units, which make the fitted frame grow without end", () =>
127 + Effect.gen(function* () {
128 + const htmlRender = yield* HtmlRender.HtmlRender;
129 + for (const page of [
130 + "<style>main{min-height:100vh}</style>",
131 + "<style media=screen>main{height: calc(100dvh - 2rem)}",
132 + "<div style='top:.5svh'></div>",
133 + "<div style=height:100vh></div>",
134 + ]) {
135 + const error = yield* htmlRender.prepare(page).pipe(Effect.flip);
136 + expect(error).toBeInstanceOf(HtmlRender.HtmlRenderViewportHeightError);
137 + }
138 + yield* htmlRender.prepare(
139 + '<style>main{width:100vw;height:320px}</style><img src="data:image/png;base64,AB1vh+2vh/3vhC">',
140 + );
141 + yield* htmlRender.prepare(
142 + "<p>Avoid 100vh here.</p><!-- <div style=\"height:100vh\"></div> --><script>const unit = '100vh';</script>",
143 + );
144 + yield* htmlRender.prepare(`<style>${"1".repeat(200_000)}vx</style>`);
145 + }).pipe(Effect.provide(layerTest)),
146 + );
147 +
148 it.effect("inlines an SVG behind processing instructions and a doctype subset", () =>
149 Effect.gen(function* () {
150 const fileSystem = yield* FileSystem.FileSystem;
apps/server/src/htmlRender/HtmlRender.ts
+32 -1
@@ -68,6 +68,34 @@ export class HtmlRenderPageTooLargeError extends Schema.TaggedError<HtmlRenderPa
68 }
69 }
70
71 +export class HtmlRenderViewportHeightError extends Schema.TaggedError<HtmlRenderViewportHeightError>()(
72 + "HtmlRenderViewportHeightError",
73 + { found: Schema.String },
74 +) {
75 + override get message(): string {
76 + return `The page uses a viewport height unit (${this.found}). The frame grows to fit the page, so a size that follows the viewport makes it grow again and again. Let content set the height, or use fixed pixel heights.`;
77 + }
78 +}
79 +
80 +// Only stylesheets and style attributes are checked, so page text that mentions
81 +// a unit passes; comments match first so their contents are skipped. Scripts
82 +// are still checked, since markup they insert applies. An unclosed comment,
83 +// tag, or quote runs to the end of the page, which keeps both patterns linear
84 +// on hostile input.
85 +const CSS_SOURCE =
86 + /<!--[\s\S]*?(?:-->|$)|<style\b[^>]*(?:>|$)([\s\S]*?)(?:<\/style\s*>|$)|\sstyle\s*=\s*(?:"([^"]*)(?:"|$)|'([^']*)(?:'|$)|([^\s>]+))/gi;
87 +// The lookbehind skips base64 runs, such as an inlined image that happens to contain "1vh".
88 +const VIEWPORT_HEIGHT_UNIT = /(?<![\w.+/])(?:\d+(?:\.\d+)?|\.\d+)[sld]?vh(?![\w-])/i;
89 +
90 +const rejectViewportHeight = (html: string) => {
91 + for (const [, sheet, doubleQuoted, singleQuoted, unquoted] of html.matchAll(CSS_SOURCE)) {
92 + const css = sheet ?? doubleQuoted ?? singleQuoted ?? unquoted ?? "";
93 + const found = VIEWPORT_HEIGHT_UNIT.exec(css)?.[0];
94 + if (found !== undefined) return Effect.fail(new HtmlRenderViewportHeightError({ found }));
95 + }
96 + return Effect.void;
97 +};
98 +
99 export class HtmlRenderStoreError extends Schema.TaggedError<HtmlRenderStoreError>()(
100 "HtmlRenderStoreError",
101 { cause: Schema.Defect() },
@@ -80,7 +108,8 @@ export class HtmlRenderStoreError extends Schema.TaggedError<HtmlRenderStoreErro
108 export type HtmlRenderPrepareError =
109 | HtmlRenderImagesNotFoundError
110 | HtmlRenderImageTooLargeError
83 - | HtmlRenderPageTooLargeError;
111 + | HtmlRenderPageTooLargeError
112 + | HtmlRenderViewportHeightError;
113
114 export interface HtmlPreview {
115 readonly png: string;
@@ -380,6 +409,7 @@ const make = Effect.gen(function* () {
409 inlineLocalImages(injectHtmlRenderBootstrap(html)).pipe(Effect.provideContext(services));
410
411 const prepare = Effect.fn("HtmlRender.prepare")(function* (html: string) {
412 + yield* rejectViewportHeight(html);
413 const inlined = yield* inline(html);
414 if (inlined.missing.length > 0) {
415 return yield* new HtmlRenderImagesNotFoundError({ paths: inlined.missing });
@@ -447,6 +477,7 @@ const make = Effect.gen(function* () {
477 Math.max(MIN_PREVIEW_WIDTH, Math.round(input.width ?? HTML_RENDER_COLUMN_WIDTH)),
478 );
479 const appearance = input.appearance ?? "dark";
480 + yield* rejectViewportHeight(input.html);
481 const inlined = yield* inline(input.html);
482 const executable = yield* previewBrowser.executable;
483 const theme = htmlRenderTheme(
apps/server/src/mcp/toolkits/html/handlers.ts
+1
@@ -10,6 +10,7 @@ const INVALID_PAGE_ERRORS = new Set([
10 "HtmlRenderImagesNotFoundError",
11 "HtmlRenderImageTooLargeError",
12 "HtmlRenderPageTooLargeError",
13 + "HtmlRenderViewportHeightError",
14 ]);
15
16 const toFailure = (error: { readonly _tag: string; readonly message: string }) =>
apps/server/src/mcp/toolkits/html/tools.ts
+3 -2
@@ -2,6 +2,7 @@ import { OrchestratorMcpFailure } from "@t3tools/contracts";
2 import {
3 HTML_RENDER_COLUMN_WIDTH,
4 HTML_RENDER_LAYOUT_GUIDE,
5 + HTML_RENDER_MAX_FIT_HEIGHT,
6 HTML_RENDER_MAX_HEIGHT,
7 HTML_RENDER_MAX_TITLE_LENGTH,
8 HTML_RENDER_MIN_HEIGHT,
@@ -71,7 +72,7 @@ export const HtmlPreviewTool = Tool.make("html_preview", {
72 // Read-only in the MCP sense: it shows a page in the caller's own thread and
73 // touches no workspace, so plan mode and read-only sandboxes can use it.
74 const HtmlRenderTool = Tool.make(HTML_RENDER_TOOL_NAME, {
74 - 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}`,
75 + 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. On mobile, a height below the page's contentHeight caps the frame there, and the rest scrolls inside it; web and desktop fit the whole page, up to ${HTML_RENDER_MAX_FIT_HEIGHT}px. ${PAGE_RULES} ${HTML_RENDER_LAYOUT_GUIDE} ${HTML_RENDER_THEME_GUIDE}`,
76 parameters: Schema.Struct({
77 html: Html,
78 title: Schema.String.check(
@@ -79,7 +80,7 @@ const HtmlRenderTool = Tool.make(HTML_RENDER_TOOL_NAME, {
80 Schema.isMaxLength(HTML_RENDER_MAX_TITLE_LENGTH),
81 ).annotate({ description: "Short name for the page." }),
82 height: Schema.Int.annotate({
82 - 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.`,
83 + description: `The frame height in CSS pixels, ${HTML_RENDER_MIN_HEIGHT}-${HTML_RENDER_MAX_HEIGHT}. Use html_preview's contentHeight. A lower height makes long content scroll inside the frame on mobile only.`,
84 }),
85 }),
86 success: Schema.Struct({
apps/web/src/components/chat/HtmlRenderFrame.browser.test.tsx new
+63
@@ -0,0 +1,63 @@
1 +import { act } from "react";
2 +import { createRoot, type Root } from "react-dom/client";
3 +import { afterEach, expect, it, vi } from "vite-plus/test";
4 +import { EnvironmentId } from "@t3tools/contracts";
5 +import {
6 + htmlRenderTheme,
7 + HTML_RENDER_DEFAULT_FONTS,
8 + injectHtmlRenderBootstrap,
9 +} from "@t3tools/shared/htmlRender";
10 +import { T3_CODE_DARK_THEME_COLORS } from "@t3tools/shared/themePalettes";
11 +
12 +import "~/index.css";
13 +
14 +import { HtmlRenderFrame } from "./HtmlRenderFrame";
15 +
16 +const page = vi.hoisted(() => ({ url: "" }));
17 +vi.mock(import("~/assets/assetUrls"), async (original) => ({
18 + ...(await original()),
19 + useAssetUrlState: () => ({
20 + _tag: "Success",
21 + url: page.url,
22 + expiresAt: Date.now() + 60 * 60_000,
23 + }),
24 + useAssetUrlRefresh: () => vi.fn(),
25 +}));
26 +vi.mock(import("~/hooks/useHtmlRenderTheme"), async (original) => ({
27 + ...(await original()),
28 + useHtmlRenderTheme: () =>
29 + htmlRenderTheme(T3_CODE_DARK_THEME_COLORS, "dark", HTML_RENDER_DEFAULT_FONTS),
30 +}));
31 +
32 +let root: Root | undefined;
33 +let container: HTMLDivElement | undefined;
34 +
35 +afterEach(async () => {
36 + await act(() => root?.unmount());
37 + container?.remove();
38 + URL.revokeObjectURL(page.url);
39 +});
40 +
41 +it("grows past the agent's height to fit the page the client lays out", async () => {
42 + page.url = URL.createObjectURL(
43 + new Blob([injectHtmlRenderBootstrap('<div style="height:2345px"></div>')], {
44 + type: "text/html",
45 + }),
46 + );
47 + container = document.createElement("div");
48 + document.body.append(container);
49 + root = createRoot(container);
50 + await act(() =>
51 + root!.render(
52 + <HtmlRenderFrame
53 + environmentId={EnvironmentId.make("environment-1")}
54 + htmlRender={{ attachmentId: "html", title: "Tall page", height: 400 }}
55 + threadRef={undefined}
56 + />,
57 + ),
58 + );
59 +
60 + const box = container.firstElementChild as HTMLElement;
61 + await expect.poll(() => box.style.height).toBe("2345px");
62 + expect(box.querySelector("iframe")?.clientHeight).toBe(2345);
63 +});
packages/shared/src/htmlRender.test.ts
+11 -7
@@ -1,7 +1,7 @@
1 import { describe, expect, it } from "vite-plus/test";
2
3 import {
4 - HTML_RENDER_MAX_HEIGHT,
4 + HTML_RENDER_MAX_FIT_HEIGHT,
5 htmlRenderFrameHeight,
6 htmlRenderReferencesEqual,
7 htmlRenderTheme,
@@ -267,18 +267,22 @@ describe("htmlRenderFrameHeight", () => {
267 const fitted = { ...measured, height: 1403 };
268 expect(htmlRenderFrameHeight(fitted, 728, 1415)).toBe(1415);
269 expect(htmlRenderFrameHeight(fitted, 1400)).toBe(1660);
270 - expect(htmlRenderFrameHeight(fitted, 728, 5000)).toBe(HTML_RENDER_MAX_HEIGHT);
270 + expect(htmlRenderFrameHeight(fitted, 728, 5000)).toBe(5000);
271 + expect(htmlRenderFrameHeight(fitted, 728, 99_999)).toBe(HTML_RENDER_MAX_FIT_HEIGHT);
272 });
273
273 - it("keeps the agent's height when it asked for a scrolling frame or the page is unmeasured", () => {
274 + it("fits the client's measured content over a shorter agent height", () => {
275 const scrolling = { ...measured, height: 600 };
275 - expect(htmlRenderFrameHeight(scrolling, 728, 1415)).toBe(600);
276 - expect(htmlRenderFrameHeight(scrolling, 1400)).toBe(600);
277 - expect(htmlRenderFrameHeight(reference, 728)).toBe(reference.height);
278 - expect(htmlRenderFrameHeight(reference, 728, 900)).toBe(reference.height);
276 + expect(htmlRenderFrameHeight(scrolling, 728, 1415)).toBe(1415);
277 + expect(htmlRenderFrameHeight(reference, 728, 900)).toBe(900);
278 expect(htmlRenderFrameHeight(reference, 728, 300)).toBe(300);
279 });
280
281 + it("keeps the agent's height without a client measurement", () => {
282 + expect(htmlRenderFrameHeight({ ...measured, height: 600 }, 1400)).toBe(600);
283 + expect(htmlRenderFrameHeight(reference, 728)).toBe(reference.height);
284 + });
285 +
286 it("drops a malformed table and compares tables by value", () => {
287 expect(readHtmlRenderReference({ ...reference, heights: [[728, "x"]] })?.heights).toBe(
288 undefined,
packages/shared/src/htmlRender.ts
+15 -4
@@ -9,6 +9,9 @@ import { EVENT_CODE_SHORTCUT_KEYS } from "./keybindings.ts";
9 export const HTML_RENDER_TOOL_NAME = "html_render";
10 export const HTML_RENDER_MIN_HEIGHT = 80;
11 export const HTML_RENDER_MAX_HEIGHT = 2000;
12 +// A client fits the frame to the live page up to this height. It only stops a
13 +// page that grows with its frame, since vh units are rejected at publish.
14 +export const HTML_RENDER_MAX_FIT_HEIGHT = 20_000;
15 export const HTML_RENDER_MAX_TITLE_LENGTH = 200;
16
17 export interface HtmlRenderReference {
@@ -90,22 +93,30 @@ function measuredHeight(heights: NonNullable<HtmlRenderReference["heights"]>, wi
93
94 /**
95 * A page even a few pixels taller than its frame scrolls inside it and takes
93 - * the reader's scroll, so the frame fits the page.
96 + * the reader's scroll, so the frame fits the page. A client that measured the
97 + * live page passes `contentHeight`, which wins over the agent's height: client
98 + * fonts often wrap the page taller than the server or agent measured it.
99 */
100 export function htmlRenderFrameHeight(
101 reference: HtmlRenderReference,
102 width: number,
103 contentHeight?: number,
104 ) {
105 + if (contentHeight !== undefined) {
106 + return Math.min(
107 + HTML_RENDER_MAX_FIT_HEIGHT,
108 + Math.max(HTML_RENDER_MIN_HEIGHT, Math.ceil(contentHeight)),
109 + );
110 + }
111 const heights = reference.heights;
112 if (heights === undefined || heights.length === 0) {
102 - return clampHtmlRenderHeight(Math.min(reference.height, contentHeight ?? reference.height));
113 + return clampHtmlRenderHeight(reference.height);
114 }
115 const cap =
116 measuredHeight(heights, HTML_RENDER_COLUMN_WIDTH) > reference.height
117 ? reference.height
118 : HTML_RENDER_MAX_HEIGHT;
108 - return clampHtmlRenderHeight(Math.min(cap, contentHeight ?? measuredHeight(heights, width)));
119 + return clampHtmlRenderHeight(Math.min(cap, measuredHeight(heights, width)));
120 }
121
122 export function htmlRenderFileName(title: string) {
@@ -234,7 +245,7 @@ export const HTML_RENDER_LAYOUT_GUIDE = [
245 "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.",
246 "If a box needs its own background (a mock of a specific screen, a panel that must stand apart), give it at least 16px of padding on every side and var(--radius) corners, so content never touches its edge.",
247 "Give charts fixed pixel heights rather than heights that scale with width.",
237 - "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.",
248 + "Let content set the page's height. The frame grows to fit the page, so a height that follows the viewport makes it grow again and again: html_preview and html_render reject vh, svh, lvh, and dvh units, and height:100% on html or body has the same problem.",
249 ].join(" ");
250
251 const HOST_CONTEXT_CHANGED_METHOD = "ui/notifications/host-context-changed";