@oh-my-pi/pi-tui 18.0.10 → 18.1.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [18.1.0] - 2026-09-01
+
+### Fixed
+
+- Improved terminal stability when resuming image-heavy sessions, preventing large transcript repaints from being mistaken for stalled output or exceeding the terminal output limit.
+- Fixed inline images leaving blank rows in Herdr panes when resuming or rendering sessions in nested terminals.
+- Fixed the TUI crashing on reference-style Markdown links whose labels match JavaScript built-in names; these links now render safely as plain text.
+- Fixed fatal cleanup leaving the cursor inside a focused input before error output is displayed.
+- Fixed resumed sessions showing stale background bands until the next keypress in WSL and Windows Terminal.
+
+## [18.0.11] - 2026-08-29
+
+### Added
+
+- Added `setTerminalHyperlinks()` to let hosts control OSC 8 hyperlink behavior in rendered Markdown links.
+
+### Fixed
+
+- Fixed inline color swatches appearing for words with hex-like prefixes, such as `#each`; swatches now appear only when the entire word is a valid color.
+
 ## [18.0.10] - 2026-08-28
 
 ### Added

package/dist/types/components/composer/registry.d.ts

@@ -1,6 +1,13 @@
 import type { ComposerStyle, EditorBorderStyle } from "./types.js";
 /** Whether an id names a composer style shipped by pi-tui. */
 export declare function isBuiltinComposerStyle(id: string): boolean;
+/**
+ * Whether a style paints its own row foreground.
+ *
+ * Extensions registered before `filledSurface` existed received undecorated
+ * row text, so an omitted flag remains filled for extension-owned ids.
+ */
+export declare function isFilledComposerStyle(style: ComposerStyle): boolean;
 /**
  * Register one extension-owned composer style for this process.
  *

package/dist/types/components/composer/types.d.ts

@@ -60,6 +60,12 @@ export interface ComposerRowContext extends ComposerChromeContext {
 }
 export interface ComposerStyle {
     readonly id: EditorBorderStyle;
+    /**
+     * True when rows paint their own foreground through `surfaceColor`.
+     * Built-ins default to transparent; registered extensions that omit this
+     * field retain the pre-field behavior and receive undecorated row text.
+     */
+    readonly filledSurface?: boolean;
     /** Content rows carry left/right border glyphs; drives the cursor-reserve
      *  column, IME-safe layout, and the right-border scrollbar. */
     readonly sideBorders: boolean;

package/dist/types/components/editor.d.ts

@@ -10,6 +10,8 @@ export interface EditorTheme {
     accentColor?: (str: string) => string;
     /** Background fill used by filled composer styles. */
     surfaceColor?: (str: string) => string;
+    /** Foreground used when the composer shape leaves its text surface transparent. */
+    textColor?: (str: string) => string;
     selectList: SelectListTheme;
     symbols: SymbolTheme;
     editorPaddingX?: number;

package/dist/types/components/image.d.ts

@@ -29,9 +29,9 @@ export declare const DEFAULT_MAX_INLINE_IMAGES = 8;
  *
  * The budget keeps the most recent `cap` images live and demotes older ones to
  * their text fallback. Demotion needs a full redraw (so off-screen rows are
- * rewritten) plus an explicit graphics purge of the demoted ids — {@link Image}
- * reports display order via {@link observe}, and the TUI drives the purge +
- * redraw on the frame after a new image pushes the count past the cap.
+ * rewritten) plus an explicit graphics purge of the demoted ids. {@link Image}
+ * reports display order via {@link observe}; when that reveals a stricter split,
+ * the TUI repeats the pass before emitting its terminal frame.
  *
  * `cap <= 0` disables budgeting: every image stays a live graphic.
  */
