@linxiraos/pi-tui 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -2,9 +2,40 @@
 
 ## [Unreleased]
 
-### Changed
+## [1.0.2] - 2026-08-15
+
+## [17.3.3] - 2026-08-14
+
+### Fixed
+
+- Fixed Gemini reports rendering their final headings and tables as one raw code block when the model emitted a lone closing Markdown fence without its opener.
+
+## [17.3.1] - 2026-08-13
+
+### Fixed
+
+- Fixed screen flashing in Herdr panes during transcript streaming.
+
+## [17.3.0] - 2026-08-13
+
+### Fixed
+
+- Fixed an issue where repeated pane-width adjustments or terminal resizing could corrupt native scrollback and soft-wrap behavior.
+- Fixed an issue where scaled OSC 66 Markdown headings (such as "Large Headings" on Kitty) would render as invisible placeholders or get partially cleared after a redraw or terminal resize.
+
+## [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)).
 
-- Reset the version to 1.0.0 and republished under the `@linxiraos/*` scope, breaking from the `@oh-my-pi` version lineage.
 ## [17.2.11] - 2026-08-07
 
 ### Fixed
@@ -1179,7 +1210,7 @@
 
 ### Added
 
-- Restored the `Key` runtime helper on `@oh-my-pi/pi-tui` to mirror upstream `@mariozechner/pi-tui`'s surface. `Key.enter`, `Key.escape`, `Key.tab`, … return the canonical key-name strings; modifier methods (`Key.ctrl(k)`, `Key.shift(k)`, `Key.ctrlShift(k)`, etc.) build precisely-typed `KeyId` literals like `"ctrl+c"`. Pure runtime convenience for typed key-id construction — plugins built against the upstream package surface that import `Key` (e.g. `@plannotator/pi-extension`, `@juicesharp/rpiv-ask-user-question`) load again now that the specifier shim remaps them onto this package.
+- Restored the `Key` runtime helper on `@linxiraos/pi-tui` to mirror upstream `@mariozechner/pi-tui`'s surface. `Key.enter`, `Key.escape`, `Key.tab`, … return the canonical key-name strings; modifier methods (`Key.ctrl(k)`, `Key.shift(k)`, `Key.ctrlShift(k)`, etc.) build precisely-typed `KeyId` literals like `"ctrl+c"`. Pure runtime convenience for typed key-id construction — plugins built against the upstream package surface that import `Key` (e.g. `@plannotator/pi-extension`, `@juicesharp/rpiv-ask-user-question`) load again now that the specifier shim remaps them onto this package.
 
 ## [15.0.1] - 2026-05-14
 
@@ -1260,7 +1291,7 @@
 - Simplified cache key computation in Box component by removing intermediate hash updates and consolidating hash operations
 - Wrapped native text utility functions (`sliceWithWidth`, `truncateToWidth`, `wrapTextWithAnsi`, `extractSegments`) to automatically pass the current default tab width, simplifying the API for consumers
 - Added `getIndentationNoescape` wrapper that uses `process.cwd()` as the project root for relative file paths
-- Re-export `getDefaultTabWidth`, `getIndentation`, and `setDefaultTabWidth` from `@oh-my-pi/pi-utils`; native text helpers still receive tab width via wrappers that read the JS default
+- Re-export `getDefaultTabWidth`, `getIndentation`, and `setDefaultTabWidth` from `@linxiraos/pi-utils`; native text helpers still receive tab width via wrappers that read the JS default
 
 ## [13.16.1] - 2026-03-27
 
@@ -1567,7 +1598,7 @@
 - Changed notification suppression environment variable from `OMP_NOTIFICATIONS` to `PI_NOTIFICATIONS`
 - Changed TUI write log environment variable from `OMP_TUI_WRITE_LOG` to `PI_TUI_WRITE_LOG`
 - Changed hardware cursor environment variable from `OMP_HARDWARE_CURSOR` to `PI_HARDWARE_CURSOR`
-- Updated environment variable access to use `getEnv()` utility function from `@oh-my-pi/pi-utils` for consistent handling
+- Updated environment variable access to use `getEnv()` utility function from `@linxiraos/pi-utils` for consistent handling
 - Renamed `TERMINAL_INFO` export to `TERMINAL` for clearer API semantics
 - Reorganized terminal image exports from `terminal-image` to `terminal-capabilities` module
 - Updated all internal references to use `TERMINAL` instead of `TERMINAL_INFO`
@@ -1586,7 +1617,7 @@
 
 ### Changed
 
-- Moved `wrapTextWithAnsi` export to `@oh-my-pi/pi-natives` package
+- Moved `wrapTextWithAnsi` export to `@linxiraos/pi-natives` package
 
 ### Fixed
 
