@oh-my-pi/pi-tui 15.10.8 → 15.10.10

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## [Unreleased]
 
+## [15.10.10] - 2026-06-09
+### Fixed
+
+- Fixed committed transcript rows silently vanishing when a component re-laid-out content the engine had already scrolled into native history — a TTSR stream rewind truncating a streamed block, or the image budget demoting a committed inline image to its one-line fallback, shifted every row below by the height delta and the engine kept committing from the stale index, skipping that many rows of everything after (missing interruption banners, half-cut images in scrollback). The engine now audits its committed prefix every ordinary frame: an in-place edit or restyle keeps its alignment (stale styling in history remains the accepted artifact), while any shift re-anchors the commit index at the first moved row and recommits from there — history keeps the stale copy and gains a fresh one. Duplication, never loss. The detector (`findCommittedPrefixResync`, exported for the stress harness's shadow ledger) samples the prefix tail SGR-stripped so theme restyles and single-row edits never trigger spurious recommits.
+- Fixed budget-demoted inline images shrinking their transcript block: the text fallback is now height-preserving once a graphic has rendered (reserved rows plus the fallback line), so demotion never shifts content below a committed image.
+- Fixed stale trailing cells bleeding into committed history on combining-heavy rows: the native width model can over-count Arabic/combining clusters, classifying a short-rendering row as full-width and skipping the trailing erase — the previous occupant's cells then scrolled into scrollback baked into the committed row. Non-ASCII row rewrites now erase the line before writing.
+
+### Changed
+
+- Rewrote the render core around an append-only native-scrollback contract. Committed rows are immutable: rows enter terminal history exactly once, in order, when the component-reported commit boundary (`NativeScrollbackLiveRegion`) marks them final, and the visible window repaints in place with relative moves. The engine no longer probes the terminal's scroll position or guesses whether a destructive rebuild is safe — the entire ED3-risk/defer/checkpoint machinery (viewport probes, eager streaming mode, dirty-scrollback reconciliation, deferred shrink/mutation intents, streaming high-water rebuilds, ConPTY-specific defer paths) is deleted. ED3 (`CSI 3 J`) now fires only on explicit user gestures: session replace, resize outside multiplexers, and `resetDisplay()`. This structurally removes the yank / flash / duplicated-rows / invisible-until-resize failure families tracked across #1610, #1635, #1651, #1682, #1719, #1746, #1799, #1823, #1962, #1974, #2000, #2011, #2154.
+- A frame that shrinks into its committed prefix re-anchors the visible window at the new tail and restarts commit bookkeeping; previously committed rows stay in history (history is never rewritten without a gesture).
+- Overlays now composite into the visible window slice only and freeze commits while visible, so overlay pixels can never enter native scrollback and closing an overlay no longer triggers a destructive history rebuild.
+- Inline-image budget demotion now deletes the demoted image's graphics by id and lets the window diff repaint the text fallback — no more mid-session destructive full replay when the image cap is exceeded.
+- The render-stress harness now validates the contract with a shadow commit ledger (an independent reimplementation of the ledger math fed only by observed frames and bytes), asserting scrollback equals the committed prefix row-for-row and that tape growth matches physical scroll exactly, across randomized op sequences, resizes, overlays, and multiplexer scenarios. The ghostty-web virtual terminal additionally survives libghostty-vt 0.4's WASM allocator traps via an event-log replay/compaction recovery, and strips non-spacing combining marks on input (a margin-aligned combining cluster deterministically corrupts that engine; mark placement through it was already unverifiable).
+
+### Removed
+
+- Removed the probe/defer API surface: `TUI.setEagerNativeScrollbackRebuild()`, `TUI.refreshNativeScrollbackIfDirty()`, `TUI.setClearOnShrink()`/`getClearOnShrink()`, `RenderRequestOptions.allowUnknownViewportMutation`, `NativeScrollbackRefreshOptions`, `Terminal.isNativeViewportAtBottom()`, `Terminal.hasEagerEraseScrollbackRisk()`, and the `eagerEraseScrollbackRisk`/`submitPinsViewportToTail` capability fields with their detectors.
+- Removed the `PI_TUI_ED3_SAFE`, `PI_CLEAR_ON_SHRINK`, and `PI_TUI_DEBUG` environment variables (the levers they tuned no longer exist; `PI_DEBUG_REDRAW` now logs the commit-ledger state per frame).
+
+## [15.10.9] - 2026-06-09
+
+### Added
+
+- Added a `wrapDescription` option to `SelectListLayoutOptions`. When enabled, long descriptions wrap onto continuation rows indented under the description column instead of being silently truncated. The slash-command/skill autocomplete picker now opts in so descriptions like the bundled skills' remain fully readable at normal terminal widths. `maxVisible` becomes the picker's visual row budget so the popup height stays bounded even when items wrap (a single 5-row description with `maxVisible=3` clips with the scrollbar carrying the offscreen tail). Navigation stays item-to-item, the narrow-width fallback (`width <= 40`) is unchanged, and the `ScrollView` scrollbar tracks visual rows so the thumb stays correct when items wrap unevenly. ([#2169](https://github.com/can1357/oh-my-pi/issues/2169))
+
+### Fixed
+
+- Fixed Ghostty's first inline image in a fresh TUI session sometimes rendering as an empty placeholder block by holding the initial Kitty graphics paint until the terminal startup settle window has passed. Direct Kitty placements also keep their zero-width reservation rows non-plain so image-only transcript blocks do not collapse when blank-edge trimming runs.
+
 ## [15.10.8] - 2026-06-09
 
 ### Fixed
@@ -1218,4 +1248,4 @@ Initial release under @oh-my-pi scope. See previous releases at [badlogic/pi-mon
 
 ### Fixed
 
-- **Readline-style Ctrl+W**: Now skips trailing whitespace before deleting the preceding word, matching standard readline behavior. ([#306](https://github.com/badlogic/pi-mono/pull/306) by [@kim0](https://github.com/kim0))
+- **Readline-style Ctrl+W**: Now skips trailing whitespace before deleting the preceding word, matching standard readline behavior. ([#306](https://github.com/badlogic/pi-mono/pull/306) by [@kim0](https://github.com/kim0))

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

@@ -73,6 +73,8 @@ export declare class ImageBudget {
      * repeated call (e.g. a width-change re-render) never re-sends the data.
      */
     enqueueTransmit(imageId: number, sequence: string): void;
+    /** Whether a frame has image data queued but not yet written to the terminal. */
+    hasPendingTransmits(): boolean;
     /** Transmit sequences to write before this frame's placements; clears the queue. */
     takeTransmits(): readonly string[];
 }

package/dist/types/components/select-list.d.ts

@@ -28,6 +28,14 @@ export interface SelectListLayoutOptions {
     truncatePrimary?: (context: SelectListTruncatePrimaryContext) => string;
     /** Enable type-to-filter search when the item count exceeds maxVisible. Defaults to true. */
     overflowSearch?: boolean;
+    /**
+     * Wrap long descriptions onto continuation rows indented under the
+     * description column instead of truncating. Defaults to false so existing
+     * single-line consumers are unaffected. Navigation remains item-to-item;
+     * the scrollbar tracks visual rows so the thumb stays correct when items
+     * wrap unevenly.
+     */
+    wrapDescription?: boolean;
 }
 export declare class SelectList implements Component {
     #private;

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

@@ -16,22 +16,13 @@ export declare class TerminalInfo {
     readonly trueColor: boolean;
     readonly hyperlinks: boolean;
     readonly notifyProtocol: NotifyProtocol;
-    readonly eagerEraseScrollbackRisk: boolean;
     readonly deccara: boolean;
     readonly supportsScreenToScrollback: boolean;
     /** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
     readonly textSizing: boolean;
-    constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol, eagerEraseScrollbackRisk?: boolean, deccara?: boolean, supportsScreenToScrollback?: boolean, 
+    constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol, deccara?: boolean, supportsScreenToScrollback?: boolean, 
     /** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
     textSizing?: boolean);
-    /**
-     * Whether a prompt-submit keystroke scrolls this host to its tail, so the
-     * native-scrollback reconciliation checkpoint may ED3-rebuild even when the
-     * viewport position is unprobeable. Assigned by the TERMINAL builder from
-     * {@link detectSubmitPinsViewportToTail}; readonly but tests opt in via the
-     * {@link setTerminalSubmitPinsViewportToTail} mutable-cast setter.
-     */
-    readonly submitPinsViewportToTail: boolean;
     /**
      * Mutable clone for the {@link TERMINAL} singleton: copies every field and
      * keeps the prototype methods, so the builder and runtime setters flip
@@ -50,36 +41,6 @@ export declare function isNotificationSuppressed(): boolean;
  * Windows Terminal introduced SIXEL support in preview 1.22.
  */
 export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
-/**
- * Whether live-frame native scrollback rebuilds are unsafe when the terminal
- * viewport position is unobservable.
- *
- * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). Many
- * terminals either clamp a scrolled reader back to the active tail or erase host
- * scrollback when ED3 lands. The important property is not the brand name — it
- * is that an unknown viewport position cannot be proven safe. Environment
- * markers are therefore only used to prove *risk* or a strongly-known profile;
- * unknown POSIX/remote/multiplexer shapes default to risky for passive renders.
- *
- * Native win32 is excluded here because the renderer has dedicated ConPTY
- * deferral paths; a `WT_SESSION` sighting on POSIX means Windows Terminal is the
- * outer host fronting WSL, where the same ED3 yank applies. See #1610/#1682/#1799.
- */
-export declare function detectTerminalEagerEraseScrollbackRisk(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
-/**
- * Whether a prompt-submit keystroke scrolls this terminal to its tail, making the
- * native-scrollback reconciliation checkpoint (`refreshNativeScrollbackIfDirty`)
- * safe to ED3-rebuild even when the viewport position cannot be probed.
- *
- * True only for recognized genuine *local* terminals where typing into the prompt
- * brings the host viewport to the bottom. False — the checkpoint keeps deferring
- * until a positive at-tail probe — for hosts whose scrollback a keystroke does not
- * move: Windows consoles/ConPTY, Windows Terminal (incl. WSL), SSH, multiplexers,
- * and unrecognized profiles. This is the per-terminal counterpart to the blanket
- * block from #1610/#1682/#1746: those hosts genuinely cannot treat a submit as
- * proof of at-tail, but genuine local terminals can.
- */
-export declare function detectSubmitPinsViewportToTail(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 /**
  * Resolve an explicit user override for DEC 2026 synchronized output. Returns
  * `false` for an opt-out, `true` for a force-on, or `null` when the user has
@@ -134,11 +95,9 @@ export declare const TERMINAL_ID: TerminalId;
 export interface RuntimeTerminal extends TerminalInfo {
     imageProtocol: ImageProtocol | null;
     hyperlinks: boolean;
-    eagerEraseScrollbackRisk: boolean;
     deccara: boolean;
     supportsScreenToScrollback: boolean;
     textSizing: boolean;
-    submitPinsViewportToTail: boolean;
 }
 export declare const TERMINAL: RuntimeTerminal;
 /**
@@ -153,8 +112,6 @@ export declare function setTerminalImageProtocol(imageProtocol: ImageProtocol |
 export declare function setTerminalDeccara(enabled: boolean): void;
 /** Override screen-to-scrollback clear support for targeted renderer tests. */
 export declare function setTerminalScreenToScrollback(enabled: boolean): void;
-/** Override submit-pins-viewport-to-tail for checkpoint reconciliation tests. */
-export declare function setTerminalSubmitPinsViewportToTail(enabled: boolean): void;
 /**
  * Enable/disable OSC 66 text-sizing at runtime. The coding-agent calls this from
  * the `tui.textSizing` setting (gated on the terminal's static `textSizing`

package/dist/types/terminal.d.ts

@@ -48,42 +48,6 @@ export interface Terminal {
     clearScreen(): void;
     setTitle(title: string): void;
     setProgress(active: boolean): void;
-    /**
-     * Returns whether the native terminal viewport is at the scrollback tail when
-     * the host exposes that state. `undefined` means the terminal cannot report it.
-     *
-     * `ProcessTerminal` deliberately does not implement this — no real terminal
-     * can answer it truthfully:
-     *
-     * - POSIX terminals expose no scrollback-position API at all.
-     * - Every modern Windows terminal host (Windows Terminal, VS Code, Tabby,
-     *   Hyper, Alacritty, WezTerm, JetBrains, …) fronts console apps through
-     *   ConPTY, where kernel32's `GetConsoleScreenBufferInfo` describes the
-     *   pseudo-console buffer. That buffer is pinned to the visible grid —
-     *   scrollback lives in the host UI, invisible to console APIs
-     *   (microsoft/terminal#10191) — so a probe reads "at bottom" no matter
-     *   where the user scrolled. Trusting it let streaming-time rebuilds emit
-     *   `\x1b[3J` and yank scrolled readers: #1635 (Windows Terminal), #1746
-     *   (Tabby and other ConPTY hosts). No env var distinguishes these hosts
-     *   (Tabby sets none), so trust cannot be conditional on the environment.
-     * - Legacy conhost (the only non-ConPTY host) keeps a real scrollback
-     *   buffer, but its window follows the output cursor: a probe comparing
-     *   `srWindow.Bottom` against `dwSize.Y - 1` reads "scrolled up" for a user
-     *   following live output until all ~9001 buffer rows fill, permanently
-     *   blocking checkpoint scrollback reconciliation.
-     *
-     * The renderer treats a missing implementation / `undefined` as "unknown":
-     * live mutations defer destructive rebuilds and reconcile native scrollback
-     * at explicit checkpoints (prompt submit), where the user's keystroke has
-     * already pinned the host viewport to the bottom. Only test terminals
-     * (xterm.js-backed) implement this with a real answer.
-     */
-    isNativeViewportAtBottom?(): boolean | undefined;
-    /**
-     * Override the global terminal-profile ED3 risk decision for custom/test
-     * terminals. `undefined` falls back to the resolved `TERMINAL` profile.
-     */
-    hasEagerEraseScrollbackRisk?(): boolean | undefined;
     /**
      * Register a callback for terminal appearance (dark/light) changes.
      * Detection uses OSC 11 background color query with Mode 2031 as a change trigger.

package/dist/types/tui.d.ts

@@ -55,22 +55,22 @@ export interface Component {
     dispose?(): void;
 }
 /**
- * Optional component seam for native-scrollback pinning. A component that
- * renders a stable prefix followed by a live/transient suffix reports the local
- * line index where that suffix begins after each render. TUI treats that suffix
- * — and every root child rendered below it — as not yet safe to commit to native
- * scrollback on ED3-risk terminals whose viewport position is unobservable.
+ * Component seam for append-only native-scrollback commits. A component that
+ * renders a finalized prefix followed by a live/mutating suffix reports the
+ * local line index where that suffix begins after each render. The engine
+ * commits rows to native scrollback only up to that boundary; everything
+ * below repaints in place inside the visible window and never enters history
+ * until it finalizes.
  *
  * `getNativeScrollbackCommitSafeEnd` optionally reports a *deeper* boundary
- * inside that live suffix: the line index up to which the live region is
- * append-only (its earlier rows never re-layout, only new rows append at the
- * bottom — a streaming assistant message). Rows in `[liveRegionStart,
- * commitSafeEnd)` that scroll above the viewport are safe to commit to native
- * scrollback even though they are technically live, because they will never
- * change. Without this, a single live block that alone overflows the viewport
- * loses its scrolled-off head (committed nowhere, repainted nowhere). Volatile
- * live blocks (tool previews that collapse) omit it, so their mutable rows stay
- * deferred. Defaults to `liveRegionStart` when absent.
+ * inside the live suffix: the line index up to which the live region is
+ * append-only (earlier rows never re-layout — a streaming assistant message).
+ * Rows in `[liveRegionStart, commitSafeEnd)` may commit even though they are
+ * technically live, because they will never change. Without it, a single live
+ * block that alone overflows the window would hold its scrolled-off head out
+ * of history until it finalizes. Volatile live blocks (tool previews that
+ * collapse) omit it. Defaults to `liveRegionStart` when absent; a root that
+ * reports no seam at all commits everything that scrolls (shell semantics).
  */
 export interface NativeScrollbackLiveRegion {
     getNativeScrollbackLiveRegionStart(): number | undefined;
@@ -97,21 +97,6 @@ export interface Focusable {
 export interface RenderRequestOptions {
     /** Clear terminal scrollback for intentional transcript replacement. */
     clearScrollback?: boolean;
-    /**
-     * Allow a transient live-viewport repaint when the terminal cannot report
-     * whether its native viewport is at the tail.
-     *
-     * This is **not** a settled transcript commit and must not be used for tool
-     * completion, session replay, or other background/offscreen rewrites. On
-     * ED3-risk terminals it may deliberately choose a viewport repaint/deferred
-     * shrink without clearing native scrollback so autocomplete, IME, and focused
-     * editor chrome stay responsive without yanking a scrolled reader.
-     */
-    allowUnknownViewportMutation?: boolean;
-}
-/** Options for deferred native scrollback rebuild checkpoints. Reserved for API stability. */
-export interface NativeScrollbackRefreshOptions {
-    allowUnknownViewport?: boolean;
 }
 /** Type guard to check if a component implements Focusable */
 export declare function isFocusable(component: Component | null): component is Component & Focusable;
@@ -205,6 +190,26 @@ export declare class Container implements Component {
     dispose(): void;
     render(width: number): string[];
 }
+/**
+ * Decide whether `frame` still aligns with the committed prefix, and where to
+ * re-anchor the commit index when it does not. Returns the resync row index,
+ * or -1 when no resync is needed.
+ *
+ * The detector exploits the asymmetry between the two mutation classes: an
+ * in-place edit or restyle of committed rows disturbs only the touched rows
+ * (alignment below them is intact — the stale copy in history is the
+ * long-accepted artifact), while any insertion or deletion shifts EVERY row
+ * below it, including the rows just above the commit boundary. So the prefix
+ * *tail* is sampled (up to 8 non-blank rows within the last 24, compared
+ * SGR-stripped so theme changes stay quiet, tolerating one mismatch for a
+ * legitimate single-row edit): aligned ⇒ no resync; misaligned ⇒ resync at
+ * the first non-equivalent row, recommitting from there — duplication, never
+ * loss. Highly repetitive tails (identical filler rows) can mask a shift, in
+ * which case the skipped rows are content-identical to the committed ones —
+ * observationally harmless. Exported for the render-stress harness, whose
+ * shadow commit ledger must mirror the engine's law exactly.
+ */
+export declare function findCommittedPrefixResync(frame: readonly string[], prefix: readonly string[]): number;
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
@@ -232,13 +237,6 @@ export declare class TUI extends Container {
     setMaxInlineImages(cap: number): void;
     getShowHardwareCursor(): boolean;
     setShowHardwareCursor(enabled: boolean): void;
-    getClearOnShrink(): boolean;
-    /**
-     * Set whether to trigger full re-render when content shrinks.
-     * When true (default), empty rows are cleared when content shrinks.
-     * When false, empty rows remain (reduces redraws on slower terminals).
-     */
-    setClearOnShrink(enabled: boolean): void;
     /**
      * Whether DEC 2026 synchronized-output wrappers are currently emitted around
      * paints. Starts from conservative terminal/env detection and is reconciled at
@@ -246,30 +244,6 @@ export declare class TUI extends Container {
      * positive report, disabled on a negative one.
      */
     get synchronizedOutput(): boolean;
-    /**
-     * When enabled, live render frames rebuild native scrollback on offscreen and
-     * structural changes even when the viewport position is unobservable (POSIX,
-     * where `isNativeViewportAtBottom()` is `undefined`), instead of deferring to a
-     * non-destructive repaint. This trades the anti-yank guarantee for a clean,
-     * duplicate-free history and is meant for windows where output above the fold
-     * is actively re-rendering — e.g. a tool whose result is still streaming and
-     * re-laying-out rows that have already scrolled into history. A terminal that
-     * reports a *known*-scrolled viewport still defers, as does native Windows
-     * (the viewport is never observable there and ConPTY hosts erase host
-     * scrollback on ED3 — #1635/#1746); only the unknown POSIX case is forced to
-     * rebuild. POSIX hosts known to disturb scrolled readers on xterm ED3
-     * (`CSI 3 J`, erase saved lines) also defer the eager opt-in; checkpoint
-     * rebuilds are unaffected.
-     *
-     * Disabling stays active through one already-requested frame: the event batch
-     * that ends a foreground stream both removes its UI rows (loader/status
-     * teardown — a shrink) and clears this flag before the throttled render timer
-     * fires. If the flag dropped immediately, that teardown frame would hit the
-     * ED3-risk idle deferral and freeze on screen (stale spinner) until the next
-     * keystroke. When no render is pending, disable immediately so a later
-     * unrelated content mutation does not inherit foreground-stream privileges.
-     */
-    setEagerNativeScrollbackRebuild(enabled: boolean): void;
     setFocus(component: Component | null): void;
     /** Component currently receiving keyboard input, if any. */
     getFocused(): Component | null;
@@ -288,12 +262,6 @@ export declare class TUI extends Container {
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
     stop(): void;
-    /**
-     * Rebuild native terminal scrollback if live rendering deferred a history rewrite.
-     * Callers should only invoke this at checkpoints where the user is expected to be
-     * at the terminal bottom, such as after submitting a new prompt.
-     */
-    refreshNativeScrollbackIfDirty(_options?: NativeScrollbackRefreshOptions): boolean;
     /**
      * Force an immediate full replay of the current frame, including native
      * scrollback. This is the keyboard-accessible equivalent of the resize reset:

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.10.8",
+	"version": "15.10.10",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "15.10.8",
-		"@oh-my-pi/pi-utils": "15.10.8",
+		"@oh-my-pi/pi-natives": "15.10.10",
+		"@oh-my-pi/pi-utils": "15.10.10",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.4"
 	},

package/src/components/editor.ts

@@ -27,6 +27,7 @@ const SLASH_COMMAND_SELECT_LIST_LAYOUT: SelectListLayoutOptions = {
 	minPrimaryColumnWidth: 12,
 	maxPrimaryColumnWidth: 32,
 	overflowSearch: false,
+	wrapDescription: true,
 };
 
 function sanitizeLoadedText(text: string): string {

package/src/components/image.ts

@@ -27,6 +27,9 @@ export interface ImageOptions {
 
 const EMPTY_IDS: readonly number[] = [];
 const EMPTY_TRANSMITS: readonly string[] = [];
+// Direct placements reserve height with leading zero-width rows. Keep them
+// non-plain so transcript blank-edge trimming does not collapse image-only blocks.
+const RESERVED_IMAGE_ROW = "\x1b[0m";
 
 /** Default count of inline images kept as live graphics before older ones fall back to text. */
 export const DEFAULT_MAX_INLINE_IMAGES = 8;
@@ -188,6 +191,11 @@ export class ImageBudget {
 		this.#pendingTransmits.push(sequence);
 	}
 
+	/** Whether a frame has image data queued but not yet written to the terminal. */
+	hasPendingTransmits(): boolean {
+		return this.#pendingTransmits.length > 0;
+	}
+
 	/** Transmit sequences to write before this frame's placements; clears the queue. */
 	takeTransmits(): readonly string[] {
 		if (this.#pendingTransmits.length === 0) return EMPTY_TRANSMITS;
@@ -232,6 +240,10 @@ export class Image implements Component {
 	#cachedLines?: string[];
 	#cachedWidth?: number;
 	#cachedSuppressed = false;
+	// Tallest graphic placement this image has rendered. The text fallback
+	// pads itself to this height so a budget demotion never shrinks the block
+	// (its rows may already be committed to native scrollback).
+	#renderedGraphicRows = 0;
 
 	constructor(
 		base64Data: string,
@@ -296,17 +308,16 @@ export class Image implements Component {
 				// moves the cursor back up, then emits the image sequence.
 				lines = [];
 				for (let i = 0; i < result.rows - 1; i++) {
-					lines.push("");
+					lines.push(RESERVED_IMAGE_ROW);
 				}
 				const moveUp = result.rows > 1 ? `\x1b[${result.rows - 1}A` : "";
 				lines.push(moveUp + (result.sequence ?? ""));
 			} else {
-				lines = [
-					this.#theme.fallbackColor(imageFallback(this.#mimeType, this.#dimensions, this.#options.filename)),
-				];
+				lines = this.#fallbackLines();
 			}
+			this.#renderedGraphicRows = Math.max(this.#renderedGraphicRows, lines.length);
 		} else {
-			lines = [this.#theme.fallbackColor(imageFallback(this.#mimeType, this.#dimensions, this.#options.filename))];
+			lines = this.#fallbackLines();
 		}
 
 		this.#cachedLines = lines;
@@ -315,4 +326,25 @@ export class Image implements Component {
 
 		return lines;
 	}
+
+	/**
+	 * Text fallback, height-preserving once a graphic has rendered: a demoted
+	 * image must keep occupying the rows its placement used, because those
+	 * rows may already be committed to native scrollback — shrinking the block
+	 * would shift everything below it and force the renderer's commit-resync
+	 * (stale band + recommit). Reserved rows stay non-plain so blank-edge
+	 * trimming cannot collapse the block either.
+	 */
+	#fallbackLines(): string[] {
+		const fallback = this.#theme.fallbackColor(
+			imageFallback(this.#mimeType, this.#dimensions, this.#options.filename),
+		);
+		if (this.#renderedGraphicRows <= 1) return [fallback];
+		const lines: string[] = [];
+		for (let i = 0; i < this.#renderedGraphicRows - 1; i++) {
+			lines.push(RESERVED_IMAGE_ROW);
+		}
+		lines.push(fallback);
+		return lines;
+	}
 }