@oh-my-pi/pi-coding-agent 14.0.3 → 14.0.5

package/src/tools/browser.ts

@@ -501,6 +501,83 @@ export interface ReadableResult {
 	markdown?: string;
 }
 
+type ReadableFormat = "text" | "markdown";
+
+/** Trim to non-empty string or undefined. */
+function normalize(text: string | null | undefined): string | undefined {
+	const trimmed = text?.trim();
+	return trimmed || undefined;
+}
+
+/**
+ * Extract readable content from raw HTML.
+ * Tries Readability (article-isolation scoring) first, then falls back to a
+ * CSS selector chain over the same pre-parsed DOM. Returns null if neither
+ * path yields usable content.
+ */
+export function extractReadableFromHtml(html: string, url: string, format: ReadableFormat): ReadableResult | null {
+	const { document } = parseHTML(html);
+
+	// --- Primary: Readability article extraction ---
+	const article = new Readability(document).parse();
+	if (article) {
+		const result = toReadableResult(url, format, article.textContent, article.content, {
+			title: article.title,
+			byline: article.byline,
+			excerpt: article.excerpt,
+			length: article.length,
+		});
+		if (result) return result;
+	}
+
+	// --- Fallback: CSS selector chain ---
+	const candidates = [
+		document.querySelector("[data-pagefind-body]"),
+		document.querySelector("main article"),
+		document.querySelector("article"),
+		document.querySelector("main"),
+		document.querySelector("[role='main']"),
+		document.body,
+	];
+	for (const el of candidates) {
+		if (!el) continue;
+		const innerHTML = el.innerHTML?.trim();
+		const textContent = el.textContent?.trim();
+		if (!innerHTML || !textContent) continue;
+		const result = toReadableResult(url, format, textContent, innerHTML, {
+			title: document.title,
+			excerpt: textContent.slice(0, 240),
+			length: textContent.length,
+		});
+		if (result) return result;
+	}
+
+	return null;
+}
+
+/** Shared builder for both extraction paths. */
+function toReadableResult(
+	url: string,
+	format: ReadableFormat,
+	textContent: string | null | undefined,
+	htmlContent: string | null | undefined,
+	meta: { title?: string | null; byline?: string | null; excerpt?: string | null; length?: number | null },
+): ReadableResult | null {
+	const text = normalize(textContent);
+	const markdown = format === "markdown" ? (normalize(htmlToBasicMarkdown(htmlContent ?? "")) ?? text) : undefined;
+	const normalizedText = format === "text" ? text : undefined;
+	if (!normalizedText && !markdown) return null;
+	return {
+		url,
+		title: normalize(meta.title),
+		byline: normalize(meta.byline),
+		excerpt: normalize(meta.excerpt),
+		contentLength: meta.length ?? text?.length ?? markdown?.length ?? 0,
+		text: normalizedText,
+		markdown,
+	};
+}
+
 function ensureParam<T>(value: T | undefined, name: string, action: string): T {
 	if (value === undefined || value === null || value === "") {
 		throw new ToolError(`Missing required parameter '${name}' for action '${action}'.`);
@@ -1365,26 +1442,13 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 					const format = params.format ?? "markdown";
 					const html = (await untilAborted(signal, () => page.content())) as string;
 					const url = page.url();
-					const { document } = parseHTML(html);
-					const reader = new Readability(document);
-					const article = reader.parse();
-					if (!article) {
+					const readable = extractReadableFromHtml(html, url, format);
+					if (!readable) {
 						throw new ToolError("Readable content not found");
 					}
-					const markdown = format === "markdown" ? htmlToBasicMarkdown(article.content ?? "") : undefined;
-					const text = format === "text" ? (article.textContent ?? "") : undefined;
-					const readable: ReadableResult = {
-						url,
-						title: article.title ?? undefined,
-						byline: article.byline ?? undefined,
-						excerpt: article.excerpt ?? undefined,
-						contentLength: article.length ?? article.textContent?.length ?? 0,
-						text,
-						markdown,
-					};
 					details.url = url;
 					details.readable = readable;
-					details.result = format === "markdown" ? (markdown ?? "") : (text ?? "");
+					details.result = format === "markdown" ? (readable.markdown ?? "") : (readable.text ?? "");
 					return toolResult(details)
 						.text(JSON.stringify(readable, null, 2))
 						.done();
@@ -1407,13 +1471,12 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 						buffer = (await untilAborted(signal, () => page.screenshot({ type: "png", fullPage }))) as Buffer;
 					}
 
-					// Compress for API content (same as pasted images)
-					// NOTE: screenshots can be deceptively large (especially PNG) even at modest resolutions,
-					// and tool results are immediately embedded in the next LLM request.
-					// Use a tighter budget than the global per-image limit to avoid 413 request_too_large.
+					// Compress aggressively for API content — screenshots are the most
+					// frequent image source and land directly in the next LLM request.
+					// 1024px is plenty for OCR/UI inspection; 150KB keeps payloads lean.
 					const resized = await resizeImage(
 						{ type: "image", data: buffer.toBase64(), mimeType: "image/png" },
-						{ maxBytes: 0.75 * 1024 * 1024 },
+						{ maxWidth: 1024, maxHeight: 1024, maxBytes: 150 * 1024, jpegQuality: 70 },
 					);
 					// Resolve destination: user-defined path > screenshotDir (auto-named) > temp file.
 					const screenshotDir = (() => {

package/src/tools/fetch.ts

@@ -84,7 +84,7 @@ const IMAGE_MIME_BY_EXTENSION = new Map<string, string>([
 ]);
 const SUPPORTED_INLINE_IMAGE_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
 const MAX_INLINE_IMAGE_SOURCE_BYTES = 20 * 1024 * 1024;
-const MAX_INLINE_IMAGE_OUTPUT_BYTES = 0.75 * 1024 * 1024;
+const MAX_INLINE_IMAGE_OUTPUT_BYTES = 300 * 1024;
 
 // =============================================================================
 // Utilities

package/src/tools/find.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
-import { FileType, type GlobMatch, glob } from "@oh-my-pi/pi-natives";
+import * as natives from "@oh-my-pi/pi-natives";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { isEnoent, prompt, untilAborted } from "@oh-my-pi/pi-utils";
@@ -124,46 +124,15 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 				throw new ToolError("Limit must be a positive number");
 			}
 			const includeHidden = hidden ?? true;
-
-			// If custom operations provided with glob, use that instead of fd
-			if (this.#customOps?.glob) {
-				if (!(await this.#customOps.exists(searchPath))) {
-					throw new ToolError(`Path not found: ${scopePath}`);
-				}
-
-				if (!hasGlob && this.#customOps.stat) {
-					const stat = await this.#customOps.stat(searchPath);
-					if (stat.isFile()) {
-						const files = [scopePath];
-						const details: FindToolDetails = {
-							scopePath,
-							fileCount: 1,
-							files,
-							truncated: false,
-						};
-						return toolResult(details).text(files.join("\n")).done();
-					}
-				}
-
-				const results = await this.#customOps.glob(globPattern, searchPath, {
-					ignore: ["**/node_modules/**", "**/.git/**"],
-					limit: effectiveLimit,
-				});
-
-				if (results.length === 0) {
+			const timeoutSignal = AbortSignal.timeout(GLOB_TIMEOUT_MS);
+			const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+			const buildResult = (files: string[]): AgentToolResult<FindToolDetails> => {
+				if (files.length === 0) {
 					const details: FindToolDetails = { scopePath, fileCount: 0, files: [], truncated: false };
 					return toolResult(details).text("No files found matching pattern").done();
 				}
 
-				// Relativize paths
-				const relativized = results.map(p => {
-					if (p.startsWith(searchPath)) {
-						return p.slice(searchPath.length + 1);
-					}
-					return path.relative(searchPath, p);
-				});
-
-				const listLimit = applyListLimit(relativized, { limit: effectiveLimit });
+				const listLimit = applyListLimit(files, { limit: effectiveLimit });
 				const limited = listLimit.items;
 				const limitMeta = listLimit.meta;
 				const rawOutput = limited.join("\n");
@@ -186,6 +155,32 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 				}
 
 				return resultBuilder.done();
+			};
+
+			if (this.#customOps?.glob) {
+				if (!(await this.#customOps.exists(searchPath))) {
+					throw new ToolError(`Path not found: ${scopePath}`);
+				}
+
+				if (!hasGlob && this.#customOps.stat) {
+					const stat = await this.#customOps.stat(searchPath);
+					if (stat.isFile()) {
+						return buildResult([scopePath]);
+					}
+				}
+
+				const results = await this.#customOps.glob(globPattern, searchPath, {
+					ignore: ["**/node_modules/**", "**/.git/**"],
+					limit: effectiveLimit,
+				});
+				const relativized = results.map(p => {
+					if (p.startsWith(searchPath)) {
+						return p.slice(searchPath.length + 1);
+					}
+					return path.relative(searchPath, p);
+				});
+
+				return buildResult(relativized);
 			}
 
 			let searchStat: fs.Stats;
@@ -199,20 +194,13 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 			}
 
 			if (!hasGlob && searchStat.isFile()) {
-				const files = [scopePath];
-				const details: FindToolDetails = {
-					scopePath,
-					fileCount: 1,
-					files,
-					truncated: false,
-				};
-				return toolResult(details).text(files.join("\n")).done();
+				return buildResult([scopePath]);
 			}
 			if (!searchStat.isDirectory()) {
 				throw new ToolError(`Path is not a directory: ${searchPath}`);
 			}
 
-			let matches: GlobMatch[];
+			let matches: natives.GlobMatch[];
 			const onUpdateMatches: string[] = [];
 			const updateIntervalMs = 200;
 			let lastUpdate = 0;
@@ -233,27 +221,25 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 				});
 			};
 			const onMatch = onUpdate
