@oh-my-pi/pi-tui 17.2.11 → 17.2.13

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [17.2.13] - 2026-08-11
+
+### Fixed
+
+- Fixed inline images rendering permanently cropped on Kitty direct-placement terminals (WezTerm, Warp) when an image block straddled the viewport top during streaming: placements are now clipped to the visible slice at write time, and a placement id whose cells reached native scrollback is never re-used ([#8070](https://github.com/can1357/oh-my-pi/pull/8070) by [@voonfoo](https://github.com/voonfoo))
+
+## [17.2.12] - 2026-08-08
+
+### Fixed
+
+- Fixed slow Loader paints exceeding their cost-aware CPU duty cycle on WSL/ConPTY when a 200 ms backpressure cap was shorter than the proportional delay ([#8012](https://github.com/can1357/oh-my-pi/issues/8012)).
+- Fixed display-math (`$$…$$`) fractions rendering as fragmented text when the numerator and denominator are written on separate source lines: `latexToBlock` treated the top-level newline between `\frac{num}` and `{den}` as a row break, severing `\frac` from its denominator. Such argument-continuation newlines are now preserved so the fraction stays stacked ([#7996](https://github.com/can1357/oh-my-pi/issues/7996)).
+
 ## [17.2.11] - 2026-08-07
 
 ### Fixed

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

@@ -78,6 +78,53 @@ export declare class ImageBudget {
     takeAllTransmittedIds(): readonly number[];
     /** Whether `imageId`'s data still needs to be transmitted to the terminal. */
     shouldTransmit(imageId: number): boolean;
+    /**
+     * Record a direct-placement image's source pixel geometry so the renderer
+     * can clip its placement to the visible slice at write time; cleared when
+     * the image is purged from the terminal store.
+     */
+    registerPlacementGeometry(imageId: number, widthPx: number, heightPx: number): void;
+    /**
+     * Record this frame's native-scrollback commit target (the frame-row count
+     * that is committed once the frame's writes land). Called once per rendered
+     * frame — including frames that emit no placements — so an epoch whose rows
+     * commit while its line is never rewritten is still flagged before the next
+     * re-emission.
+     */
+    observeCommitWatermark(committedTo: number): void;
+    /**
+     * Resolve the placement id and geometry for a direct-placement emit whose
+     * topmost attached cell sits at `attachTopFrameRow` — the first frame row
+     * the placement covers, i.e. the block's first *visible* row, not its
+     * origin (-1 when the writer has no frame-space position: alt-screen,
+     * resize, ConPTY-truncated replays). `committedTo` is this frame's commit
+     * target in the same frame-row space (-1 when unknown).
+     *
+     * Invariant: a placement id may be re-used (Kitty replace strips that id's
+     * cells everywhere, scrollback included) only while none of the cells it
+     * attached have entered native scrollback. The epoch — the `p=` id —
+     * advances exactly when the archived flag says otherwise; rewrites with no
+     * commit progression keep replacing the same id in place.
+     */
+    resolvePlacementEmit(imageId: number, attachTopFrameRow: number, committedTo: number): {
+        placementId: number;
+        widthPx: number;
+        heightPx: number;
+    } | null;
+    /**
+     * Restart every placement epoch after a destructive history clear (`CSI 3 J`
+     * full paint). The clear destroys all placement cells — scrollback rows are
+     * gone and the replay rewrites the viewport — so no archive remains to
+     * protect. Reverting to epoch 1 lets the replay's placements replace the
+     * terminal's stale registry entries; the returned list names every image
+     * and the highest epoch it reached so the caller can delete all of its
+     * registry entries explicitly (`d=i` keeps the transmitted data) — an image
+     * absent from the replay never re-places, so even its epoch-1 entry must go.
+     */
+    resetPlacementEpochs(): ReadonlyArray<{
+        imageId: number;
+        lastEpoch: number;
+    }>;
     /**
      * Queue a one-time transmit for `imageId`. No-op if already transmitted, so a
      * repeated call (e.g. a width-change re-render) never re-sends the data.

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

@@ -235,6 +235,38 @@ export declare function encodeKittyPlacement(options: {
     columns?: number;
     rows?: number;
 }): string;
+export interface ParsedKittyPlacementLine {
+    imageId: number;
+    placementId: number | undefined;
+    columns: number;
+    rows: number;
+}
+/**
+ * Parse a frame line that consists solely of a Kitty direct placement (the
+ * last line of an {@link Image} block). Returns null for anything else —
+ * placeholder grids, tmux-wrapped placements, sixel/iTerm2 payloads — so
+ * callers fall back to writing the line verbatim.
+ */
+export declare function parseKittyDirectPlacementLine(line: string): ParsedKittyPlacementLine | null;
+/**
+ * Rebuild an {@link Image} direct-placement line for the viewport row it is
+ * written at. The component-rendered line encodes `CUU(rows-1)`, which clamps
+ * at the viewport top once the block's leading rows have scrolled out — the
+ * placement then re-anchors the full image shifted down over foreign rows.
+ * Anchor at the block's first *visible* row instead, clipping the source
+ * rectangle (`y=`/`h=`, image pixels) to the visible bottom slice.
+ */
+export declare function encodeKittyPlacementLine(options: {
+    imageId: number;
+    placementId: number;
+    columns: number;
+    /** Total cell rows of the image block. */
+    rows: number;
+    /** Viewport row the block's last line is being written at. */
+    screenRow: number;
+    /** Source image height in pixels, for the clipped source rectangle. */
+    imageHeightPx: number;
+}): string;
 /**
  * Kitty graphics delete command for a single image id. Uses `d=I` (capital)
  * which removes the image and every one of its placements — on screen *and* in
@@ -243,6 +275,13 @@ export declare function encodeKittyPlacement(options: {
  * this is the only way to actually purge a placed image.
  */
 export declare function encodeKittyDeleteImage(imageId: number): string;
+/**
+ * Delete a single placement of an image (`d=i`, lowercase): removes its cells
+ * and registry entry but keeps the transmitted data, so a later `a=p` under a
+ * fresh placement id needs no retransmit. Used to clear stale placement-epoch
+ * entries after a destructive history clear.
+ */
+export declare function encodeKittyDeletePlacement(imageId: number, placementId: number): string;
 export declare function encodeITerm2(base64Data: string, options?: {
     width?: number | string;
     height?: number | string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "17.2.11",
+	"version": "17.2.13",
 	"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": "17.2.11",
-		"@oh-my-pi/pi-utils": "17.2.11"
+		"@oh-my-pi/pi-natives": "17.2.13",
+		"@oh-my-pi/pi-utils": "17.2.13"
 	},
 	"devDependencies": {
 		"ghostty-web": "^0.4.0"

package/src/components/image.ts

@@ -29,6 +29,7 @@ export interface ImageOptions {
 
 const EMPTY_IDS: readonly number[] = [];
 const EMPTY_TRANSMITS: readonly string[] = [];
+const EMPTY_STALE_EPOCHS: ReadonlyArray<{ imageId: number; lastEpoch: number }> = [];
 const SAVE_CURSOR = "\x1b7";
 const RESTORE_CURSOR = "\x1b8";
 // Direct placements reserve height with leading zero-width rows. Keep them
@@ -38,6 +39,24 @@ 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;
 
+/** Per-image direct-placement emit state tracked by {@link ImageBudget}. */
+interface PlacementEmitState {
+	widthPx: number;
+	heightPx: number;
+	/** Current placement-id (`p=`) generation. */
+	epoch: number;
+	/** First frame row the current epoch's last emit attached cells to. */
+	lastAttachTopFrameRow: number | undefined;
+	/**
+	 * Whether any cell attached by the current epoch's last emit has entered
+	 * native scrollback. Set by {@link ImageBudget.observeCommitWatermark}
+	 * comparing each frame's raw commit target against the attach top —
+	 * era-local comparisons, so a divergence recommit that rewinds and
+	 * re-advances the ledger is detected the moment it re-crosses the attach
+	 * top, and a stale pre-rewind peak can never re-trigger.
+	 */
+	cellsArchived: boolean;
+}
 let nextImageBudgetSeed = Math.floor(Math.random() * 0xffffff);
 function nextImageIdSeed(): number {
 	nextImageBudgetSeed = (nextImageBudgetSeed + 0x10000) & 0xffffff;
@@ -96,6 +115,22 @@ export class ImageBudget {
 	// id so a partial pass reproduces the on-screen live/text split without a
 	// full, correctly-ordered walk.
 	#suppressedIds = new Set<number>();
+	/**
+	 * Per-image direct-placement emit state: source pixel geometry for the
+	 * renderer's clipped source rectangle, plus the placement-id epoch (see
+	 * {@link resolvePlacementEmit}). Entries deliberately live as long as the
+	 * terminal's own placement registry for the image — they are the ledger the
+	 * destructive-clear sweep uses to delete every registry entry an image ever
+	 * placed — and die with it on demotion purge (`d=I`) or full cleanup.
+	 */
+	#placementState = new Map<number, PlacementEmitState>();
+	/**
+	 * States with an un-archived live attach top — the only ones a frame's
+	 * commit watermark can affect. {@link observeCommitWatermark} runs every
+	 * rendered frame, so it scans this set (bounded by concurrently live
+	 * placements) instead of every image ever registered.
+	 */
+	#watchedPlacements = new Set<PlacementEmitState>();
 
 	constructor(cap: number = DEFAULT_MAX_INLINE_IMAGES, requestRender: () => void = () => {}) {
 		this.#cap = normalizeCap(cap);
@@ -191,6 +226,7 @@ export class ImageBudget {
 				this.#purgeIds.push(id);
 				// d=I frees the data too, so the image must re-transmit if it returns.
 				this.#transmitted.delete(id);
+				this.#deletePlacementState(id);
 				this.#forgetKeyForId(id);
 			}
 			this.#onTerminal = this.#planned;
@@ -223,6 +259,8 @@ export class ImageBudget {
 		this.#pendingTransmits = [];
 		this.#keyToId.clear();
 		this.#idToKey.clear();
+		this.#placementState.clear();
+		this.#watchedPlacements.clear();
 		return ids;
 	}
 
@@ -231,6 +269,116 @@ export class ImageBudget {
 		return !this.#transmitted.has(imageId);
 	}
 
+	/**
+	 * Record a direct-placement image's source pixel geometry so the renderer
+	 * can clip its placement to the visible slice at write time; cleared when
+	 * the image is purged from the terminal store.
+	 */
+	registerPlacementGeometry(imageId: number, widthPx: number, heightPx: number): void {
+		const state = this.#placementState.get(imageId);
+		if (state) {
+			state.widthPx = widthPx;
+			state.heightPx = heightPx;
+			return;
+		}
+		this.#placementState.set(imageId, {
+			widthPx,
+			heightPx,
+			epoch: 1,
+			lastAttachTopFrameRow: undefined,
+			cellsArchived: false,
+		});
+	}
+
+	/**
+	 * Record this frame's native-scrollback commit target (the frame-row count
+	 * that is committed once the frame's writes land). Called once per rendered
+	 * frame — including frames that emit no placements — so an epoch whose rows
+	 * commit while its line is never rewritten is still flagged before the next
+	 * re-emission.
+	 */
+	observeCommitWatermark(committedTo: number): void {
+		if (committedTo < 0 || this.#watchedPlacements.size === 0) return;
+		for (const state of this.#watchedPlacements) {
+			if (state.lastAttachTopFrameRow !== undefined && committedTo > state.lastAttachTopFrameRow) {
+				// Latched: the flag only clears when the next emit consumes it,
+				// so the state needs no further per-frame scans until then.
+				state.cellsArchived = true;
+				this.#watchedPlacements.delete(state);
+			}
+		}
+	}
+
+	/**
+	 * Resolve the placement id and geometry for a direct-placement emit whose
+	 * topmost attached cell sits at `attachTopFrameRow` — the first frame row
+	 * the placement covers, i.e. the block's first *visible* row, not its
+	 * origin (-1 when the writer has no frame-space position: alt-screen,
+	 * resize, ConPTY-truncated replays). `committedTo` is this frame's commit
+	 * target in the same frame-row space (-1 when unknown).
+	 *
+	 * Invariant: a placement id may be re-used (Kitty replace strips that id's
+	 * cells everywhere, scrollback included) only while none of the cells it
+	 * attached have entered native scrollback. The epoch — the `p=` id —
+	 * advances exactly when the archived flag says otherwise; rewrites with no
+	 * commit progression keep replacing the same id in place.
+	 */
+	resolvePlacementEmit(
+		imageId: number,
+		attachTopFrameRow: number,
+		committedTo: number,
+	): { placementId: number; widthPx: number; heightPx: number } | null {
+		const state = this.#placementState.get(imageId);
+		if (!state) return null;
+		// Frames that commit as they write (seam/full-paint chunk passes) pass
+		// their own commit target; fold it in before deciding, so a commit that
+		// lands in the same frame as the re-emission still advances the epoch.
+		if (committedTo >= 0 && state.lastAttachTopFrameRow !== undefined && committedTo > state.lastAttachTopFrameRow) {
+			state.cellsArchived = true;
+			this.#watchedPlacements.delete(state);
+		}
+		if (state.cellsArchived) {
+			state.epoch += 1;
+			state.cellsArchived = false;
+			state.lastAttachTopFrameRow = undefined;
+		}
+		if (attachTopFrameRow >= 0) {
+			state.lastAttachTopFrameRow = attachTopFrameRow;
+			this.#watchedPlacements.add(state);
+		}
+		return { placementId: state.epoch, widthPx: state.widthPx, heightPx: state.heightPx };
+	}
+
+	/**
+	 * Restart every placement epoch after a destructive history clear (`CSI 3 J`
+	 * full paint). The clear destroys all placement cells — scrollback rows are
+	 * gone and the replay rewrites the viewport — so no archive remains to
+	 * protect. Reverting to epoch 1 lets the replay's placements replace the
+	 * terminal's stale registry entries; the returned list names every image
+	 * and the highest epoch it reached so the caller can delete all of its
+	 * registry entries explicitly (`d=i` keeps the transmitted data) — an image
+	 * absent from the replay never re-places, so even its epoch-1 entry must go.
+	 */
+	resetPlacementEpochs(): ReadonlyArray<{ imageId: number; lastEpoch: number }> {
+		let stale: Array<{ imageId: number; lastEpoch: number }> | undefined;
+		for (const [imageId, state] of this.#placementState) {
+			stale ??= [];
+			stale.push({ imageId, lastEpoch: state.epoch });
+			state.epoch = 1;
+			state.lastAttachTopFrameRow = undefined;
+			state.cellsArchived = false;
+		}
+		this.#watchedPlacements.clear();
+		return stale ?? EMPTY_STALE_EPOCHS;
+	}
+
+	#deletePlacementState(imageId: number): void {
+		const state = this.#placementState.get(imageId);
+		if (!state) return;
+		this.#watchedPlacements.delete(state);
+		this.#placementState.delete(imageId);
+	}
+
 	/**
 	 * Queue a one-time transmit for `imageId`. No-op if already transmitted, so a
 	 * repeated call (e.g. a width-change re-render) never re-sends the data.
@@ -407,9 +555,17 @@ export class Image implements Component {
 				// Direct placement: return `rows` lines so TUI accounts for image
 				// height. First (rows-1) lines are empty (TUI clears them); the last
 				// saves the final-row cursor, moves up to the image origin, emits the
-				// image sequence, then restores the final-row cursor. Save/restore is
-				// required because CUU clamps at the viewport top when leading rows are
-				// clipped away.
+				// image sequence, then restores the final-row cursor. When the block
+				// straddles the viewport top, the renderer rewrites this line to the
+				// visible slice (encodeKittyPlacementLine) from the geometry
+				// registered below.
+				if (this.#imageId != null && this.#budget !== undefined) {
+					this.#budget.registerPlacementGeometry(
+						this.#imageId,
+						this.#dimensions.widthPx,
+						this.#dimensions.heightPx,
+					);
+				}
 				lines = [];
 				for (let i = 0; i < result.rows - 1; i++) {
 					lines.push(RESERVED_IMAGE_ROW);

package/src/components/loader.ts

@@ -4,7 +4,6 @@ import { Text } from "./text";
 
 const RENDER_INTERVAL_MS = 1000 / 30;
 const SPINNER_ADVANCE_MS = 80;
-const MAX_RENDER_BACKPRESSURE_MS = 200;
 const RENDER_BACKPRESSURE_MULTIPLIER = 9;
 
 type ColorFn = (str: string) => string;
@@ -144,8 +143,8 @@ export class Loader extends Text {
 			if (this.#intervalId !== timer) return;
 			const cadenceDelayMs = Math.max(0, intervalMs - frameCostMs);
 			// Idle for nine times the paint cost to keep animation at or below
-			// 10% CPU, while cheap frames retain their original cadence.
-			const backpressureDelayMs = Math.min(MAX_RENDER_BACKPRESSURE_MS, frameCostMs * RENDER_BACKPRESSURE_MULTIPLIER);
+			// 10% CPU, even when a slow ConPTY write exceeds the normal cadence.
+			const backpressureDelayMs = frameCostMs * RENDER_BACKPRESSURE_MULTIPLIER;
 			this.#scheduleTick(intervalMs, Math.max(cadenceDelayMs, backpressureDelayMs));
 		}, delayMs);
 		this.#intervalId = timer;

package/src/latex-block.ts

@@ -146,6 +146,16 @@ const HBRACE_COMMANDS: Record<string, HBraceSpec> = {
 	underparen: { left: "╰", mid: "─", center: "─", right: "╯", over: false },
 };
 
+/**
+ * Number of required arguments each display command consumes. Shared by
+ * {@link readArg} and {@link splitLines} so nested command atoms consume exactly
+ * their own arguments while preserving any outer command's pending arity.
+ */
+const COMMAND_ARITY: Record<string, number> = { overset: 2, underset: 2, stackrel: 2, sqrt: 1 };
+for (const name in FRAC_COMMANDS) COMMAND_ARITY[name] = 2;
+for (const name in BINOM_COMMANDS) COMMAND_ARITY[name] = 2;
+for (const name in HBRACE_COMMANDS) COMMAND_ARITY[name] = 1;
+
 // Vertical delimiter piece characters: `only` for single-line content, then
 // top/mid/bot columns for stretched forms; `axis` replaces `mid` at the
 // baseline row (the brace point).
@@ -516,11 +526,13 @@ function readBraceGroup(src: string, i: number): Span {
 
 /**
  * Read one command argument: a `{…}` group, a single char, or a `\command`
- * together with its attached `[…]`/`{…}` arguments (or whole `\begin…\end`
- * block), so e.g. `\frac\sqrt{a}{b}` reads `\sqrt{a}` as the numerator.
+ * together with its arguments (or whole `\begin…\end` block). Commands whose
+ * arity is known consume exactly that many arguments, including across source
+ * whitespace, so `\frac\sqrt {a} {b}` reads `\sqrt {a}` as the numerator and
+ * leaves `{b}` for the denominator.
  */
 function readArg(src: string, i: number): Span {
-	while (src[i] === " ") i++;
+	while (src[i] === " " || src[i] === "\t" || src[i] === "\n") i++;
 	if (i >= src.length) return { text: "", end: i };
 	if (src[i] === "{") return readBraceGroup(src, i);
 	if (src[i] !== "\\") return { text: src[i], end: i + 1 };
@@ -535,6 +547,22 @@ function readArg(src: string, i: number): Span {
 		if (env) return env;
 	}
 	if (!name) return { text: src.slice(i, i + 2), end: i + 2 }; // non-letter command (\,, \{, …)
+
+	const arity = COMMAND_ARITY[name];
+	if (arity !== undefined) {
+		let end = j;
+		// Optional command arguments (e.g. the degree in `\sqrt[3]{x}`) do not
+		// consume a required-argument slot.
+		for (;;) {
+			while (src[end] === " " || src[end] === "\t" || src[end] === "\n") end++;
+			if (src[end] !== "[") break;
+			const close = src.indexOf("]", end);
+			end = close === -1 ? src.length : close + 1;
+		}
+		for (let arg = 0; arg < arity; arg++) end = readArg(src, end).end;
+		return { text: src.slice(i, end), end };
+	}
+
 	let end = j;
 	while (src[end] === "[" || src[end] === "{") {
 		if (src[end] === "{") end = readBraceGroup(src, end).end;
@@ -1271,6 +1299,80 @@ function parseExpr(src: string, ctx: Ctx = ROOT_CTX): Box {
 	return hconcat(boxes);
 }
 
+/**
+ * Count the command arguments still owed at the end of `seg` — non-zero when
+ * the row ends mid-construct (`\frac{a}` awaiting its denominator, or
+ * `\frac`/`x^` awaiting any argument). Pending arities form a stack: an
+ * unbraced nested command consumes one outer argument, then retains its own
+ * pending arguments without discarding the outer command's remaining arity.
+ * Used to keep a command joined to an argument written on the next source line
+ * while still treating an ordinary next row (`a\n{b+c}`) as a real row break.
+ */
+function bracesOwed(seg: string): number {
+	const pending: number[] = [];
+	const consumeArg = (): void => {
+		const top = pending.length - 1;
+		if (top < 0) return;
+		if (pending[top] === 1) pending.pop();
+		else pending[top]--;
+	};
+
+	let i = 0;
+	while (i < seg.length) {
+		const c = seg[i];
+		if (c === "\\") {
+			let j = i + 1;
+			let name = "";
+			while (j < seg.length && /[A-Za-z]/.test(seg[j])) name += seg[j++];
+			// A command plus its immediately attached `[…]`/`{…}` groups is one
+			// atom for an enclosing argument, matching readArg. Consume that outer
+			// argument first, then retain only the command's own missing arguments
+			// in a nested frame. Attached groups beyond the known arity still stay
+			// part of the atom and cannot consume another outer argument.
+			consumeArg();
+			const arity = name ? (COMMAND_ARITY[name] ?? 0) : 0;
+			let attached = 0;
+			if (name) {
+				while (seg[j] === "[" || seg[j] === "{") {
+					if (seg[j] === "{") {
+						j = readBraceGroup(seg, j).end;
+						if (attached < arity) attached++;
+					} else {
+						const close = seg.indexOf("]", j);
+						j = close === -1 ? seg.length : close + 1;
+					}
+				}
+			} else {
+				j = i + 2; // non-letter command (`\,`, `\{`, …)
+			}
+			const missing = arity - attached;
+			if (missing > 0) pending.push(missing);
+			i = j;
+			continue;
+		}
+		if (c === "{") {
+			i = readBraceGroup(seg, i).end;
+			consumeArg();
+			continue;
+		}
+		if (c === "^" || c === "_") {
+			pending.push(1);
+			i++;
+			continue;
+		}
+		if (c === " " || c === "\t" || c === "\n") {
+			i++;
+			continue;
+		}
+		consumeArg(); // a bare atom satisfies one pending argument
+		i++;
+	}
+
+	let owed = 0;
+	for (const remaining of pending) owed += remaining;
+	return owed;
+}
+
 /** Split on top-level `\n` and `\\` row separators (outside braces and environments). */
 function splitLines(src: string): string[] {
 	const lines: string[] = [];
@@ -1308,8 +1410,16 @@ function splitLines(src: string): string[] {
 		if (c === "{") braceDepth++;
 		else if (c === "}") braceDepth--;
 		else if (c === "\n" && braceDepth === 0 && envDepth === 0) {
-			lines.push(src.slice(last, i));
-			last = i + 1;
+			// A top-level newline is a row break UNLESS the current row ends with a
+			// command still awaiting an argument (e.g. `\frac{num}\n{den}`,
+			// `\frac{num}\n\sqrt{x}`, or `x^\n2`). Splitting there would sever the
+			// command from its argument, so keep both in one segment; latexToBlock
+			// collapses the interior newline to a space before parsing. A row that
+			// merely opens with a braced group (`a\n{b+c}`) stays a break.
+			if (bracesOwed(src.slice(last, i)) === 0) {
+				lines.push(src.slice(last, i));
+				last = i + 1;
+			}
 		}
 		i++;
 	}
@@ -1327,7 +1437,7 @@ function splitLines(src: string): string[] {
 export function latexToBlock(src: string): string[] {
 	if (typeof src !== "string" || src.trim() === "") return [];
 	const rows = splitLines(src.trim())
-		.map(line => line.trim())
+		.map(line => line.replace(/[ \t]*\n[ \t]*/g, " ").trim())
 		.filter(line => line !== "")
 		.map(line => parseExpr(line));
 	if (rows.length === 0) return [];

package/src/terminal-capabilities.ts

@@ -731,6 +731,80 @@ export function encodeKittyPlacement(options: {
 	return wrapTmuxPassthroughIfNeeded(`\x1b_G${params.join(",")}\x1b\\`);
 }
 
+/**
+ * Exact shape of the direct-placement line {@link Image} emits as its block's
+ * last row: optional `ESC 7` + `CUU(rows-1)` prefix, the {@link encodeKittyPlacement}
+ * APC, optional `ESC 8` suffix. tmux-passthrough-wrapped lines deliberately do
+ * not match (passthrough placements stay untouched).
+ */
+const KITTY_DIRECT_PLACEMENT_LINE =
+	/^(?:\x1b7(?:\x1b\[(\d+)A)?)?\x1b_Ga=p,q=2,C=1,i=(\d+)(?:,p=(\d+))?(?:,c=(\d+))?(?:,r=(\d+))?\x1b\\(?:\x1b8)?$/;
+
+export interface ParsedKittyPlacementLine {
+	imageId: number;
+	placementId: number | undefined;
+	columns: number;
+	rows: number;
+}
+
+/**
+ * Parse a frame line that consists solely of a Kitty direct placement (the
+ * last line of an {@link Image} block). Returns null for anything else —
+ * placeholder grids, tmux-wrapped placements, sixel/iTerm2 payloads — so
+ * callers fall back to writing the line verbatim.
+ */
+export function parseKittyDirectPlacementLine(line: string): ParsedKittyPlacementLine | null {
+	const m = KITTY_DIRECT_PLACEMENT_LINE.exec(line);
+	if (!m) return null;
+	const columns = m[4] !== undefined ? Number(m[4]) : 0;
+	const rows = m[5] !== undefined ? Number(m[5]) : 0;
+	if (columns <= 0 || rows <= 0) return null;
+	return {
+		imageId: Number(m[2]),
+		placementId: m[3] !== undefined ? Number(m[3]) : undefined,
+		columns,
+		rows,
+	};
+}
+
+/**
+ * Rebuild an {@link Image} direct-placement line for the viewport row it is
+ * written at. The component-rendered line encodes `CUU(rows-1)`, which clamps
+ * at the viewport top once the block's leading rows have scrolled out — the
+ * placement then re-anchors the full image shifted down over foreign rows.
+ * Anchor at the block's first *visible* row instead, clipping the source
+ * rectangle (`y=`/`h=`, image pixels) to the visible bottom slice.
+ */
+export function encodeKittyPlacementLine(options: {
+	imageId: number;
+	placementId: number;
+	columns: number;
+	/** Total cell rows of the image block. */
+	rows: number;
+	/** Viewport row the block's last line is being written at. */
+	screenRow: number;
+	/** Source image height in pixels, for the clipped source rectangle. */
+	imageHeightPx: number;
+}): string {
+	// Without a source pixel height the slice cannot be expressed — emit the
+	// component's own full form (status quo) rather than squashing the whole
+	// image into the reduced row count.
+	const clippable = options.imageHeightPx > 0;
+	const hiddenRows = clippable ? Math.max(0, options.rows - 1 - options.screenRow) : 0;
+	const visibleRows = options.rows - hiddenRows;
+	const params: string[] = ["a=p", "q=2", "C=1", `i=${options.imageId}`, `p=${options.placementId}`];
+	params.push(`c=${options.columns}`, `r=${visibleRows}`);
+	if (hiddenRows > 0) {
+		const srcY = Math.floor((options.imageHeightPx * hiddenRows) / options.rows);
+		params.push(`y=${srcY}`, `h=${Math.max(1, options.imageHeightPx - srcY)}`);
+	}
+	// No tmux passthrough: inside tmux the component's own line arrives
+	// wrapped, never parses, and never reaches this rewrite.
+	const apc = `\x1b_G${params.join(",")}\x1b\\`;
+	const cuu = visibleRows - 1;
+	return cuu > 0 ? `\x1b7\x1b[${cuu}A${apc}\x1b8` : apc;
+}
+
 /**
  * Kitty graphics delete command for a single image id. Uses `d=I` (capital)
  * which removes the image and every one of its placements — on screen *and* in
@@ -742,6 +816,16 @@ export function encodeKittyDeleteImage(imageId: number): string {
 	return wrapTmuxPassthroughIfNeeded(`\x1b_Ga=d,d=I,i=${imageId},q=2\x1b\\`);
 }
 
+/**
+ * Delete a single placement of an image (`d=i`, lowercase): removes its cells
+ * and registry entry but keeps the transmitted data, so a later `a=p` under a
+ * fresh placement id needs no retransmit. Used to clear stale placement-epoch
+ * entries after a destructive history clear.
+ */
+export function encodeKittyDeletePlacement(imageId: number, placementId: number): string {
+	return wrapTmuxPassthroughIfNeeded(`\x1b_Ga=d,d=i,i=${imageId},p=${placementId},q=2\x1b\\`);
+}
+
 export function encodeITerm2(
 	base64Data: string,
 	options: {

package/src/tui.ts

@@ -25,8 +25,11 @@ import { LoopWatchdog } from "./loop-watchdog";
 import { isConPTYHosted, setAltScreenActive, type Terminal } from "./terminal";
 import {
 	encodeKittyDeleteImage,
+	encodeKittyDeletePlacement,
+	encodeKittyPlacementLine,
 	ImageProtocol,
 	isInsideTerminalMultiplexer,
+	parseKittyDirectPlacementLine,
 	setCellDimensions,
 	setTerminalImageProtocol,
 	shouldEnableSynchronizedOutputByDefault,
@@ -2133,7 +2136,13 @@ export class TUI extends Container {
 		buffer += "\r";
 		for (let i = firstChanged; i <= lastChanged; i++) {
 			if (i > firstChanged) buffer += "\r\n";
-			buffer += this.#lineRewriteSequence(this.#preparedFrame[segment.start + i] ?? "", width);
+			buffer += this.#lineRewriteSequence(
+				this.#preparedFrame[segment.start + i] ?? "",
+				width,
+				screenStart + i,
+				segment.start + i,
+				this.#committedRows,
+			);
 		}
 		const cursorControl = this.#cursorControlSequence(
 			cursorPos,
@@ -2796,8 +2805,39 @@ export class TUI extends Container {
 		};
 	}
 
-	#terminalLine(line: string): string {
-		if (TERMINAL.isImageLine(line)) return line;
+	/**
+	 * Rewrite a Kitty direct-placement line for the viewport row it is written
+	 * at, clipping to the visible slice (see {@link encodeKittyPlacementLine})
+	 * under the placement id resolved by the budget's epoch tracking (see
+	 * {@link ImageBudget.resolvePlacementEmit}). `screenRow` -1 (write position
+	 * unknown) and non-placement image lines (placeholder grids, sixel, iTerm2,
+	 * tmux-wrapped) pass through verbatim.
+	 */
+	#imageLineSequence(line: string, screenRow: number, frameRow: number, committedTo: number): string {
+		if (screenRow < 0) return line;
+		const parsed = parseKittyDirectPlacementLine(line);
+		if (!parsed) return line;
+		// The emitted placement attaches from the block's first *visible* row
+		// (the clip drops the rows above the viewport), so epoch tracking keys
+		// on that row — not the block origin, which may be long committed.
+		const placement = this.#imageBudget.resolvePlacementEmit(
+			parsed.imageId,
+			frameRow >= 0 ? frameRow - Math.min(parsed.rows - 1, screenRow) : -1,
+			committedTo,
+		);
+		if (!placement) return line;
+		return encodeKittyPlacementLine({
+			imageId: parsed.imageId,
+			placementId: placement.placementId,
+			columns: parsed.columns,
+			rows: parsed.rows,
+			screenRow,
+			imageHeightPx: placement.heightPx,
+		});
+	}
+
+	#terminalLine(line: string, screenRow = -1, frameRow = -1, committedTo = -1): string {
+		if (TERMINAL.isImageLine(line)) return this.#imageLineSequence(line, screenRow, frameRow, committedTo);
 		const coalesced = coalesceAdjacentSgr(line);
 		return coalesced + (line.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
 	}
@@ -3208,6 +3248,12 @@ export class TUI extends Container {
 		} else {
 			this.#imageBudget.takePurgeIds();
 		}
+		// Feed this frame's commit target to the placement-epoch tracker before
+		// any placement resolves against it — an epoch whose rows commit during
+		// frames that never rewrite its line must still advance on the next
+		// re-emission, and the raw per-frame value keeps the check correct
+		// across committed-ledger rewinds.
+		this.#imageBudget.observeCommitWatermark(chunkTo);
 
 		// 6. Emit.
 		if (intent.kind === "fullPaint") {
@@ -3506,8 +3552,10 @@ export class TUI extends Container {
 		return col;
 	}
 
-	#lineRewriteSequence(line: string, width: number): string {
-		if (TERMINAL.isImageLine(line)) return ERASE_LINE + line;
+	#lineRewriteSequence(line: string, width: number, screenRow = -1, frameRow = -1, committedTo = -1): string {
+		if (TERMINAL.isImageLine(line)) {
+			return ERASE_LINE + this.#imageLineSequence(line, screenRow, frameRow, committedTo);
+		}
 		const terminalLine = this.#terminalLine(line);
 		const asciiWidth = this.#ansiAsciiLineWidth(line, width);
 		if (asciiWidth !== undefined) {
@@ -3674,7 +3722,17 @@ export class TUI extends Container {
 			// Clear native history without blanking the live viewport first. The
 			// replay below rewrites every visible row from home, including blanks,
 			// so terminals without DEC 2026 never expose an ED2-cleared frame.
+			// The clear also destroys every placement cell, so placement epochs
+			// restart and every registry entry each image ever placed is deleted
+			// explicitly (`d=i` keeps the transmitted data, so the replay needs
+			// no retransmit). Deleting epoch 1 too matters for images absent from
+			// the replay — nothing would ever replace their stale entry.
 			buffer += "\x1b[H\x1b[3J";
+			for (const { imageId, lastEpoch } of this.#imageBudget.resetPlacementEpochs()) {
+				for (let placementId = 1; placementId <= lastEpoch; placementId++) {
+					buffer += encodeKittyDeletePlacement(imageId, placementId);
+				}
+			}
 		} else {
 			// Best-effort: push the pre-paint screen into scrollback on
 			// terminals that implement kitty's ED 22
@@ -3711,20 +3769,31 @@ export class TUI extends Container {
 			// each row must self-clear stale cells left by the previous viewport.
 			for (let i = 0; i < chunkTo; i++) {
 				if (i > 0) buffer += "\r\n";
+				const writeRow = Math.min(i, height - 1);
 				buffer += options.clearScrollback
-					? this.#lineRewriteSequence(frame[i] ?? "", width)
-					: this.#terminalLine(frame[i] ?? "");
+					? this.#lineRewriteSequence(frame[i] ?? "", width, writeRow, i, chunkTo)
+					: this.#terminalLine(frame[i] ?? "", writeRow, i, chunkTo);
 			}
 			for (let screenRow = 0; screenRow < height; screenRow++) {
 				if (chunkTo + screenRow > 0) buffer += "\r\n";
 				const line = visibleTexts ? (visibleTexts[screenRow] ?? "") : (window[screenRow] ?? "");
-				buffer += options.clearScrollback ? this.#lineRewriteSequence(line, width) : this.#terminalLine(line);
+				const writeRow = Math.min(chunkTo + screenRow, height - 1);
+				const frameRow = windowTop + screenRow;
+				buffer += options.clearScrollback
+					? this.#lineRewriteSequence(line, width, writeRow, frameRow, chunkTo)
+					: this.#terminalLine(line, writeRow, frameRow, chunkTo);
 			}
 		} else {
+			// ConPTY-truncated replay: leading rows were dropped, so frame-space
+			// positions are unknown — placements still clip to the write row but
+			// skip epoch bookkeeping.
 			for (let i = 0; i < paintLines.length; i++) {
 				if (i > 0) buffer += "\r\n";
 				const line = visibleTexts && i >= visibleStart ? visibleTexts[i - visibleStart] : (paintLines[i] ?? "");
-				buffer += options.clearScrollback ? this.#lineRewriteSequence(line, width) : this.#terminalLine(line);
+				const writeRow = Math.min(i, height - 1);
+				buffer += options.clearScrollback
+					? this.#lineRewriteSequence(line, width, writeRow, -1, chunkTo)
+					: this.#terminalLine(line, writeRow, -1, chunkTo);
 			}
 		}
 		buffer += fillSequence;
@@ -3922,7 +3991,7 @@ export class TUI extends Container {
 		let buffer = `${this.#paintBeginSequence + altEnter}\x1b[H`;
 		for (let r = 0; r < height; r++) {
 			if (r > 0) buffer += "\r\n";
-			buffer += this.#lineRewriteSequence(window[r] ?? "", width);
+			buffer += this.#lineRewriteSequence(window[r] ?? "", width, r, -1, this.#committedRows);
 		}
 		// Park the hardware cursor at the real content bottom, not the padded
 		// viewport bottom: a later height shrink would otherwise scroll the live
@@ -3988,7 +4057,7 @@ export class TUI extends Container {
 		let buffer = `${this.#paintBeginSequence}\x1b[H`;
 		for (let r = 0; r < height; r++) {
 			if (r > 0) buffer += "\r\n";
-			buffer += this.#lineRewriteSequence(fitted[r], width);
+			buffer += this.#lineRewriteSequence(fitted[r], width, r, -1, -1);
 		}
 		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
@@ -4067,7 +4136,7 @@ export class TUI extends Container {
 				const moveToBottom = height - 1 - currentScreenRow;
 				if (moveToBottom > 0) buffer += `\x1b[${moveToBottom}B`;
 				for (let r = height - scroll; r < height; r++) {
-					buffer += `\r\n${this.#lineRewriteSequence(window[r] ?? "", width)}`;
+					buffer += `\r\n${this.#lineRewriteSequence(window[r] ?? "", width, height - 1, windowTop + r, chunkTo)}`;
 				}
 				// Rewrite any remaining changed rows after the shift.
 				let firstChanged = -1;
@@ -4084,7 +4153,7 @@ export class TUI extends Container {
 					buffer += "\r";
 					for (let r = firstChanged; r <= lastChanged; r++) {
 						if (r > firstChanged) buffer += "\r\n";
-						buffer += this.#lineRewriteSequence(window[r] ?? "", width);
+						buffer += this.#lineRewriteSequence(window[r] ?? "", width, r, windowTop + r, chunkTo);
 					}
 					cursorFromRow = windowTop + lastChanged;
 				}
@@ -4153,7 +4222,13 @@ export class TUI extends Container {
 			}
 			for (let r = firstChanged; r <= lastChanged; r++) {
 				if (r > firstChanged) buffer += "\r\n";
-				buffer += this.#lineRewriteSequence(fillTexts ? fillTexts[r - firstChanged] : (window[r] ?? ""), width);
+				buffer += this.#lineRewriteSequence(
+					fillTexts ? fillTexts[r - firstChanged] : (window[r] ?? ""),
+					width,
+					r,
+					windowTop + r,
+					this.#committedRows,
+				);
 			}
 			buffer += fillSequence;
 			// Never park below real content (a height shrink would scroll live
@@ -4184,12 +4259,18 @@ export class TUI extends Container {
 		let wroteLine = false;
 		for (let i = chunkFrom; i < chunkTo; i++) {
 			if (wroteLine) buffer += "\r\n";
-			buffer += this.#lineRewriteSequence(frame[i] ?? "", width);
+			buffer += this.#lineRewriteSequence(frame[i] ?? "", width, Math.min(i - chunkFrom, height - 1), i, chunkTo);
 			wroteLine = true;
 		}
 		for (let screenRow = 0; screenRow < height; screenRow++) {
 			if (wroteLine) buffer += "\r\n";
-			buffer += this.#lineRewriteSequence(window[screenRow] ?? "", width);
+			buffer += this.#lineRewriteSequence(
+				window[screenRow] ?? "",
+				width,
+				Math.min(chunkTo - chunkFrom + screenRow, height - 1),
+				windowTop + screenRow,
+				chunkTo,
+			);
 			wroteLine = true;
 		}
 		const parkUp = height - 1 - (contentBottomRow - windowTop);