@@ -67,9 +67,8 @@ export declare class ImageBudget {
      */
     observe(imageId: number): boolean;
     /**
-     * End a render pass. Returns true when this frame must purge graphics and
-     * fully repaint to apply a stricter budget; read the ids via
-     * {@link takePurgeIds}.
+     * End a render pass. Returns true when the pass discovered a stricter budget
+     * and must be repeated before its terminal frame is emitted.
      */
     endPass(): boolean;
     /** Image ids to delete from the terminal this frame; clears the pending set. */

package/dist/types/kitty-graphics.d.ts

@@ -26,12 +26,12 @@ export interface KittyGraphicsFeatures {
  * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
  * U+10EEEE with row/column diacritics).
  *
- * Kitty and Ghostty advertise placeholder support directly. A tmux session
+ * Kitty and Ghostty advertise placeholder support directly. A multiplexer
  * cannot use cursor-positioned placements because the outer terminal does not
- * know pane scroll/reflow state, so an explicit `PI_FORCE_IMAGE_PROTOCOL=kitty`
- * also opts into placeholders there — matching `timg -pk`. Automatic tmux
- * fallback stays off because the unknown outer terminal may render U+10EEEE as
- * literal PUA boxes (#1877).
+ * know pane scroll/reflow state. An explicit `PI_FORCE_IMAGE_PROTOCOL=kitty`
+ * opts into placeholders under any multiplexer — matching `timg -pk`.
+ * Automatic Herdr fallback stays off because its pane marker does not prove
+ * that the experimental Kitty renderer is enabled.
  *
  * `PI_NO_KITTY_PLACEHOLDERS=1` and `PI_KITTY_PLACEHOLDERS=0` remain hard
  * opt-outs; `PI_KITTY_PLACEHOLDERS=1` explicitly opts in anywhere else.

package/dist/types/terminal-capabilities.d.ts

@@ -1,4 +1,5 @@
 import type { HangulCompatibilityJamoWidth } from "./utils.js";
+export * from "./terminal-multiplexer.js";
 export { isInsideTmux, wrapTmuxPassthrough } from "./tmux.js";
 export declare enum ImageProtocol {
     Kitty = "\u001B_G",
@@ -48,8 +49,6 @@ export declare class TerminalInfo {
     formatNotification(message: string | TerminalNotification): string;
     sendNotification(message: string | TerminalNotification): void;
 }
-/** Detect terminal multiplexers where scrollback clearing and height-change redraws are hostile. */
-export declare function isInsideTerminalMultiplexer(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Whether the agent process is running inside a Zellij session. Read fresh on
  * each call (like {@link isInsideTmux}) so a session attached/detached mid-run
@@ -165,9 +164,9 @@ export declare function isPaseoEmbedder(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Resolve the image protocol for a non-forced runtime: static per-terminal
  * support (with Warp's platform carve-out), then the multiplexer fallback,
- * then the Paseo embedder carve-out. `isTTY` is injectable because the
- * fallback only fires on a real TTY — a piped subprocess cannot exercise
- * that path, so regression tests call this directly.
+ * then host carve-outs. `isTTY` is injectable because the fallback only fires
+ * on a real TTY — a piped subprocess cannot exercise that path, so regression
+ * tests call this directly.
  */
 export declare function resolveImageProtocol(terminalId: TerminalId, env?: NodeJS.ProcessEnv, isTTY?: boolean): ImageProtocol | null;
 /** Resolve terminal identity from environment markers used by common emulators. */
@@ -206,6 +205,15 @@ export declare function setTerminalScreenToScrollback(enabled: boolean): void;
  * capability); tests flip it directly to exercise the scaled-heading path.
  */
 export declare function setTerminalTextSizing(enabled: boolean): void;
+/**
+ * Override OSC 8 hyperlink capability at runtime. The coding-agent calls this
+ * from the `tui.hyperlinks` setting so its resolved policy (`off`/`auto`/`always`)
+ * drives every renderer that gates on {@link TERMINAL}`.hyperlinks` — notably the
+ * Markdown component's `[text](url)`/bare-URL links — consistently with the
+ * path/resource links that already consult the setting directly. Tests flip it
+ * to exercise the OSC 8 and plain-text paths deterministically.
+ */
+export declare function setTerminalHyperlinks(enabled: boolean): void;
 export declare function getTerminalInfo(terminalId: TerminalId, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): TerminalInfo;
 export interface CellDimensions {
     widthPx: number;

package/dist/types/terminal-multiplexer.d.ts

@@ -0,0 +1,2 @@
+/** Detect whether a terminal multiplexer owns the current screen grid. */
+export declare function isInsideTerminalMultiplexer(env?: NodeJS.ProcessEnv): boolean;

package/dist/types/terminal.d.ts

@@ -20,33 +20,50 @@
  */
 export declare function chunkForConPTY(data: string, maxChunkBytes?: number): string[];
 /**
- * Turns an unbounded, never-draining stdout writable buffer into a bounded
- * disconnect signal.
+ * Backlog at or below which stdout is healthy again: the pump has kept up, the
+ * TUI resumes composing frames, and a {@link StdoutStallWatchdog} episode ends.
+ * The TUI render gate (`TUI.#MAX_PENDING_OUTPUT_BYTES`) is this same value, so
+ * the watchdog stays armed across the entire range where frames are deferred —
+ * otherwise a consumer that wedges between this level and the arm cap is never
+ * re-sampled and the session freezes instead of disconnecting (#10434 review).
+ */
+export declare const STDOUT_BACKLOG_CLEAR_BYTES: number;
+/**
+ * Bounds a never-draining stdout backlog without killing a single large but
+ * actively-draining frame.
  *
  * `process.stdout.write()` returns `false` once its buffer exceeds the stream
- * high-water mark; the bytes stay queued and are only freed when the consumer
- * drains (the `drain` event). While the consumer keeps up, writes are accepted
- * and nothing accumulates. When it stalls, every subsequent write piles onto
- * the buffer — a stalled-but-alive PTY reader never throws, so the write path
- * has no other signal that output is going nowhere. This guard sums the bytes
- * queued since backpressure began and reports when that backlog crosses the
- * cap, at which point the caller treats the terminal as disconnected.
+ * high-water mark, and the off-thread pump's `pending()` climbs the same way;
+ * a stalled-but-alive PTY reader never throws, so the byte count is the only
+ * signal that output is going nowhere. Tripping on the instantaneous count
+ * alone is wrong: a legitimate oversized frame (a resume repaint of dozens of
+ * inline screenshots, #10430) briefly exceeds the cap and then drains.
+ *
+ * An episode starts when the backlog first exceeds `armBytes` and lasts until
+ * it drains back to `clearBytes` (healthy). The backlog can fall below
+ * `armBytes` while still unhealthy, so the episode must outlive that dip
+ * (#10434): during it the watchdog declares the terminal disconnected only when
+ * the backlog makes no drain progress (no new low-water mark) for `stallMs` —
+ * a draining terminal keeps lowering the mark and never trips, while a wedged
+ * one (#6854) still tears down within the window.
  *
  * Exported for unit testing; `ProcessTerminal` is the sole production user.
  */
-export declare class OutputBacklogGuard {
+export declare class StdoutStallWatchdog {
     #private;
-    private readonly capBytes;
-    constructor(capBytes?: number);
-    /** True once a refused write started a backlog that has not yet drained. */
-    get tracking(): boolean;
+    private readonly armBytes;
+    private readonly clearBytes;
+    private readonly stallMs;
+    constructor(armBytes?: number, clearBytes?: number, stallMs?: number);
+    /** True while an episode is active and the backlog must be polled to completion. */
+    get armed(): boolean;
     /**
-     * Record one `stdout.write()`: `accepted` is that call's return value and
-     * `bytes` its encoded size. Returns true when the pending backlog now
-     * exceeds the cap and the terminal should be treated as disconnected.
+     * Feed the current pending-byte count and clock reading. Returns true once an
+     * armed episode has gone `stallMs` with no drain progress, at which point the
+     * caller treats the terminal as disconnected.
      */
-    record(accepted: boolean, bytes: number): boolean;
-    /** Called on the stdout `drain` event: the buffer emptied, backlog cleared. */
+    sample(pending: number, nowMs: number): boolean;
+    /** Episode ended (drained) or terminal torn down: stop watching. */
     reset(): void;
 }
 /** Record alternate-screen state (called by the TUI on `?1049h`/`?1049l` writes). */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "18.0.10",
+	"version": "18.1.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -29,16 +29,16 @@
 	"main": "./src/index.ts",
 	"types": "./dist/types/index.d.ts",
 	"scripts": {
-		"check": "biome check . && bun run check:types",
+		"check": "oxlint . && oxfmt --check --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts' && bun run check:types",
 		"check:types": "tsgo -p tsconfig.json --noEmit",
-		"lint": "biome lint .",
+		"lint": "oxlint .",
 		"test": "bun test --parallel test/*.test.ts",
-		"fix": "biome check --write --unsafe .",
-		"fmt": "biome format --write ."
+		"fix": "oxlint --fix --fix-suggestions . && bun run fmt",
+		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.0.10",
-		"@oh-my-pi/pi-utils": "18.0.10"
+		"@oh-my-pi/pi-natives": "18.1.0",
+		"@oh-my-pi/pi-utils": "18.1.0"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/autocomplete.ts

@@ -382,7 +382,7 @@ function buildSlashCommandCompletions(
 			// Equal text-match scores fall back to usage frequency, then to the
 			// stable registry order.
 			.sort((a, b) => b.score - a.score || b.usage - a.usage)
-			.map(({ score: _, usage: _usage, ...rest }) => rest)
+			.map(({ score: _score, usage: _usage, ...rest }) => rest)
 	);
 }
 

package/src/components/composer/field.ts

@@ -11,6 +11,7 @@ const RIGHT_CAP = "▌";
 /** One-row filled field with accent caps. */
 export const fieldComposerStyle: ComposerStyle = {
 	id: "field",
+	filledSurface: true,
 	sideBorders: true,
 	verticalChrome: 0,
 	statusAttachment: "none",

package/src/components/composer/rail.ts

@@ -10,6 +10,7 @@ const ACCENT_RAIL = "▎";
 /** Filled composer surface anchored by a single left accent rail. */
 export const railComposerStyle: ComposerStyle = {
 	id: "rail",
+	filledSurface: true,
 	sideBorders: true,
 	verticalChrome: 0,
 	statusAttachment: "none",

package/src/components/composer/registry.ts

@@ -25,6 +25,16 @@ export function isBuiltinComposerStyle(id: string): boolean {
 	return Object.hasOwn(BUILTIN_COMPOSER_STYLES, id);
 }
 
+/**
+ * Whether a style paints its own row foreground.
+ *
+ * Extensions registered before `filledSurface` existed received undecorated
+ * row text, so an omitted flag remains filled for extension-owned ids.
+ */
+export function isFilledComposerStyle(style: ComposerStyle): boolean {
+	return style.filledSurface ?? !isBuiltinComposerStyle(style.id);
+}
+
 /**
  * Register one extension-owned composer style for this process.
  *

package/src/components/composer/types.ts

@@ -77,6 +77,12 @@ export interface ComposerRowContext extends ComposerChromeContext {
 
 export interface ComposerStyle {
 	readonly id: EditorBorderStyle;
+	/**
+	 * True when rows paint their own foreground through `surfaceColor`.
+	 * Built-ins default to transparent; registered extensions that omit this
+	 * field retain the pre-field behavior and receive undecorated row text.
+	 */
+	readonly filledSurface?: boolean;
 	/** Content rows carry left/right border glyphs; drives the cursor-reserve
 	 *  column, IME-safe layout, and the right-border scrollbar. */
 	readonly sideBorders: boolean;

package/src/components/editor.ts

@@ -32,6 +32,7 @@ import {
 	type EditorBorderStyle,
 	type EditorTopBorder,
 	getComposerStyle,
+	isFilledComposerStyle,
 } from "./composer";
 
 export type { EditorBorderStyle, EditorTopBorder };
@@ -401,6 +402,8 @@ export interface EditorTheme {
 	accentColor?: (str: string) => string;
 	/** Background fill used by filled composer styles. */
 	surfaceColor?: (str: string) => string;
+	/** Foreground used when the composer shape leaves its text surface transparent. */
+	textColor?: (str: string) => string;
 	selectList: SelectListTheme;
 	symbols: SymbolTheme;
 	editorPaddingX?: number;
@@ -1271,13 +1274,16 @@ export class Editor implements Component, Focusable {
 					displayWidth = visibleWidth(displayText);
 				}
 			}
+			const renderedText = isFilledComposerStyle(style)
+				? displayText
+				: (this.#theme.textColor ?? PASSTHROUGH_COLOR)(displayText);
 
 			const linePad = padding(Math.max(0, lineContentWidth - displayWidth));
 
 			result.push(
 				...style.renderRow({
 					...chromeCtx,
-					text: displayText,
+					text: renderedText,
 					pad: linePad,
 					gutter: gutterText,
 					isLastRow: visibleIndex === visibleLayoutLines.length - 1,

package/src/components/image.ts

@@ -73,9 +73,9 @@ function nextImageIdSeed(): number {
  *
  * The budget keeps the most recent `cap` images live and demotes older ones to
  * their text fallback. Demotion needs a full redraw (so off-screen rows are
- * rewritten) plus an explicit graphics purge of the demoted ids — {@link Image}
- * reports display order via {@link observe}, and the TUI drives the purge +
- * redraw on the frame after a new image pushes the count past the cap.
+ * rewritten) plus an explicit graphics purge of the demoted ids. {@link Image}
+ * reports display order via {@link observe}; when that reveals a stricter split,
+ * the TUI repeats the pass before emitting its terminal frame.
  *
  * `cap <= 0` disables budgeting: every image stays a live graphic.
  */
@@ -87,6 +87,8 @@ export class ImageBudget {
 	#idToKey = new Map<number, string>();
 	/** Display-order image ids observed during the in-flight pass. */
 	#passIds: number[] = [];
+	/** Per-id suppression decision from the first observation in this pass. */
+	#passSuppression = new Map<number, boolean>();
 	/**
 	 * Suppress threshold reflected in the frame currently on the terminal: images
 	 * at display indices `[0, #onTerminal)` are shown as text there.
@@ -104,7 +106,7 @@ export class ImageBudget {
 	/** Image ids whose data is believed to be loaded in the terminal's store. */
 	#transmitted = new Set<number>();
 	/** Transmit sequences (full base64) to write once, before this frame's placements. */
-	#pendingTransmits: string[] = [];
+	#pendingTransmits = new Map<number, string>();
 	// True while the in-flight pass is a partial/throwaway pass (the
 	// non-multiplexer resize viewport fast path) that walks only the visible
 	// tail, bottom-up. Such a pass cannot derive display order from observe()
@@ -185,6 +187,7 @@ export class ImageBudget {
 	 */
 	beginPass(stable = false): void {
 		this.#passIds.length = 0;
+		this.#passSuppression.clear();
 		this.#stablePass = stable;
 		this.#applyingReset = !stable && this.#cap > 0 && this.#planned > this.#onTerminal;
 	}
@@ -199,47 +202,49 @@ export class ImageBudget {
 	 * (`#suppressedIds`) keyed by id — order- and partiality-independent.
 	 */
 	observe(imageId: number): boolean {
+		const existing = this.#passSuppression.get(imageId);
+		if (existing !== undefined) return existing;
 		if (this.#stablePass) {
 			const suppressed = this.#cap > 0 && this.#suppressedIds.has(imageId);
+			this.#passSuppression.set(imageId, suppressed);
 			if (suppressed) this.#forgetKeyForId(imageId);
 			return suppressed;
 		}
 		const index = this.#passIds.length;
 		this.#passIds.push(imageId);
 		const suppressed = this.#cap > 0 && index < this.#planned;
+		this.#passSuppression.set(imageId, suppressed);
 		if (suppressed) this.#forgetKeyForId(imageId);
 		return suppressed;
 	}
 
 	/**
-	 * End a render pass. Returns true when this frame must purge graphics and
-	 * fully repaint to apply a stricter budget; read the ids via
-	 * {@link takePurgeIds}.
+	 * End a render pass. Returns true when the pass discovered a stricter budget
+	 * and must be repeated before its terminal frame is emitted.
 	 */
 	endPass(): boolean {
 		const total = this.#passIds.length;
 		this.#lastTotal = total;
-		let reset = false;
 		if (this.#applyingReset) {
 			for (let i = this.#onTerminal; i < this.#planned && i < total; i++) {
 				const id = this.#passIds[i];
-				this.#purgeIds.push(id);
-				// d=I frees the data too, so the image must re-transmit if it returns.
+				// A transmit queued by a discarded discovery pass never reached
+				// the terminal, so cancel it instead of transmitting then purging.
+				if (!this.#pendingTransmits.delete(id)) this.#purgeIds.push(id);
 				this.#transmitted.delete(id);
 				this.#deletePlacementState(id);
 				this.#forgetKeyForId(id);
 			}
 			this.#onTerminal = this.#planned;
 			this.#applyingReset = false;
-			reset = true;
 		}
-		this.#reconcile(total);
+		const retry = this.#reconcile(total);
 		// Snapshot the committed display-order suppression by id: the prefix
 		// [0, #onTerminal) is what the terminal currently shows as text. Partial
 		// passes replay this per id (see #stablePass) instead of re-deriving it
 		// from a reversed, tail-only walk.
 		this.#suppressedIds = new Set(this.#passIds.slice(0, this.#onTerminal));
-		return reset;
+		return retry;
 	}
 
 	/** Image ids to delete from the terminal this frame; clears the pending set. */
@@ -256,7 +261,7 @@ export class ImageBudget {
 		const ids = [...this.#transmitted];
 		this.#transmitted.clear();
 		this.#purgeIds = [];
-		this.#pendingTransmits = [];
+		this.#pendingTransmits.clear();
 		this.#keyToId.clear();
 		this.#idToKey.clear();
 		this.#placementState.clear();
@@ -393,12 +398,12 @@ export class ImageBudget {
 	enqueueTransmit(imageId: number, sequence: string): void {
 		if (this.#transmitted.has(imageId)) return;
 		this.#transmitted.add(imageId);
-		this.#pendingTransmits.push(sequence);
+		this.#pendingTransmits.set(imageId, sequence);
 	}
 
 	/** Whether a frame has image data queued but not yet written to the terminal. */
 	hasPendingTransmits(): boolean {
-		return this.#pendingTransmits.length > 0;
+		return this.#pendingTransmits.size > 0;
 	}
 
 	/**
@@ -410,7 +415,7 @@ export class ImageBudget {
 	get quiescent(): boolean {
 		return (
 			this.#lastTotal === 0 &&
-			this.#pendingTransmits.length === 0 &&
+			this.#pendingTransmits.size === 0 &&
 			this.#purgeIds.length === 0 &&
 			this.#planned === this.#onTerminal
 		);
@@ -418,9 +423,9 @@ export class ImageBudget {
 
 	/** Transmit sequences to write before this frame's placements; clears the queue. */
 	takeTransmits(): readonly string[] {
-		if (this.#pendingTransmits.length === 0) return EMPTY_TRANSMITS;
-		const sequences = this.#pendingTransmits;
-		this.#pendingTransmits = [];
+		if (this.#pendingTransmits.size === 0) return EMPTY_TRANSMITS;
+		const sequences = [...this.#pendingTransmits.values()];
+		this.#pendingTransmits.clear();
 		return sequences;
 	}
 
@@ -433,9 +438,9 @@ export class ImageBudget {
 	 * re-emit together; keeps no base64 in budget state (the transmit-once design).
 	 */
 	forgetTransmitted(): void {
-		if (this.#transmitted.size === 0 && this.#pendingTransmits.length === 0) return;
+		if (this.#transmitted.size === 0 && this.#pendingTransmits.size === 0) return;
 		this.#transmitted.clear();
-		this.#pendingTransmits = [];
+		this.#pendingTransmits.clear();
 	}
 
 	#forgetKeyForId(id: number): void {
@@ -445,15 +450,16 @@ export class ImageBudget {
 		if (this.#keyToId.get(key) === id) this.#keyToId.delete(key);
 	}
 
-	#reconcile(total: number): void {
+	#reconcile(total: number): boolean {
 		const desired = this.#cap > 0 ? Math.max(0, total - this.#cap) : 0;
 		if (desired === this.#planned) {
 			// Budget relaxed without a stricter frame (cap raised or images
 			// removed): surviving graphics are untouched and re-exposed rows
 			// repaint normally, so just track the looser threshold.
 			if (this.#planned < this.#onTerminal) this.#onTerminal = this.#planned;
-			return;
+			return false;
 		}
+		const retry = desired > this.#onTerminal;
 		this.#planned = desired;
 		// More images must be demoted than the terminal shows: schedule the purge +
 		// full-redraw frame. Fewer: no ghosts to clear, so just catch the tracking
@@ -461,6 +467,7 @@ export class ImageBudget {
 		// render is needed to apply the new threshold.
 		if (desired <= this.#onTerminal) this.#onTerminal = desired;
 		this.#requestRender();
+		return retry;
 	}
 }