@underactive/pi-topping-web-tools 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.2.6] - 2026-10-02
+
+### Changed
+
+- Tested against pi 1.0.0. No break: the extension-facing declaration surface (`ToolDefinition`, `ExtensionAPI`, `ExtensionContext`, `ExtensionUIContext`, `defineTool`) is unchanged, `pi-ai`'s declaration surface is unchanged, and pi-tui's three changed declaration files are additive. The codemode tool description for each declared tool is now one line instead of a rendered TypeScript declaration, which shortens the prompt without changing what `promptGuidelines` contribute. `web_browser`'s `browser` status line is unaffected by the `tuiMode` default moving to `fullscreen`: the footer that renders it is mounted unconditionally and its renderer is unchanged.
+- Bumped the pinned `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` devDependencies from 0.99.2 to 1.0.0.
+- `web_browser`: added a prompt guideline that image content is not visible to a codemode script, so `screenshot` should be called directly, or with `toFile=true` to get a path the script can read.
+
+### Fixed
+
+- `fetch_markdown`, `pdf_extract`, `web_browser`: expanded result previews are bounded in wrapped rows at the render width instead of in characters. The 0.2.5 bound of 10 logical lines of 200 characters still rendered about 43 rows at 80 columns and 76 at 40; the body is now capped at 20 rows at any terminal width, using pi's `truncateToVisualLines`.
+
 ## [0.2.5] - 2026-09-30
 
 ### Changed

package/README.md