-				? (err: Error | null, match: GlobMatch | null) => {
+				? (err: Error | null, match: natives.GlobMatch | null) => {
 						if (err || signal?.aborted || !match) return;
 						let relativePath = match.path;
 						if (!relativePath) return;
-						if (match.fileType === FileType.Dir && !relativePath.endsWith("/")) {
+						if (match.fileType === natives.FileType.Dir && !relativePath.endsWith("/")) {
 							relativePath += "/";
 						}
 						onUpdateMatches.push(relativePath);
 						emitUpdate();
 					}
 				: undefined;
-			const timeoutSignal = AbortSignal.timeout(GLOB_TIMEOUT_MS);
-			const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
 
 			const doGlob = async (useGitignore: boolean) =>
 				untilAborted(combinedSignal, () =>
-					glob(
+					natives.glob(
 						{
 							pattern: globPattern,
 							path: searchPath,
-							fileType: FileType.File,
+							fileType: natives.FileType.File,
 							hidden: includeHidden,
 							maxResults: effectiveLimit,
 							sortByMtime: true,
@@ -266,7 +252,6 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 
 			try {
 				let result = await doGlob(true);
-				// If gitignore filtering yielded nothing, retry without it
 				if (result.matches.length === 0) {
 					result = await doGlob(false);
 				}
@@ -282,12 +267,7 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 				throw error;
 			}
 
-			if (matches.length === 0) {
-				const details: FindToolDetails = { scopePath, fileCount: 0, files: [], truncated: false };
-				return toolResult(details).text("No files found matching pattern").done();
-			}
 			const relativized: string[] = [];
-
 			for (const match of matches) {
 				throwIfAborted(signal);
 				const line = match.path;
@@ -297,9 +277,7 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 
 				const hadTrailingSlash = line.endsWith("/") || line.endsWith("\\");
 				let relativePath = line;
-
-				const isDirectory = match.fileType === FileType.Dir;
-
+				const isDirectory = match.fileType === natives.FileType.Dir;
 				if ((isDirectory || hadTrailingSlash) && !relativePath.endsWith("/")) {
 					relativePath += "/";
 				}
@@ -307,39 +285,7 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 				relativized.push(relativePath);
 			}
 
-			if (relativized.length === 0) {
-				const details: FindToolDetails = { scopePath, fileCount: 0, files: [], truncated: false };
-				return toolResult(details).text("No files found matching pattern").done();
-			}
-
-			// Results are already sorted by mtime from native (sortByMtime: true)
-
-			const listLimit = applyListLimit(relativized, { limit: effectiveLimit });
-			const limited = listLimit.items;
-			const limitMeta = listLimit.meta;
-
-			// Apply byte truncation (no line limit since we already have result limit)
-			const rawOutput = limited.join("\n");
-			const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
-
-			const resultOutput = truncation.content;
-			const details: FindToolDetails = {
-				scopePath,
-				fileCount: limited.length,
-				files: limited,
-				truncated: Boolean(limitMeta.resultLimit || truncation.truncated),
-				resultLimitReached: limitMeta.resultLimit?.reached,
-				truncation: truncation.truncated ? truncation : undefined,
-			};
-
-			const resultBuilder = toolResult(details)
-				.text(resultOutput)
-				.limits({ resultLimit: limitMeta.resultLimit?.reached });
-			if (truncation.truncated) {
-				resultBuilder.truncation(truncation, { direction: "head" });
-			}
-
-			return resultBuilder.done();
+			return buildResult(relativized);
 		});
 	}
 }

package/src/tools/gemini-image.ts

@@ -728,6 +728,7 @@ export const geminiImageTool: CustomTool<typeof geminiImageSchema, GeminiImageTo
 					headers: {
 						"Content-Type": "application/json",
 						Authorization: `Bearer ${apiKey.apiKey}`,
+						"X-Title": "Oh-My-Pi",
 					},
 					body: JSON.stringify(requestBody),
 					signal: requestSignal,

package/src/tools/index.ts

@@ -1,7 +1,7 @@
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import type { ToolChoice } from "@oh-my-pi/pi-ai";
 import type { SearchDb } from "@oh-my-pi/pi-natives";
-import { $env, logger } from "@oh-my-pi/pi-utils";
+import { $env, $flag, isBunTestRuntime, logger } from "@oh-my-pi/pi-utils";
 import type { AsyncJobManager } from "../async";
 import type { PromptTemplate } from "../config/prompt-templates";
 import type { Settings } from "../config/settings";
@@ -297,8 +297,7 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		!skipPythonPreflight &&
 		pythonMode !== "bash-only" &&
 		(requestedTools === undefined || requestedTools.includes("python"));
-	const isTestEnv = Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
-	const skipPythonWarm = isTestEnv || $env.PI_PYTHON_SKIP_CHECK === "1";
+	const skipPythonWarm = isBunTestRuntime() || $flag("PI_PYTHON_SKIP_CHECK");
 	if (shouldCheckPython) {
 		const availability = await logger.time("createTools:pythonCheck", checkPythonKernelAvailability, session.cwd);
 		pythonAvailable = availability.ok;

package/src/tools/read.ts

@@ -14,6 +14,7 @@ import {
 	parseChunkReadPath,
 	parseChunkSelector,
 	resolveAnchorStyle,
+	resolveChunkAutoIndent,
 } from "../edit/modes/chunk";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { parseInternalUrl } from "../internal-urls/parse";
@@ -449,6 +450,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			resolveEditMode(session) === "chunk"
 				? prompt.render(readChunkDescription, {
 						anchorStyle: resolveAnchorStyle(session.settings),
+						chunkAutoIndent: resolveChunkAutoIndent(),
 					})
 				: prompt.render(readDescription, {
 						DEFAULT_LIMIT: String(this.#defaultLimit),

package/src/tools/render-utils.ts

@@ -14,7 +14,7 @@ import type { Theme } from "../modes/theme/theme";
 import { formatDimensionNote, type ResizedImage } from "../utils/image-resize";
 
 export { Ellipsis } from "@oh-my-pi/pi-natives";
-export { replaceTabs, truncateToWidth } from "@oh-my-pi/pi-tui";
+export { replaceTabs, truncateToWidth, wrapTextWithAnsi } from "@oh-my-pi/pi-tui";
 
 // =============================================================================
 // Standardized Display Constants

package/src/tools/report-tool-issue.ts

@@ -8,7 +8,7 @@
 import { Database } from "bun:sqlite";
 import path from "node:path";
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
-import { $env, getAgentDir, logger, VERSION } from "@oh-my-pi/pi-utils";
+import { $flag, getAgentDir, logger, VERSION } from "@oh-my-pi/pi-utils";
 import { Type } from "@sinclair/typebox";
 import type { Settings } from "..";
 import type { ToolSession } from "./index";
@@ -19,7 +19,7 @@ const ReportToolIssueParams = Type.Object({
 });
 
 export function isAutoQaEnabled(settings?: Settings): boolean {
-	return $env.PI_AUTO_QA === "1" || !!settings?.get("dev.autoqa");
+	return $flag("PI_AUTO_QA") || !!settings?.get("dev.autoqa");
 }
 
 export function getAutoQaDbPath(): string {

package/src/utils/edit-mode.ts

@@ -1,4 +1,4 @@
-import { $env } from "@oh-my-pi/pi-utils";
+import { $env, $flag } from "@oh-my-pi/pi-utils";
 
 export type EditMode = "replace" | "patch" | "hashline" | "chunk";
 
@@ -36,7 +36,7 @@ export function resolveEditMode(session: EditModeSessionLike): EditMode {
 	const envMode = normalizeEditMode($env.PI_EDIT_VARIANT);
 	if (envMode) return envMode;
 
-	if ($env.PI_STRICT_EDIT_MODE === "1") {
+	if (!$flag("PI_STRICT_EDIT_MODE")) {
 		if (activeModel?.includes("spark")) return "replace";
 		if (activeModel?.includes("nano")) return "replace";
 		if (activeModel?.includes("mini")) return "replace";

package/src/utils/image-resize.ts

@@ -2,10 +2,10 @@ import type { ImageContent } from "@oh-my-pi/pi-ai";
 import { ImageFormat, PhotonImage, SamplingFilter } from "@oh-my-pi/pi-natives";
 
 export interface ImageResizeOptions {
-	maxWidth?: number; // Default: 2000
-	maxHeight?: number; // Default: 2000
-	maxBytes?: number; // Default: 4.5MB (below Anthropic's 5MB limit)
-	jpegQuality?: number; // Default: 80
+	maxWidth?: number; // Default: 1568
+	maxHeight?: number; // Default: 1568
+	maxBytes?: number; // Default: 500KB
+	jpegQuality?: number; // Default: 75
 }
 
 export interface ResizedImage {
@@ -19,22 +19,25 @@ export interface ResizedImage {
 	get data(): string;
 }
 
-// 4.5MB - provides headroom below Anthropic's 5MB limit
-const DEFAULT_MAX_BYTES = 4.5 * 1024 * 1024;
+// 500KB target — aggressive compression; Anthropic's 5MB per-image cap is rarely the
+// binding constraint once images are downsized to 1568px (Anthropic's internal threshold).
+const DEFAULT_MAX_BYTES = 500 * 1024;
 
 const DEFAULT_OPTIONS: Required<ImageResizeOptions> = {
-	maxWidth: 2000,
-	maxHeight: 2000,
+	// 1568px — Anthropic downscales anything larger; OpenAI tiles at 768px;
+	// sending bigger pixels wastes bandwidth the model never sees.
+	maxWidth: 1568,
+	maxHeight: 1568,
 	maxBytes: DEFAULT_MAX_BYTES,
-	jpegQuality: 80,
+	jpegQuality: 75,
 };
 
-/** Helper to pick the smaller of two buffers */
-function pickSmaller(
-	a: { buffer: Uint8Array; mimeType: string },
-	b: { buffer: Uint8Array; mimeType: string },
-): { buffer: Uint8Array; mimeType: string } {
-	return a.buffer.length <= b.buffer.length ? a : b;
+/** Pick the smallest of N encoded buffers. */
+function pickSmallest(...candidates: Array<{ buffer: Uint8Array; mimeType: string }>): {
+	buffer: Uint8Array;
+	mimeType: string;
+} {
+	return candidates.reduce((best, c) => (c.buffer.length < best.buffer.length ? c : best));
 }
 
 /** Polyfill for Buffer.toBase64, technically since it derives from Uint8Array it should exist but Bun reasons... */
@@ -43,17 +46,22 @@ Buffer.prototype.toBase64 = function (this: Buffer) {
 };
 
 /**
- * Resize an image to fit within the specified max dimensions and file size.
- * Returns the original image if it already fits within the limits.
+ * Resize and recompress an image to fit within the specified max dimensions and file size.
  *
- * Uses Photon for image processing. If Photon is not available,
- * returns the original image unchanged.
+ * Defaults target Anthropic's internal 1568px downscale threshold and produce small
+ * lossy JPEG output suitable for tool-call payloads (~100–500KB typical).
  *
- * Strategy for staying under maxBytes:
- * 1. First resize to maxWidth/maxHeight
- * 2. Try both PNG and JPEG formats, pick the smaller one
- * 3. If still too large, try JPEG with decreasing quality
- * 4. If still too large, progressively reduce dimensions
+ * Strategy:
+ * 1. Fast path — if input already fits dimensions AND is at <=25% of byte budget,
+ *    return as-is. Avoids re-encoding tiny icons/diagrams.
+ * 2. Resize to maxWidth/maxHeight, encode both PNG and JPEG at default quality,
+ *    pick whichever is smaller. PNG wins for line art / few-color UI; JPEG wins
+ *    for photographic content.
+ * 3. If still too large, JPEG-only quality ladder (PNG quality is a no-op).
+ * 4. If still too large, progressively reduce dimensions and retry the JPEG ladder.
+ * 5. Last resort: ship the smallest variant produced.
+ *
+ * On any decode failure, returns the original bytes unchanged with wasResized=false.
  */
 export async function resizeImage(img: ImageContent, options?: ImageResizeOptions): Promise<ResizedImage> {
 	const opts = { ...DEFAULT_OPTIONS, ...options };
@@ -68,7 +76,12 @@ export async function resizeImage(img: ImageContent, options?: ImageResizeOption
 
 		// Check if already within all limits (dimensions AND size)
 		const originalSize = inputBuffer.length;
-		if (originalWidth <= opts.maxWidth && originalHeight <= opts.maxHeight && originalSize <= opts.maxBytes) {
+		// Fast path: skip if already within dimensions AND well under budget.
+		// Threshold is 1/4 of budget — if already that compact, don't re-encode.
+		// Avoids wasted work on tiny icons/diagrams while ensuring larger PNGs
+		// still get JPEG-compressed.
+		const comfortableSize = opts.maxBytes / 4;
+		if (originalWidth <= opts.maxWidth && originalHeight <= opts.maxHeight && originalSize <= comfortableSize) {
 			return {
 				buffer: inputBuffer,
 				mimeType: img.mimeType ?? `image/${format}`,
@@ -96,35 +109,58 @@ export async function resizeImage(img: ImageContent, options?: ImageResizeOption
 			targetHeight = opts.maxHeight;
 		}
 
-		// Helper to resize and encode in both formats, returning the smaller one
-		async function tryBothFormats(
+		// First-attempt encoder: try PNG, JPEG, and lossy WebP — return whichever is smallest.
+		// PNG wins for line art / few-color UI; JPEG and WebP win for photographic content;
+		// WebP usually beats JPEG by 25–35% at the same perceptual quality.
+		async function encodeSmallest(
 			width: number,
 			height: number,
 			quality: number,
 		): Promise<{ buffer: Uint8Array; mimeType: string }> {
 			const resized = await image.resize(width, height, SamplingFilter.Lanczos3);
 
-			const [pngBuffer, jpegBuffer] = await Promise.all([
+			const [pngBuffer, jpegBuffer, webpBuffer] = await Promise.all([
 				resized.encode(ImageFormat.PNG, quality),
 				resized.encode(ImageFormat.JPEG, quality),
+				resized.encode(ImageFormat.WEBP, quality),
 			]);
 
-			return pickSmaller(
+			return pickSmallest(
 				{ buffer: pngBuffer, mimeType: "image/png" },
 				{ buffer: jpegBuffer, mimeType: "image/jpeg" },
+				{ buffer: webpBuffer, mimeType: "image/webp" },
+			);
+		}
+
+		// Lossy-only encoder — used in quality/dimension fallback ladders where PNG can't shrink
+		// further (PNG quality is a no-op). Picks the smaller of JPEG vs lossy WebP at the
+		// requested quality.
+		async function encodeLossy(
+			width: number,
+			height: number,
+			quality: number,
+		): Promise<{ buffer: Uint8Array; mimeType: string }> {
+			const resized = await image.resize(width, height, SamplingFilter.Lanczos3);
+			const [jpegBuffer, webpBuffer] = await Promise.all([
+				resized.encode(ImageFormat.JPEG, quality),
+				resized.encode(ImageFormat.WEBP, quality),
+			]);
+			return pickSmallest(
+				{ buffer: jpegBuffer, mimeType: "image/jpeg" },
+				{ buffer: webpBuffer, mimeType: "image/webp" },
 			);
 		}
 
-		// Try to produce an image under maxBytes
-		const qualitySteps = [85, 70, 55, 40];
+		// Quality ladder — more aggressive steps for tighter budgets
+		const qualitySteps = [70, 60, 50, 40];
 		const scaleSteps = [1.0, 0.75, 0.5, 0.35, 0.25];
 
 		let best: { buffer: Uint8Array; mimeType: string };
 		let finalWidth = targetWidth;
 		let finalHeight = targetHeight;
 
-		// First attempt: resize to target dimensions, try both formats
-		best = await tryBothFormats(targetWidth, targetHeight, opts.jpegQuality);
+		// First attempt: resize to target, try both PNG and JPEG, pick smaller
+		best = await encodeSmallest(targetWidth, targetHeight, opts.jpegQuality);
 
 		if (best.buffer.length <= opts.maxBytes) {
 			return {
@@ -141,9 +177,9 @@ export async function resizeImage(img: ImageContent, options?: ImageResizeOption
 			};
 		}
 
-		// Still too large - try JPEG with decreasing quality
+		// Still too large — lossy ladder (JPEG vs WebP, smallest wins) with decreasing quality
 		for (const quality of qualitySteps) {
-			best = await tryBothFormats(targetWidth, targetHeight, quality);
+			best = await encodeLossy(targetWidth, targetHeight, quality);
 
 			if (best.buffer.length <= opts.maxBytes) {
 				return {
@@ -161,7 +197,7 @@ export async function resizeImage(img: ImageContent, options?: ImageResizeOption
 			}
 		}
 
-		// Still too large - reduce dimensions progressively
+		// Still too large — reduce dimensions progressively with the lossy ladder
 		for (const scale of scaleSteps) {
 			finalWidth = Math.round(targetWidth * scale);
 			finalHeight = Math.round(targetHeight * scale);
@@ -171,7 +207,7 @@ export async function resizeImage(img: ImageContent, options?: ImageResizeOption
 			}
 
 			for (const quality of qualitySteps) {
-				best = await tryBothFormats(finalWidth, finalHeight, quality);
+				best = await encodeLossy(finalWidth, finalHeight, quality);
 
 				if (best.buffer.length <= opts.maxBytes) {
 					return {