@oh-my-pi/pi-tui 18.12.2 → 18.12.3

package/src/tools/output-meta.ts

@@ -87,7 +87,7 @@ export interface OutputMeta {
 	/** Capture failure of this output itself; aggregate reports keep source failures on their entries. */
 	artifactError?: OutputArtifactError;
 	source?: SourceMeta;
-	/** The output is a bounded page of session artifact storage its `source` re-reads with line selectors; spill-to-artifact skips it. */
+	/** The output is a bounded page of a file or session artifact its `source` re-reads with line selectors; spill-to-artifact skips it. */
 	pagedSource?: true;
 	diagnostics?: DiagnosticMeta;
 	limits?: LimitsMeta;

package/src/tools/streaming-output.ts

@@ -1432,6 +1432,7 @@ export class OutputSink {
 	 * Replace the in-memory buffer with the given text. Used when an upstream
 	 * minimizer rewrites the captured output after the raw bytes have already
 	 * been streamed.
+	 * The replacement is held to the per-line column cap like streamed output.
 	 *
 	 * After this call the buffer is authoritative: streaming counters realign
 	 * to the replacement, the retained head window is cleared, and head
@@ -1442,23 +1443,24 @@ export class OutputSink {
 	 */
 	replace(text: string): void {
 		this.#clearPendingChunkTimer();
-		this.#buffer = text;
-		this.#bufferBytes = Buffer.byteLength(text, "utf-8");
+		this.#currentLineBytes = 0;
+		this.#columnEllipsisAdded = false;
+		this.#columnDroppedBytes = 0;
+		this.#columnTruncatedLines = 0;
+		// The artifact keeps the replaced stream, so later line numbers no longer match it.
+		this.#columnCutLinesUnmapped = true;
+		const capped = this.#maxColumns > 0 ? this.#applyColumnCap(text, 0) : text;
+		this.#buffer = capped;
+		this.#bufferBytes = Buffer.byteLength(capped, "utf-8");
 		this.#tailUntrimmed = false;
 		this.#head = "";
 		this.#headBytes = 0;
 		this.#headLines = 0;
 		this.#headRetentionDisabled = true;
-		this.#totalBytes = this.#bufferBytes;
+		this.#totalBytes = Buffer.byteLength(text, "utf-8");
 		this.#totalLines = countNewlines(text);
 		this.#sawData = text.length > 0;
 		this.#truncated = false;
-		this.#currentLineBytes = 0;
-		this.#columnEllipsisAdded = false;
-		this.#columnDroppedBytes = 0;
-		this.#columnTruncatedLines = 0;
-		// The artifact keeps the replaced stream, so later line numbers no longer match it.
-		this.#columnCutLinesUnmapped = true;
 		this.#pendingChunk = "";
 		this.#pendingCarriageReturn = false;
 	}

package/src/tools/task.ts

@@ -764,6 +764,15 @@ function renderAgentProgress(
 
 	// Current tool (if running) or most recent completed tool
 	if (progress.status === "running") {
+		if (progress.stage) {
+			lines.push(
+				truncateTaskRow(
+					`${continuePrefix}${theme.fg("muted", replaceTabs(sanitizeText(progress.stage)))}`,
+					maxWidth,
+					"",
+				),
+			);
+		}
 		if (progress.currentTool) {
 			let toolLine = `${continuePrefix}${theme.tree.hook} ${theme.fg("muted", sanitizeText(progress.currentTool))}`;
 			const toolDetail = toolCallDetail(
@@ -1873,6 +1882,9 @@ function describeProgressAgent(progress: AgentProgress, state: AgentDescribeStat
 					age: progress.currentToolStartMs ? Math.max(0, nowMs - progress.currentToolStartMs) : undefined,
 				}
 			: null;
+	const summary = taskSummary(progress.description || progress.assignment || progress.task);
+	// The agent's own stage line (from its completion probe) rides beside the task while it runs.
+	const stage = running && progress.stage ? plainText(progress.stage) : "";
 	const retry =
 		running && progress.retryState
 			? {
@@ -1887,7 +1899,7 @@ function describeProgressAgent(progress: AgentProgress, state: AgentDescribeStat
 		{
 			name: formatTaskId(progress.id),
 			agent: progress.agent || undefined,
-			task: taskSummary(progress.description || progress.assignment || progress.task) || undefined,
+			task: stage ? (summary ? [span(summary), span(` · ${stage}`, "muted")] : stage) : summary || undefined,
 			status,
 			model: progress.resolvedModelIdentity ?? progress.resolvedModel,
 			thinking: thinkingToken(progress.resolvedThinkingLevel),
@@ -2383,6 +2395,18 @@ export interface AgentProgress {
 	advisor?: boolean;
 	/** The agent's latest self-estimate of task completion (0–100), from the periodic `task.completionProbe` side request. */
 	completionPercent?: number;
+	/**
+	 * The agent's current step in its own words (one line, ≤ 80 chars), from the
+	 * same probe reply as {@link completionPercent}. Running rows prefer it over
+	 * `lastIntent`; the job widget uses it as its stage line.
+	 */
+	stage?: string;
+	/**
+	 * What the agent says shows its progress live (one line, ≤ 200 chars), e.g.
+	 * "BENCH lines in bg_2 pipe:1, tok_s higher is better, target 70% of roofline";
+	 * from the probe reply. Feeds the job widget author's brief; never rendered.
+	 */
+	watch?: string;
 	/** Data extracted by registered subprocess tool handlers (keyed by tool name) */
 	extractedToolData?: Record<string, unknown[]>;
 	/**

package/src/tools/wait.ts

@@ -24,10 +24,11 @@ import {
 	type ConfiguredThinkingLevel,
 } from "../render/render-utils";
 import type { StructuredSubagentOutput } from "./task";
+import { describeJobTiles, type JobTile, type JobWidgetView, renderJobTileLines } from "./job-widget";
 import type { RenderResultOptions, ToolRenderer, ToolActivitySummary } from "./renderer";
 import type { IrcDeliveryReceipt, IrcMessage } from "./irc";
 import type { TspSpan } from "@oh-my-pi/pi-wire";
-import { card as cardNode, compact, elapsed, md, node, row, span, text } from "../native/describe";
+import { card as cardNode, compact, elapsed, keyed, md, node, row, span, text } from "../native/describe";
 import type { NativeNode } from "../native/node";
 import { OwnerMemo } from "../native/memo";
 import { plainText } from "../native/spans";
@@ -63,6 +64,10 @@ export interface JobSnapshot {
 	advisor?: boolean;
 	/** The task agent's latest self-estimated completion (0–100); see `AgentProgress.completionPercent`. */
 	completionPercent?: number;
+	/** The task agent's latest stage in its own words; see `AgentProgress.stage`. */
+	stage?: string;
+	/** The job's live widget, while one is being drawn; frozen at its last state once the job settles. */
+	widget?: JobWidgetView;
 	resultText?: string;
 	errorText?: string;
 	/** Source-output metadata retained for per-job warnings and persisted row rendering. */
@@ -194,6 +199,40 @@ function flattenStructuredPreview(text: string): string {
 	return text.slice(0, PREVIEW_LINES_EXPANDED * PREVIEW_LINE_WIDTH * 2).replace(/\s+/g, " ");
 }
 
+/** The row label: a running task's own stage line when it reports one, else the job's label. */
+function jobRowLabel(job: JobSnapshot): string {
+	return job.type === "task" && job.status === "running" && job.stage?.trim() ? job.stage : job.label;
+}
+
+/** A job as its tile; `live` while the card's clocks run. */
+function jobTile(job: JobSnapshot, live: boolean): JobTile {
+	return {
+		id: job.id,
+		type: job.type,
+		status: job.status,
+		label: job.label,
+		durationMs: job.durationMs,
+		live: live && job.status === "running",
+		...(job.widget ? { widget: job.widget } : {}),
+		...(job.status === "running" && job.completionPercent !== undefined
+			? { completionPercent: job.completionPercent }
+			: {}),
+		...(job.stage ? { stage: job.stage } : {}),
+		...(job.exitCode === undefined ? {} : { exitCode: job.exitCode }),
+	};
+}
+
+/** Identity of the widgets a job list draws: changes whenever any widget's data or state does. */
+function widgetStamp(jobs: readonly JobSnapshot[] | undefined): string {
+	if (!jobs) return "";
+	let stamp = "";
+	for (const job of jobs) if (job.widget) stamp += `${job.id}:${job.widget.updatedAt}:${job.widget.state};`;
+	return stamp;
+}
+
+/** Tiles a native wait card shows before it counts the rest. */
+const TILES_SHOWN = 9;
+
 /** Pending wait frame. */
 function waitRenderCall(_args: object, _options: RenderResultOptions, uiTheme: Theme): Component {
 	return new Text(renderStatusLine({ icon: "pending", title: "Wait" }, uiTheme), 0, 0);
@@ -201,7 +240,11 @@ function waitRenderCall(_args: object, _options: RenderResultOptions, uiTheme: T
 
 /** Result frame for wait snapshots and the agents roster. */
 function jobsRenderResult(
-	result: { content: Array<{ type: string; text?: string }>; details?: CoordinationDetails; isError?: boolean },
+	result: {
+		content: Array<{ type: string; text?: string }>;
+		details?: CoordinationDetails;
+		isError?: boolean;
+	},
 	options: RenderResultOptions,
 	uiTheme: Theme,
 ): Component {
@@ -326,6 +369,7 @@ function jobsRenderResult(
 				.u32(spinnerFrame)
 				.bool(shimmerActive)
 				.bool(showModelBadge)
+				.str(widgetStamp(jobs))
 				.digest();
 			if (!shimmerActive && cached?.key === key) return cached.lines;
 
@@ -354,7 +398,8 @@ function jobsRenderResult(
 							Math.max(0, rowWidth - visibleWidth(`${icon} ${typeBadge} ${durationSuffix}`)),
 							Ellipsis.Unicode,
 						);
-						const rawLabelLines = (job.label || "(no label)").split(/\r?\n/);
+						const rowLabel = jobRowLabel(job);
+						const rawLabelLines = (rowLabel || "(no label)").split(/\r?\n/);
 						const maxLabelLines = expanded ? LABEL_LINES_EXPANDED : LABEL_LINES_COLLAPSED;
 						const visibleLabelLines = rawLabelLines
 							.slice(0, maxLabelLines)
@@ -364,44 +409,63 @@ function jobsRenderResult(
 							visibleLabelLines[visibleLabelLines.length - 1] = `${last} …`;
 						}
 						const rowPrefix = `${icon} ${typeBadge} `;
-						const modelIdentity = job.resolvedModelIdentity ?? job.resolvedModel;
-						const modelBadge =
-							job.type === "task" && showModelBadge && typeof modelIdentity === "string"
-								? formatFeedModelBadge(
-										modelIdentity,
-										job.resolvedThinkingLevel,
-										job.advisor === true,
-										uiTheme,
-										Math.min(
-											FEED_MODEL_BADGE_WIDTH,
-											Math.max(0, rowWidth - visibleWidth(`${rowPrefix}${displayId}${durationSuffix}`) - 1),
-										),
-									)
-								: "";
-						const modelLead = modelBadge ? `${modelBadge} ` : "";
-						const headRaw = displayId;
-						// Running rows in a live block shimmer their label; once the block
-						// stops animating (sealed, or a settled snapshot — spinnerFrame
-						// cleared) they render static so scrollback never keeps a mid-sweep
-						// shimmer band.
 						const live = job.status === "running" && options.spinnerFrame !== undefined;
-						const headLabel = live
-							? shimmerEnabled()
-								? shimmerText(headRaw, uiTheme)
-								: uiTheme.fg("accent", headRaw)
-							: uiTheme.fg("toolOutput", headRaw);
-						let row = `${rowPrefix}${modelLead}${headLabel}`;
-						const distinctLabel = job.label.trim() !== job.id;
-						const label = visibleLabelLines[0] ?? "";
-						const inlineLabel = distinctLabel && visibleWidth(`${row} ${label}${durationSuffix}`) <= rowWidth;
-						if (inlineLabel) row += ` ${uiTheme.fg("toolOutput", label)}`;
-						row += durationSuffix;
-						lines.push(truncateToWidth(row, rowWidth, ""));
 						const continuationWidth = Math.max(0, rowWidth - visibleWidth("  "));
-						for (let i = distinctLabel && !inlineLabel ? 0 : 1; i < visibleLabelLines.length; i++) {
+						if (job.widget?.state === "live") {
+							const meta = compact([
+								job.status === "running" && job.completionPercent !== undefined
+									? uiTheme.fg("accent", `${job.completionPercent}%`)
+									: undefined,
+								uiTheme.fg("dim", formatDuration(job.durationMs)),
+							]).join(" ");
 							lines.push(
-								`  ${uiTheme.fg("toolOutput", truncateToWidth(visibleLabelLines[i]!, continuationWidth))}`,
+								...renderJobTileLines(jobTile(job, live), rowWidth, uiTheme, {
+									lead: rowPrefix,
+									meta,
+									full: expanded,
+								}),
 							);
+						} else {
+							const modelIdentity = job.resolvedModelIdentity ?? job.resolvedModel;
+							const modelBadge =
+								job.type === "task" && showModelBadge && typeof modelIdentity === "string"
+									? formatFeedModelBadge(
+											modelIdentity,
+											job.resolvedThinkingLevel,
+											job.advisor === true,
+											uiTheme,
+											Math.min(
+												FEED_MODEL_BADGE_WIDTH,
+												Math.max(
+													0,
+													rowWidth - visibleWidth(`${rowPrefix}${displayId}${durationSuffix}`) - 1,
+												),
+											),
+										)
+									: "";
+							const modelLead = modelBadge ? `${modelBadge} ` : "";
+							const headRaw = displayId;
+							// Running rows in a live block shimmer their label; once the block
+							// stops animating (sealed, or a settled snapshot — spinnerFrame
+							// cleared) they render static so scrollback never keeps a mid-sweep
+							// shimmer band.
+							const headLabel = live
+								? shimmerEnabled()
+									? shimmerText(headRaw, uiTheme)
+									: uiTheme.fg("accent", headRaw)
+								: uiTheme.fg("toolOutput", headRaw);
+							let row = `${rowPrefix}${modelLead}${headLabel}`;
+							const distinctLabel = rowLabel.trim() !== job.id;
+							const label = visibleLabelLines[0] ?? "";
+							const inlineLabel = distinctLabel && visibleWidth(`${row} ${label}${durationSuffix}`) <= rowWidth;
+							if (inlineLabel) row += ` ${uiTheme.fg("toolOutput", label)}`;
+							row += durationSuffix;
+							lines.push(truncateToWidth(row, rowWidth, ""));
+							for (let i = distinctLabel && !inlineLabel ? 0 : 1; i < visibleLabelLines.length; i++) {
+								lines.push(
+									`  ${uiTheme.fg("toolOutput", truncateToWidth(visibleLabelLines[i]!, continuationWidth))}`,
+								);
+							}
 						}
 						const artifactError = job.meta?.artifactError ?? job.artifactError;
 						if (artifactError) {
@@ -498,7 +562,11 @@ function bodyLines(
 	body: string,
 	expanded: boolean,
 	theme: Theme,
-	options: { indent?: string; tone?: "dim" | "toolOutput"; collapsedLines?: number } = {},
+	options: {
+		indent?: string;
+		tone?: "dim" | "toolOutput";
+		collapsedLines?: number;
+	} = {},
 ): string[] {
 	const indent = options.indent ?? "";
 	const tone = options.tone ?? "toolOutput";
@@ -561,7 +629,12 @@ export function createIrcMessageCard(
 		(width, expanded) => {
 			const lines = [renderStatusLine({ iconOverride: ircGlyph(uiTheme), title, meta }, uiTheme)];
 			if (body.trim()) {
-				lines.push(...bodyLines(body, expanded, uiTheme, { indent: "  ", collapsedLines: 3 }));
+				lines.push(
+					...bodyLines(body, expanded, uiTheme, {
+						indent: "  ",
+						collapsedLines: 3,
+					}),
+				);
 			}
 			return lines.map(line => truncateToWidth(line, width, Ellipsis.Unicode));
 		},
@@ -589,47 +662,6 @@ export function createIrcMessageCard(
 	return Object.assign(component, { describe: () => described });
 }
 
-/**
- * One job row on one line: type badge, id + label, terminal-clocked duration
- * (live while running). The job's output and errors fill the card of the call
- * that started it (`parksAsBackground`), so the row carries no preview.
- */
-function describeJob(job: JobSnapshot, isPartial: boolean): NativeNode {
-	const running = job.status === "running" && isPartial;
-	const label = job.label.trim() !== job.id ? plainText(job.label.split(/\r?\n/)[0] ?? "") : "";
-	const spans: TspSpan[] = [
-		span(plainText(job.id), running ? "accent" : "toolOutput", running ? { fx: "shimmer" } : undefined),
-	];
-	if (label) spans.push(span(` ${label}`, "toolOutput"));
-	if (job.exitCode !== undefined) spans.push(span(` exit ${job.exitCode}`, job.exitCode === 0 ? "muted" : "error"));
-	const tone =
-		job.status === "completed"
-			? "success"
-			: job.status === "failed"
-				? "error"
-				: job.status === "cancelled"
-					? "warning"
-					: "accent";
-	return node(
-		"row",
-		{ role: "omp.wait.job", tone, gap: "sm" },
-		compact([
-			node("badge", { text: job.type, tone }),
-			text(spans, { truncate: "end", grow: 1 }),
-			job.status === "running" && job.completionPercent !== undefined
-				? node("progress", {
-						value: job.completionPercent / 100,
-						label: `${job.completionPercent}%`,
-						tone: "accent",
-						title: "Agent's own completion estimate",
-					})
-				: undefined,
-			elapsed(job.durationMs, !running),
-		]),
-		job.id,
-	);
-}
-
 function describeJobsResult(
 	result: ToolRenderResult<CoordinationDetails>,
 	isPartial: boolean,
@@ -658,9 +690,23 @@ function describeJobsResult(
 	if (counts.completed > 0) head.push(span(` ${counts.completed} done`, "success"));
 	if (counts.failed > 0) head.push(span(` ${counts.failed} failed`, "error"));
 	if (counts.cancelled > 0) head.push(span(` ${counts.cancelled} cancelled`, "warning"));
-	const order: Record<JobSnapshot["status"], number> = { running: 0, failed: 1, cancelled: 2, completed: 3 };
+	const order: Record<JobSnapshot["status"], number> = {
+		running: 0,
+		failed: 1,
+		cancelled: 2,
+		completed: 3,
+	};
 	const sorted = [...jobs].sort((a, b) => order[a.status] - order[b.status] || b.durationMs - a.durationMs);
-	const body: NativeNode[] = sorted.map(job => describeJob(job, isPartial));
+	// One frame of tiles: each job's status, title, figure and widget together. The job's output
+	// and errors fill the card of the call that started it (`parksAsBackground`), so no previews.
+	const body: NativeNode[] = [];
+	if (sorted.length > 0) {
+		body.push(keyed(describeJobTiles(sorted.slice(0, TILES_SHOWN).map(job => jobTile(job, isPartial))), "tiles"));
+	}
+	if (sorted.length > TILES_SHOWN) {
+		const rest = sorted.length - TILES_SHOWN;
+		body.push(text([span(`+${rest} more ${rest === 1 ? "job" : "jobs"} · /jobs`, "dim")], { role: "omp.wait.more" }));
+	}
 	for (const agent of agents) {
 		const spans: TspSpan[] = [span(plainText(agent.id), "muted")];
 		if (agent.activity) spans.push(span(` ${plainText(agent.activity)}`, "toolOutput"));
@@ -684,6 +730,8 @@ function describeJobsResult(
 	return {
 		head,
 		tone: counts.failed > 0 ? "warning" : counts.running > 0 || agents.length > 0 ? "info" : "success",
+		// The tiles are what a wait shows: clamping the body by lines would cut them.
+		preview: "children",
 		body,
 	};
 }
@@ -729,11 +777,15 @@ export const waitToolRenderer = {
 		result: ToolRenderResult<CoordinationDetails>,
 		options: RenderResultOptions,
 	): NativeToolView | undefined {
-		return waitResultMemo.get(result, [options.isPartial], () => {
+		return waitResultMemo.get(result, [options.isPartial, widgetStamp(result.details?.jobs)], () => {
 			if (result.isError) return errorView("Wait", resultText(result));
 			const details = result.details;
 			if (details?.interrupted) {
-				return { head: toolHead("Wait", "interrupted by message"), tone: "info", inline: true };
+				return {
+					head: toolHead("Wait", "interrupted by message"),
+					tone: "info",
+					inline: true,
+				};
 			}
 			const waited = details?.waited;
 			if (!waited) return describeJobsResult(result, options.isPartial);
@@ -741,7 +793,11 @@ export const waitToolRenderer = {
 		});
 	},
 	renderResult(
-		result: { content: Array<{ type: string; text?: string }>; details?: CoordinationDetails; isError?: boolean },
+		result: {
+			content: Array<{ type: string; text?: string }>;
+			details?: CoordinationDetails;
+			isError?: boolean;
+		},
 		options: RenderResultOptions,
 		uiTheme: Theme,
 	): Component {

package/src/tui.ts

@@ -28,6 +28,7 @@ import { assumedTspHello, NativeBackend, type NativeHost } from "./native/backen
 import { col } from "./native/describe";
 import { TSP_PREFIX, type TspHello } from "./native/encode";
 import type { DescribeContext, NativeNode, NativeScreen, NativeSurfaceProvider, NativeUiEvent } from "./native/node";
+import { cropSixelTop } from "./sixel";
 import { STDOUT_BACKLOG_CLEAR_BYTES, setAltScreenActive, type Terminal } from "./terminal";
 import { classifyTerminalMultiplexerModule, terminalMultiplexerSessions } from "./terminal-multiplexer";
 import {
@@ -36,6 +37,7 @@ import {
 	encodeKittyDeleteImage,
 	encodeKittyDeletePlacement,
 	encodeKittyPlacementLine,
+	getCellDimensions,
 	getTerminalBackgroundColor,
 	ImageProtocol,
 	isImageProtocolForced,
@@ -1004,6 +1006,8 @@ export class TUI extends Container {
 	#screenImagePlacements = new Map<number, LiveImagePlacement>();
 	#altImagePlacements = new Map<number, LiveImagePlacement>();
 	#nextImagePlacementId = 1;
+	/** Last top-clipped SIXEL crop; only the block straddling row 0 is ever cropped. */
+	#sixelCrop: { source: string; pixels: number; maxHeightPixels: number; output: string } | undefined;
 	#ghosttyInitialImageDelayDone = false;
 	#ghosttyInitialImageDelayTimer: RenderTimer | undefined;
 	#ghosttyImageReadyAtMs = 0;
@@ -3287,10 +3291,11 @@ export class TUI extends Container {
 	}
 
 	/**
-	 * Clip a Kitty direct placement and record its live owner; history
-	 * placements have no mutable owner. Other direct placements (SIXEL,
-	 * iTerm2) have no delete command and composite over whatever pixels they
-	 * land on, so the rows they paint above `screenRow` are erased first.
+	 * Clip direct placements to the visible source slice: Kitty tracks a live
+	 * placement owner, while SIXEL crops the encoded raster (iTerm2 images are
+	 * not cropped). SIXEL and iTerm2 have no delete command and composite over
+	 * existing pixels, so erase the visible rows they paint above `screenRow`
+	 * before repainting.
 	 */
 	#imageLineSequence(
 		line: string,
@@ -3301,7 +3306,16 @@ export class TUI extends Container {
 		if (screenRow < 0) return line;
 		const parsed = parseKittyDirectPlacementLine(line);
 		if (!parsed) {
-			const lift = Math.min(directPlacementLift(line), screenRow);
+			const requestedLift = directPlacementLift(line);
+			const lift = Math.min(requestedLift, screenRow);
+			if (requestedLift > lift) {
+				const cellHeight = getCellDimensions().heightPx;
+				const cropPixels = Math.round((requestedLift - lift) * cellHeight);
+				const maxHeightPixels = Math.floor((screenRow + 1) * cellHeight);
+				line = line.replace(/\x1bP[0-9;]*q[\s\S]*?\x1b\\/g, sequence =>
+					this.#cropSixel(sequence, cropPixels, maxHeightPixels),
+				);
+			}
 			return lift > 0 ? `\x1b[${lift}A${`${ERASE_LINE}\x1b[B`.repeat(lift)}${line}` : line;
 		}
 		const previous = placements?.get(placementRow);
@@ -3321,6 +3335,32 @@ export class TUI extends Container {
 		);
 	}
 
+	/**
+	 * Crop a SIXEL raster whose top rows lie above the viewport. A raster the
+	 * cropper cannot parse is dropped: painting it whole would overwrite the
+	 * rows below the visible slice.
+	 */
+	#cropSixel(source: string, pixels: number, maxHeightPixels: number): string {
+		const cached = this.#sixelCrop;
+		if (
+			cached !== undefined &&
+			cached.pixels === pixels &&
+			cached.maxHeightPixels === maxHeightPixels &&
+			cached.source === source
+		) {
+			return cached.output;
+		}
+		let output: string;
+		try {
+			output = cropSixelTop(source, pixels, maxHeightPixels);
+		} catch (err) {
+			logger.warn("Dropping top-clipped SIXEL image that cannot be cropped", { err });
+			output = "";
+		}
+		this.#sixelCrop = { source, pixels, maxHeightPixels, output };
+		return output;
+	}
+
 	#terminalLine(line: PreparedLine): string {
 		if (line.hasOsc8) return line.terminalContent + LINE_TERMINATOR;
 		return line.terminalContent.endsWith(SEGMENT_RESET) ? line.terminalContent : line.terminalContent + SEGMENT_RESET;