@@ -142,6 +142,8 @@ When `screenshot` returns an inline result (`toFile` omitted or `false`), `web_b
 
 `toFile=true` and `/browser-screenshot` save the original PNG to disk and put only the path and dimensions in the tool result. The file is resized only if a later `read` or `@file` attachment sends it to the model.
 
+In codemode, a tool result exposes only its text blocks, so an inline `screenshot` reaches the script as its caption with no image bytes. Call `screenshot` directly from the session, or pass `toFile=true` and read the saved path from the script.
+
 The resize fields are:
 
 - `maxWidth` / `maxHeight`: pixel bounds (pi defaults to 2000×2000)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@underactive/pi-topping-web-tools",
-	"version": "0.2.5",
+	"version": "0.2.6",
 	"description": "Pi extensions for the web: fetch_markdown (URL to markdown, cached, keyless), pdf_extract (PDF text extraction) and web_browser (headless Playwright automation), sharing a preapproved-host allowlist.",
 	"keywords": ["pi-package", "pi-extension"],
 	"license": "MIT",
@@ -53,9 +53,9 @@
 		"typebox": "*"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "0.99.2",
-		"@earendil-works/pi-coding-agent": "0.99.2",
-		"@earendil-works/pi-tui": "0.99.2",
+		"@earendil-works/pi-ai": "1.0.0",
+		"@earendil-works/pi-coding-agent": "1.0.0",
+		"@earendil-works/pi-tui": "1.0.0",
 		"@types/node": "^24.0.0",
 		"@types/turndown": "^5.0.5",
 		"typebox": "^1.3.3",

package/src/fetch-markdown.ts

@@ -12,7 +12,7 @@ import { combineSignals } from "./abort-utils.ts";
 import { getBrowserHeaders } from "./browser-headers.ts";
 import { isPreapprovedHost, permissionKey } from "./permissions.ts";
 import { requestHostPermission } from "./permission-prompt.ts";
-import { clipField, resultPreview, resultText } from "./render-preview.ts";
+import { BoundedPreview, clipField, resultText } from "./render-preview.ts";
 import { MAX_URL_LENGTH, isLocalOrPrivateHost, upgradeHttpToHttps } from "./web-browser/permissions.ts";
 
 const MAX_HTTP_CONTENT_LENGTH = 25 * 1024 * 1024;
@@ -572,13 +572,7 @@ To complete your request, I need to fetch content from the redirected URL. Pleas
 		}
 
 		if (expanded) {
-			const preview = resultPreview(resultText(result.content));
-			for (const line of preview.lines) {
-				text += `\n${theme.fg("dim", line)}`;
-			}
-			if (preview.truncated) {
-				text += `\n${theme.fg("muted", "… (truncated)")}`;
-			}
+			return new BoundedPreview({ header: text, body: resultText(result.content), marker: "… (truncated)", theme });
 		}
 
 		return new Text(text, 0, 0);

package/src/pdf-extract.ts

@@ -11,7 +11,7 @@ import { extractText, getDocumentProxy } from "unpdf";
 import { combineSignals } from "./abort-utils.ts";
 import { isPreapprovedHost, permissionKey } from "./permissions.ts";
 import { requestHostPermission } from "./permission-prompt.ts";
-import { clipField, resultPreview, resultText } from "./render-preview.ts";
+import { BoundedPreview, clipField, resultText } from "./render-preview.ts";
 import { getWithPermittedRedirects, isPermittedRedirect, sliceContent, validateURL } from "./fetch-markdown.ts";
 import { upgradeHttpToHttps } from "./web-browser/permissions.ts";
 
@@ -423,13 +423,7 @@ Usage notes:
 		}
 
 		if (expanded) {
-			const preview = resultPreview(resultText(result.content));
-			for (const line of preview.lines) {
-				text += `\n${theme.fg("dim", line)}`;
-			}
-			if (preview.truncated) {
-				text += `\n${theme.fg("muted", "… (truncated)")}`;
-			}
+			return new BoundedPreview({ header: text, body: resultText(result.content), marker: "… (truncated)", theme });
 		}
 
 		return new Text(text, 0, 0);

package/src/render-preview.ts

@@ -7,31 +7,26 @@
  * same bound has to be applied here. Header fields need the same bound: an HTTP
  * reason phrase and a page `<title>` are attacker-controlled and can be megabytes.
  *
- * Bounds are expressed in characters rather than visual lines because pi's `Text`
- * word-wraps (and hard-breaks unspaced tokens) on render. That keeps the work
- * independent of the terminal, but rendered height still scales as
- * `characters / width`; the worst case here is about 43 lines at 80 columns and 76
- * at 40, versus the ~1250 lines a 100K-character result produced before.
+ * `renderResult` is not handed a width, so header fields and collapsed bodies are
+ * bounded in characters. The width does reach the component it returns, through
+ * `render(width)`, so an expanded body is bounded in rows there: `BoundedPreview`
+ * wraps it with the host's `truncateToVisualLines`, which keeps its height the same
+ * at every terminal width.
  */
 
+import { truncateToVisualLines, type Theme } from "@earendil-works/pi-coding-agent";
 import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import { Text, type Component } from "@earendil-works/pi-tui";
 
-/** Logical lines shown in an expanded preview. */
-export const MAX_PREVIEW_LINES = 10;
+/** Body rows in an expanded preview, counted after wrapping at the render width. */
+export const MAX_VISUAL_PREVIEW_LINES = 20;
 
-/** Characters kept per logical line in an expanded preview. */
-export const MAX_PREVIEW_LINE_CHARS = 200;
+/** Body characters handed to the wrapper: fills the row cap up to 400 columns without wrapping a 100K result on every redraw. */
+export const MAX_PREVIEW_CHARS = 8_000;
 
 /** Characters kept from a single unbounded field: a header value, status field, or collapsed body. */
 export const MAX_FIELD_CHARS = 200;
 
-export interface ResultPreview {
-	/** Logical lines to display, each already clipped to {@link MAX_PREVIEW_LINE_CHARS}. */
-	lines: string[];
-	/** Whether logical lines were dropped by the {@link MAX_PREVIEW_LINES} cap. */
-	truncated: boolean;
-}
-
 /** Concatenate a tool result's text blocks; empty when the result carries only images. */
 export function resultText(content: readonly (TextContent | ImageContent)[]): string {
 	return content
@@ -45,17 +40,68 @@ export function clipField(text: string): string {
 	return text.length > MAX_FIELD_CHARS ? `${text.slice(0, MAX_FIELD_CHARS)}…` : text;
 }
 
+export interface BoundedPreviewOptions {
+	/** Styled summary; its attacker-controlled fields are already clipped. */
+	header: string;
+	/** Raw result text, styled dim per logical line. */
+	body: string;
+	/** Raw marker shown muted when the body was cut. */
+	marker: string;
+	/** Raw line shown dim after the body whether or not it was cut. */
+	trailer?: string;
+	theme: Theme;
+}
+
 /**
- * Preview for an expanded tool result: at most {@link MAX_PREVIEW_LINES} logical lines,
- * each clipped so one long line cannot fill the screen. A line long enough to hit the
- * character cap loses its tail in the preview; the full text stays in the transcript.
+ * Expanded tool result: header, at most {@link MAX_VISUAL_PREVIEW_LINES} body rows, then the
+ * marker and trailer. Rows depend on the width, which only `render` sees; lines are cached per
+ * width because the transcript renders every result on every frame.
  */
-export function resultPreview(text: string): ResultPreview {
-	// The limit argument keeps the split bounded on a large body: one extra element is
-	// enough to detect that more lines existed.
-	const all = text.split("\n", MAX_PREVIEW_LINES + 1);
-	return {
-		lines: all.slice(0, MAX_PREVIEW_LINES).map((line) => clipField(line)),
-		truncated: all.length > MAX_PREVIEW_LINES,
-	};
-}
+export class BoundedPreview implements Component {
+	private readonly header: string;
+	private readonly body: string;
+	private readonly marker: string;
+	private readonly trailer: string | undefined;
+	private readonly cut: boolean;
+	private cachedWidth: number | undefined;
+	private cachedLines: string[] | undefined;
+
+	constructor(options: BoundedPreviewOptions) {
+		const { theme } = options;
+		this.header = options.header;
+		this.cut = options.body.length > MAX_PREVIEW_CHARS;
+		// Slice the raw text before styling so the cap never cuts an escape sequence. Every logical
+		// line takes at least one row, so one line past the cap is enough for the skip to register.
+		this.body = options.body
+			.slice(0, MAX_PREVIEW_CHARS)
+			.split("\n", MAX_VISUAL_PREVIEW_LINES + 1)
+			.map((line) => theme.fg("dim", line))
+			.join("\n");
+		this.marker = theme.fg("muted", options.marker);
+		this.trailer = options.trailer === undefined ? undefined : theme.fg("dim", options.trailer);
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines === undefined || this.cachedWidth !== width) {
+			// paddingX 0 keeps the geometry of the `new Text(text, 0, 0)` this replaces.
+			const { visualLines, skippedCount } = truncateToVisualLines(
+				this.body,
+				MAX_VISUAL_PREVIEW_LINES,
+				width,
+				0,
+				"start",
+			);
+			const lines = [...new Text(this.header, 0, 0).render(width), ...visualLines];
+			if (this.cut || skippedCount > 0) lines.push(...new Text(this.marker, 0, 0).render(width));
+			if (this.trailer !== undefined) lines.push(...new Text(this.trailer, 0, 0).render(width));
+			this.cachedLines = lines;
+			this.cachedWidth = width;
+		}
+		return this.cachedLines;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}

package/src/web-browser/index.ts

@@ -31,7 +31,7 @@ import {
 import { buildOriginChecker } from "./egress-policy.ts";
 import { checkUrlPermission, upgradeHttpToHttps, validateURL } from "./permissions.ts";
 import { requestHostPermission } from "../permission-prompt.ts";
-import { clipField, resultPreview, resultText } from "../render-preview.ts";
+import { BoundedPreview, clipField, resultText } from "../render-preview.ts";
 import { listGrants } from "../permission-store.ts";
 import { permissionKey } from "../permissions.ts";
 import { isInsideCwd } from "../pdf-extract.ts";
@@ -343,6 +343,7 @@ export default function (pi: ExtensionAPI) {
 			"Use get_content only when DOM structure or attributes are needed; it returns raw HTML.",
 			"On SPA sites, use wait_for after navigate (selector/state or networkidle) before click/type.",
 			"Use screenshot for visual verification (requires a vision-capable model); use toFile=true to save PNG to disk instead of base64.",
+			"Image content is not visible to a codemode script: a script receives only a tool result's text blocks, so a screenshot taken from one returns its caption without the pixels. Call screenshot directly, or with toFile=true to get a file path the script can read.",
 			"Use get_console_logs when JavaScript errors or console output may explain page behavior.",
 			"Use get_network_logs when failed, egress-blocked, or 4xx/5xx requests may explain page behavior. Navigate directly to a blocked origin to request approval.",
 			"Use set_cookies to inject cookies for authenticated flows after manual login.",
@@ -1101,16 +1102,13 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (expanded) {
-				const preview = resultPreview(resultText(result.content));
-				for (const line of preview.lines) {
-					text += `\n${theme.fg("dim", line)}`;
-				}
-				if (preview.truncated) {
-					text += `\n${theme.fg("muted", "…")}`;
-				}
-				if (details.fullOutputPath) {
-					text += `\n${theme.fg("dim", `Full: ${details.fullOutputPath}`)}`;
-				}
+				return new BoundedPreview({
+					header: text,
+					body: resultText(result.content),
+					marker: "…",
+					trailer: details.fullOutputPath ? `Full: ${details.fullOutputPath}` : undefined,
+					theme,
+				});
 			}
 
 			return new Text(text, 0, 0);