@@ -1615,7 +1646,7 @@
 
 ### Removed
 
-- Removed `truncateToWidth`, `sliceWithWidth`, and `extractSegments` functions from public API (now re-exported directly from @oh-my-pi/pi-natives)
+- Removed `truncateToWidth`, `sliceWithWidth`, and `extractSegments` functions from public API (now re-exported directly from @linxiraos/pi-natives)
 - Removed `ellipsis` property from `SymbolTheme` interface
 - Removed `extractAnsiCode` function from public API
 
@@ -1956,6 +1987,16 @@ Initial release under @oh-my-pi scope. See previous releases at [badlogic/pi-mon
 
 - Added `getText()` method to Text component for retrieving current text content
 
+## [1.0.1] - 2026-08-14
+
+- Reset the version to 1.0.0 and republished under the `@linxiraos/*` scope, breaking from the `@oh-my-pi` version lineage.
+
+## [1.0.0] - 2026-08-13
+
+### Changed
+
+- Reset the version to 1.0.0 and republished under the `@linxiraos/*` scope, breaking from the `@oh-my-pi` version lineage.
+
 ## [0.50.0] - 2026-01-26
 
 ### Added

package/README.md

@@ -640,7 +640,7 @@ class MyComponent implements Component {
 - `wrapTextWithAnsi()` preserves ANSI codes while word-wrapping and trimming line ends
 
 ```typescript
-import chalk from "@oh-my-pi/pi-utils/chalk";
+import chalk from "@linxiraos/pi-utils/chalk";
 
 const styled = chalk.red("Hello") + " " + chalk.blue("World");
 const width = visibleWidth(styled); // 11 (not counting ANSI codes)

package/package.json

@@ -1,70 +1,69 @@
 {
-	"type": "module",
-	"name": "@linxiraos/pi-tui",
-	"version": "1.0.0",
-	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
-	"homepage": "https://linxira-os.github.io",
-	"author": "Can Boluk",
-	"contributors": [
-		"Mario Zechner"
-	],
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
-		"directory": "packages/tui"
-	},
-	"bugs": {
-		"url": "https://github.com/can1357/oh-my-pi/issues"
-	},
-	"keywords": [
-		"tui",
-		"terminal",
-		"ui",
-		"text-editor",
-		"differential-rendering",
-		"typescript",
-		"cli"
-	],
-	"main": "./src/index.ts",
-	"types": "./dist/types/index.d.ts",
-	"scripts": {
-		"check": "biome check . && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
-		"lint": "biome lint .",
-		"test": "bun test --parallel test/*.test.ts",
-		"fix": "biome check --write --unsafe .",
-		"fmt": "biome format --write ."
-	},
-	"dependencies": {
-		"@linxiraos/pi-natives": "1.0.0",
-		"@linxiraos/pi-utils": "1.0.0"
-	},
-	"devDependencies": {
-		"ghostty-web": "^0.4.0"
-	},
-	"engines": {
-		"bun": ">=1.3.14"
-	},
-	"files": [
-		"src",
-		"README.md",
-		"CHANGELOG.md",
-		"dist/types"
-	],
-	"exports": {
-		".": {
-			"types": "./dist/types/index.d.ts",
-			"import": "./src/index.ts"
-		},
-		"./*": {
-			"types": "./dist/types/*.d.ts",
-			"import": "./src/*.ts"
-		},
-		"./components/*": {
-			"types": "./dist/types/components/*.d.ts",
-			"import": "./src/components/*.ts"
-		},
-		"./*.js": "./src/*.ts"
-	}
+  "type": "module",
+  "name": "@linxiraos/pi-tui",
+  "version": "1.0.2",
+  "description": "Terminal User Interface library with differential rendering for efficient text-based applications",
+  "homepage": "https://linxira-os.github.io",
+  "author": "Can Boluk",
+  "contributors": [
+    "Mario Zechner"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
+    "directory": "packages/tui"
+  },
+  "bugs": {
+    "url": "https://github.com/can1357/oh-my-pi/issues"
+  },
+  "keywords": [
+    "tui",
+    "terminal",
+    "ui",
+    "text-editor",
+    "differential-rendering",
+    "typescript",
+    "cli"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "check": "biome check . && bun run check:types",
+    "check:types": "tsgo -p tsconfig.json --noEmit",
+    "lint": "biome lint .",
+    "test": "bun test --parallel test/*.test.ts",
+    "fix": "biome check --write --unsafe .",
+    "fmt": "biome format --write ."
+  },
+  "dependencies": {
+    "@linxiraos/pi-natives": "catalog:",
+    "@linxiraos/pi-utils": "catalog:"
+  },
+  "devDependencies": {
+    "ghostty-web": "catalog:"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./*": {
+      "types": "./src/*.ts",
+      "import": "./src/*.ts"
+    },
+    "./components/*": {
+      "types": "./src/components/*.ts",
+      "import": "./src/components/*.ts"
+    },
+    "./*.js": "./src/*.ts"
+  }
 }

package/src/components/editor.ts

@@ -391,6 +391,8 @@ export interface EditorTopBorder {
 	content: string;
 	/** Visible width of the content */
 	width: number;
+	/** Optional logical revision that changes independently of available width. */
+	revision?: number;
 }
 
 interface HistoryEntry {
@@ -410,6 +412,8 @@ export class Editor implements Component, Focusable {
 		cursorLine: 0,
 		cursorCol: 0,
 	};
+	#widthEpochText = "";
+	#widthEpochRevision = 0;
 
 	/** Focusable interface - set by TUI when focus changes */
 	focused: boolean = false;
@@ -515,6 +519,9 @@ export class Editor implements Component, Focusable {
 	// per-event rebuilds down to one per rendered frame (see #4145).
 	#topBorderContent?: EditorTopBorder;
 	#topBorderProvider?: (availableWidth: number) => EditorTopBorder | undefined;
+	#topBorderProviderWidth: number | undefined;
+	#topBorderProviderSignature: string | undefined;
+	#topBorderProviderRevision: number | undefined;
 	#borderVisible = true;
 
 	constructor(theme: EditorTheme) {
@@ -536,7 +543,10 @@ export class Editor implements Component, Focusable {
 	 * per-event rebuilds to one per painted frame.
 	 */
 	setTopBorder(content: EditorTopBorder | undefined): void {
+		if (this.#topBorderContent?.content === content?.content && this.#topBorderContent?.width === content?.width)
+			return;
 		this.#topBorderContent = content;
+		this.#widthEpochRevision++;
 	}
 
 	/**
@@ -546,18 +556,26 @@ export class Editor implements Component, Focusable {
 	 *
 	 * Use this when the top border derives from state that mutates far faster
 	 * than the render cadence (session events, streaming, subagent updates).
-	 * The TUI already throttles renders, so a provider is invoked at most once
-	 * per frame and never does wasted work between paints.
+	 * The TUI already throttles renders, so a provider is invoked exactly once
+	 * per frame and does no work between paints. Return a logical `revision` to
+	 * distinguish concurrent status mutations from pure width reflow.
 	 */
 	setTopBorderProvider(provider: ((availableWidth: number) => EditorTopBorder | undefined) | undefined): void {
+		if (this.#topBorderProvider === provider) return;
 		this.#topBorderProvider = provider;
+		this.#topBorderProviderWidth = undefined;
+		this.#topBorderProviderSignature = undefined;
+		this.#topBorderProviderRevision = undefined;
+		this.#widthEpochRevision++;
 	}
 
 	/**
 	 * Show or hide the editor border chrome.
 	 */
 	setBorderVisible(borderVisible: boolean): void {
+		if (this.#borderVisible === borderVisible) return;
 		this.#borderVisible = borderVisible;
+		this.#widthEpochRevision++;
 	}
 
 	setPromptGutter(promptGutter: string | undefined): void {
@@ -578,12 +596,16 @@ export class Editor implements Component, Focusable {
 	 * Use the real terminal cursor instead of rendering a cursor glyph.
 	 */
 	setUseTerminalCursor(useTerminalCursor: boolean): void {
+		if (this.#useTerminalCursor === useTerminalCursor) return;
 		this.#useTerminalCursor = useTerminalCursor;
+		this.#widthEpochRevision++;
 	}
 
 	/** Render a dedicated bottom border so terminal-local IME preedit cannot shift editor chrome. */
 	setImeSafeCursorLayout(enabled: boolean): void {
+		if (this.#imeSafeCursorLayout === enabled) return;
 		this.#imeSafeCursorLayout = enabled;
+		this.#widthEpochRevision++;
 	}
 
 	getUseTerminalCursor(): boolean {
@@ -593,6 +615,7 @@ export class Editor implements Component, Focusable {
 	setMaxHeight(maxHeight: number | undefined): void {
 		if (this.#maxHeight === maxHeight) return;
 		this.#maxHeight = maxHeight;
+		this.#widthEpochRevision++;
 		// Don't reset scrollOffset — #updateScrollOffset will clamp it on next render
 	}
 
@@ -613,6 +636,10 @@ export class Editor implements Component, Focusable {
 		const newMaxVisible = Number.isFinite(maxVisible) ? Math.max(3, Math.min(20, Math.floor(maxVisible))) : 5;
 		if (this.#autocompleteMaxVisible !== newMaxVisible) {
 			this.#autocompleteMaxVisible = newMaxVisible;
+			if (this.#autocompleteState !== null) {
+				this.#autocompleteList?.setMaxVisible(newMaxVisible);
+				this.#widthEpochRevision++;
+			}
 		}
 	}
 
@@ -900,7 +927,27 @@ export class Editor implements Component, Focusable {
 			// Provider (lazy) wins over eager content — a host that installs both
 			// wants the coalesced path; falling back to eager keeps existing
 			// setTopBorder callers working unchanged.
-			const topBorder = this.#topBorderProvider ? this.#topBorderProvider(topFillWidth) : this.#topBorderContent;
+			let topBorder: EditorTopBorder | undefined;
+			if (this.#topBorderProvider) {
+				const previousWidth = this.#topBorderProviderWidth;
+				topBorder = this.#topBorderProvider(topFillWidth);
+				const signature = topBorder ? `${topBorder.width}\0${topBorder.content}` : "";
+				const revision = topBorder?.revision;
+				if (
+					(previousWidth !== undefined &&
+						revision !== undefined &&
+						this.#topBorderProviderRevision !== undefined &&
+						revision !== this.#topBorderProviderRevision) ||
+					(previousWidth === topFillWidth && signature !== this.#topBorderProviderSignature)
+				) {
+					this.#widthEpochRevision++;
+				}
+				this.#topBorderProviderWidth = topFillWidth;
+				this.#topBorderProviderSignature = signature;
+				this.#topBorderProviderRevision = revision;
+			} else {
+				topBorder = this.#topBorderContent;
+			}
 			if (topBorder) {
 				const { content, width: statusWidth } = topBorder;
 				if (statusWidth <= topFillWidth) {
@@ -1240,6 +1287,7 @@ export class Editor implements Component, Focusable {
 					kb.matchesCanonical(canonical, "tui.select.pageDown")
 				) {
 					this.#autocompleteList.handleInput(data);
+					this.#widthEpochRevision++;
 					this.onAutocompleteUpdate?.();
 					return;
 				}
@@ -1670,6 +1718,15 @@ export class Editor implements Component, Focusable {
 		return this.#state.lines.join("\n");
 	}
 
+	getNativeScrollbackWidthEpochRevision(): number {
+		const text = this.getText();
+		if (text !== this.#widthEpochText) {
+			this.#widthEpochText = text;
+			this.#widthEpochRevision++;
+		}
+		return this.#widthEpochRevision;
+	}
+
 	/** Whether the buffer text equals `value`, without `getText()`'s full join —
 	 *  O(1) for the hot per-keystroke probes against short single-line values. */
 	textEquals(value: string): boolean {
@@ -3149,6 +3206,7 @@ export class Editor implements Component, Focusable {
 			this.#autocompletePrefix = suggestions.prefix;
 			this.#autocompleteList = this.#createAutocompleteList(suggestions.prefix, suggestions.items);
 			this.#autocompleteState = "regular";
+			this.#widthEpochRevision++;
 			this.onAutocompleteUpdate?.();
 		} else {
 			this.#cancelAutocomplete();
@@ -3207,6 +3265,7 @@ export class Editor implements Component, Focusable {
 			this.#autocompletePrefix = suggestions.prefix;
 			this.#autocompleteList = this.#createAutocompleteList(suggestions.prefix, suggestions.items);
 			this.#autocompleteState = "force";
+			this.#widthEpochRevision++;
 			this.onAutocompleteUpdate?.();
 		} else {
 			this.#cancelAutocomplete();
@@ -3221,6 +3280,7 @@ export class Editor implements Component, Focusable {
 		this.#autocompleteState = null;
 		this.#autocompleteList = undefined;
 		this.#autocompletePrefix = "";
+		if (wasAutocompleting) this.#widthEpochRevision++;
 		if (notifyCancel && wasAutocompleting) {
 			this.onAutocompleteCancel?.();
 		}
@@ -3252,6 +3312,7 @@ export class Editor implements Component, Focusable {
 			this.#autocompletePrefix = suggestions.prefix;
 			// Always create new SelectList to ensure update
 			this.#autocompleteList = this.#createAutocompleteList(suggestions.prefix, suggestions.items);
+			this.#widthEpochRevision++;
 			this.onAutocompleteUpdate?.();
 		} else {
 			this.#cancelAutocomplete();

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,126 @@ 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);
+			}
+		}
+	}
+
+	/**
+	 * End the physical-row coordinate epoch after observing its final commit
+	 * watermark. Placement ids and latched archive state survive, but attachment
+	 * rows do not: the next placement emit records them in the new-width frame.
+	 */
+	beginPlacementCoordinateEpoch(): void {
+		for (const state of this.#placementState.values()) state.lastAttachTopFrameRow = undefined;
+		this.#watchedPlacements.clear();
+	}
+
+	/**
+	 * 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 +565,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;