@gajae-code/tui 0.11.11 → 0.12.1

package/CHANGELOG.md

@@ -2,7 +2,31 @@
 
 ## [Unreleased]
 
-## [0.11.11] - 2026-07-26
+## [0.12.1] - 2026-07-29
+
+### Fixed
+
+- Kitty/Ghostty inline images no longer remain visually pinned when sticky or semantic viewport repaints move their anchors into application scrollback. The renderer now soft-deletes only the named placement from the old viewport, retains uploaded pixels for history replay, and keeps placement tracking aligned across unresolved-anchor and follow-live transitions.
+
+## [0.12.0] - 2026-07-28
+
+### Changed
+
+- Mouse wheel scrolling now moves the session viewport by exactly three lines (`DEFAULT_WHEEL_LINES = 3`) instead of a full page. PageUp/PageDown keep page-sized steps with edge pinning.
+- Manual transcript scrolling now keeps a valid registered status/composer boundary fixed at the bottom independently of output-source registration. Output sources control only the exact semantic new-output notice; transcript selection excludes pinned chrome, short transcript lanes emit blanks instead of duplicating suffix rows, and constrained heights retain the focused suffix component before decorative rows.
+- Manual viewport revisions now advance for semantic changes in a visible capped sidebar even without an inline component; duplicate, elided, hidden, geometry-only, and theme-only changes do not raise a false new-output notice. Equal output-source updates do not render, and constrained pinned suffixes avoid copying transcript-length prefixes.
+- A downward manual scroll (wheel or `PageDown`) that reaches the true transcript bottom now transitions through the existing live-follow transaction instead of repainting another manual frame, so wheel and PageDown automatically return to live output at the bottom. A partial downward movement retains manual ownership and the notice; upward movement never follows. The transition preserves editor focus, pinned chrome, notice clearing, and fatal terminal transaction semantics, clears manual anchor state through the existing transaction, and does not replay manual-era output into native/host scrollback.
+
+### Fixed
+
+- Slash-command autocomplete no longer treats the final segment of a nested filesystem path or URL as a command token, preventing accepted skill suggestions from rewriting literal paths.
+
+- Terminal capability-probe replies no longer leak into the prompt as text (`^[]11;rgb:0000/0000/0000^G^[[?62;22;52c` appearing in the editor after a long-running foreground command). Three separate paths fed them to the input handler: replies whose pending-query counters had already been reset (`stop()`/`start()` around an editor handoff, Ctrl+Z, or a session resume) failed the `#pendingDa1Sentinels`/`#osc11Pending` gates and were forwarded; a reply split across stdin reads with a gap larger than `StdinBuffer`'s 10ms completion timeout was flushed as individual characters; and an unterminated sequence kept absorbing the following ESC. Probe replies are now consumed by shape, incomplete probe-reply prefixes are held at the stdin decoding boundary (bounded by 500ms/256 bytes, and only 150ms for a bare ESC inside a probe window), an ESC cuts the sequence in progress unless it is an OSC/DCS/APC string terminator, and an unsolicited reply is dropped by an explicit backstop. A dropped or mangled reply can no longer latch `#osc11Pending` either: a 1s watchdog and a 64-byte reassembly cap resolve the query cycle instead of swallowing keystrokes. DA1 and XTSMGRAPHICS replies stay owned by the sixel probe and are dropped in `Tui` once that probe has finished, so an orphaned device report is no longer typed into the focused component.
+
+- `waitForRenderCommit` / generation-scoped render tokens resolve only after a successful buffer write (or fail open on stopped/unavailable terminals), enabling awaitable progress frames for interactive resume without hanging (#2914).
+- Streaming layout contraction followed by regrowth no longer re-admits an already committed logical row into native terminal scrollback, preventing occasional duplicated assistant lines after Markdown reflow.
+- Repeated clearing of an already-clear viewport output source is now a render-request no-op, matching identical non-null source updates.
+- A terminal width change now ends in one forced full redraw 1000ms after the last observed resize event, repairing stale bands left by lines wrapped at the old column count — across the full transcript, including scrollback history, on every host. Interim resize frames keep their cheap per-host path; the debounce is what makes the one full replay safe, so drag-resizing still does not replay the transcript per `SIGWINCH`. While the user is reading scrollback (manual viewport), the repair is deferred and runs when they return to live output. Height-only changes are unaffected (#3360, #3361).
 
 ## [0.11.7] - 2026-07-22
 ### Fixed

package/README.md

@@ -56,6 +56,14 @@ tui.requestRender(); // Request a re-render
 tui.onDebug = () => console.log("Debug triggered");
 ```
 
+### Manual viewport and pinned suffix
+
+`setBottomPinnedComponent(component)` marks a direct-child boundary. During manual viewport ownership, that child and all later direct children remain fixed at the bottom while rows before it form the scrollable lane; this does not require an output source. `scrollViewportPages()` moves by the lane height minus one; `scrollViewportBy()` supports smaller row steps and rejects non-finite deltas.
+
+`setViewportOutputSource({ identity, revision })` reports semantic output changes without coupling the TUI to message types. A same-identity revision advance while manually scrolled displays the exact notice `New output — type to follow`; following live or changing/removing the identity clears it, while a stale same-identity revision rollback does not.
+
+Pinned rows and the notice are excluded from transcript mouse-selection coordinates. When the terminal is too short, the focused direct-child suffix component is retained before decorative or lower-priority suffix rows.
+
 ### Component Interface
 
 All components implement:

package/dist/types/metrics.d.ts

@@ -48,6 +48,7 @@ export interface RenderMetricsSnapshot {
     timerGauges: Record<string, number>;
     helperStats: Record<string, HelperStat>;
     lineCounts: Record<string, LineCountGauge>;
+    structuralCounters: Record<string, number>;
 }
 export declare class RenderMetrics {
     #private;
@@ -73,6 +74,8 @@ export declare class RenderMetrics {
     recordHelper(name: string, durationMs: number): void;
     /** Record a per-render line-count gauge (e.g. "rendered", "normalized", "diffed"). */
     recordLineCount(name: string, value: number): void;
+    /** Accumulate deterministic structural render work without retaining frame data. */
+    recordStructuralCounter(name: string, value?: number): void;
     /**
      * Force a GC when the runtime exposes one and sample RSS as the post-run
      * "return" value used by the memory-leak gate. Callers should drop large

package/dist/types/stdin-buffer.d.ts

@@ -45,6 +45,12 @@ export declare class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
     #private;
     constructor(options?: StdinBufferOptions);
     process(data: string | Buffer): void;
+    /**
+     * ProcessTerminal calls this right after writing a capability probe so a lone
+     * ESC arriving inside the reply window is treated as a possible reply fragment
+     * rather than a keypress.
+     */
+    noteProbeIssued(windowMs?: number): void;
     flush(): string[];
     clear(): void;
     getBuffer(): string;

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

@@ -158,6 +158,15 @@ export declare function encodeKittyPlacement(options: {
     columns: number;
     rows: number;
 }): string;
+export interface KittyPlacementReference {
+    imageId: number;
+    placementId: number;
+    rows: number;
+}
+/** Extract bounded, named kitty placements from a rendered line. */
+export declare function extractKittyPlacementReferences(line: string): KittyPlacementReference[];
+/** Soft-delete one named kitty placement while retaining its transmitted pixels. */
+export declare function encodeKittyPlacementDelete(reference: KittyPlacementReference): string;
 export declare function encodeITerm2(base64Data: string, options?: {
     width?: number | string;
     height?: number | string;

package/dist/types/terminal.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Capability-probe reply shapes that only this layer solicits (OSC 11 background
+ * color, the Mode 2031 appearance DSR, and the Kitty keyboard-flags report).
+ * These are terminal-to-host replies and are NEVER legitimate user input, so a
+ * reply that arrives outside its pending-query window is dropped defensively.
+ *
+ * DA1 is deliberately absent: `Tui` issues its own DA1 request for the sixel
+ * probe and consumes that reply downstream.
+ */
+export declare const PROBE_REPLY_PATTERNS: ReadonlyArray<{
+    name: string;
+    issuedProbe: string;
+    pattern: RegExp;
+}>;
+/** True when `sequence` is one of the probe replies above. */
+export declare function isUnsolicitedProbeReply(sequence: string): boolean;
 /**
  * Whether GJC may reprogram the keyboard with enhanced input protocols
  * (the Kitty keyboard protocol and the xterm modifyOtherKeys fallback).

package/dist/types/tui.d.ts

@@ -1,5 +1,7 @@
 import type { Terminal } from "./terminal";
 import { visibleWidth } from "./utils";
+/** Discrete mouse-wheel notch size in terminal rows (xterm/less-style). */
+export declare const DEFAULT_WHEEL_LINES = 3;
 type InputListenerResult = {
     consume?: boolean;
     data?: string;
@@ -99,6 +101,11 @@ export interface ViewportAnchorProvider extends Component {
 export interface ViewportAnchorSource {
     id: ViewportAnchorId;
 }
+/** Identity and monotonic revision of the logical output producer. */
+export type ViewportOutputSource = {
+    identity: string;
+    revision: bigint;
+};
 export interface ViewportAnchorSourceRenderer extends Component {
     renderWithViewportAnchorSource(width: number, source: ViewportAnchorSource): ViewportAnchorRender;
 }
@@ -231,6 +238,13 @@ export declare class TUI extends Container {
     constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: {
         enableMouse?: boolean;
         copySelection?: (text: string) => void | Promise<void>;
+        /**
+         * Trailing debounce for the settled width repair, in ms. `0` disables the
+         * settled repair (deterministic harnesses need this — a wall-clock-timed
+         * full replay lands at nondeterministic logical positions). Defaults to
+         * `GJC_TUI_WIDTH_SETTLE_MS` / `PI_TUI_WIDTH_SETTLE_MS`, then 1000.
+         */
+        widthSettleMs?: number;
     });
     dispose(): void;
     get fullRedraws(): number;
@@ -244,7 +258,11 @@ export declare class TUI extends Container {
      */
     setClearOnShrink(enabled: boolean): void;
     setFocus(component: Component | null): void;
+    removeChild(component: Component): void;
+    clear(): void;
     setBottomPinnedComponent(component: Component | null): void;
+    /** Report the logical output producer revision without coupling TUI to message types. */
+    setViewportOutputSource(source: ViewportOutputSource | null): void;
     /** Register the direct child whose rows are eligible for semantic viewport anchoring. */
     setViewportAnchorComponent(component: Component | null): void;
     /** Clear manual viewport ownership before replacing the transcript identity namespace. */
@@ -253,6 +271,10 @@ export declare class TUI extends Container {
     prepareViewportAnchorForTranscriptRebuild(): void;
     /** Reveal a semantic viewport anchor without changing the rendered content width. */
     revealViewportAnchor(id: ViewportAnchorId, alignment: "top" | "center" | "bottom"): boolean;
+    scrollViewportBy(deltaRows: number, options?: {
+        /** edge: PageUp/PageDown pin; stable: preserve/center pin for fine wheel motion */
+        pin?: "edge" | "stable";
+    }): boolean;
     scrollViewportPages(direction: -1 | 1): boolean;
     followLiveViewport(): boolean;
     /**
@@ -266,6 +288,15 @@ export declare class TUI extends Container {
     hasOverlay(): boolean;
     invalidate(): void;
     start(): void;
+    /**
+     * Wait for a specific render request generation to be written successfully.
+     *
+     * Render requests are coalesced, so committing a newer generation also commits
+     * every older generation represented by that frame. A stopped or unavailable
+     * terminal resolves waiters false so UI callers can fail open instead of
+     * holding a session operation behind a dead renderer.
+     */
+    waitForRenderCommit(generation: number, timeoutMs?: number): Promise<boolean>;
     get terminalAvailable(): boolean;
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
@@ -294,6 +325,7 @@ export declare class TUI extends Container {
      */
     requestResizeRender(): void;
     requestRender(force?: boolean, source?: string): void;
+    requestRenderWithGeneration(force?: boolean, source?: string): number;
     getLineRenderCacheStats(): {
         normalizationSize: number;
         truncationSize: number;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.11.11",
+	"version": "0.12.1",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -36,8 +36,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.11.11",
-		"@gajae-code/utils": "0.11.11",
+		"@gajae-code/natives": "0.12.1",
+		"@gajae-code/utils": "0.12.1",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},

package/src/autocomplete.ts

@@ -229,6 +229,10 @@ export function extractSlashCommandTokenPrefix(text: string): string | null {
 	const charBeforeSlash = text[slashIndex - 1];
 	if (charBeforeSlash && NON_COMMAND_SLASH_PREFIX_PRECEDERS.has(charBeforeSlash)) return null;
 
+	let tokenStart = slashIndex;
+	while (tokenStart > 0 && !/\s/.test(text[tokenStart - 1] ?? "")) tokenStart -= 1;
+	if (text.slice(tokenStart, slashIndex).includes("/")) return null;
+
 	return token;
 }
 export interface AutocompleteItem {

package/src/metrics.ts

@@ -124,6 +124,7 @@ export interface RenderMetricsSnapshot {
 	timerGauges: Record<string, number>;
 	helperStats: Record<string, HelperStat>;
 	lineCounts: Record<string, LineCountGauge>;
+	structuralCounters: Record<string, number>;
 }
 
 function emptyDurationStats(): DurationStats {
@@ -160,6 +161,7 @@ export class RenderMetrics {
 	#timerGauges = new Map<string, number>();
 	#helpers = new Map<string, { count: number; totalMs: number }>();
 	#lineGauges = new Map<string, LineCountGauge>();
+	#structuralCounters = new Map<string, number>();
 	#rssReturn: number | null = null;
 	#heapBaseline: number | null = null;
 	#heapReturn: number | null = null;
@@ -200,6 +202,7 @@ export class RenderMetrics {
 		this.#timerGauges.clear();
 		this.#helpers.clear();
 		this.#lineGauges.clear();
+		this.#structuralCounters.clear();
 		this.#rssReturn = null;
 		this.#heapBaseline = null;
 		this.#heapReturn = null;
@@ -296,6 +299,13 @@ export class RenderMetrics {
 		this.#lineGauges.set(retained, cur);
 	}
 
+	/** Accumulate deterministic structural render work without retaining frame data. */
+	recordStructuralCounter(name: string, value = 1): void {
+		if (!this.#enabled) return;
+		const retained = retainedLabel(this.#structuralCounters, name);
+		this.#structuralCounters.set(retained, (this.#structuralCounters.get(retained) ?? 0) + value);
+	}
+
 	/**
 	 * Force a GC when the runtime exposes one and sample RSS as the post-run
 	 * "return" value used by the memory-leak gate. Callers should drop large
@@ -345,6 +355,10 @@ export class RenderMetrics {
 		return out;
 	}
 
+	#structuralCounterStats(): Record<string, number> {
+		return Object.fromEntries(this.#structuralCounters);
+	}
+
 	snapshot(): RenderMetricsSnapshot {
 		return {
 			enabled: this.#enabled,
@@ -374,6 +388,7 @@ export class RenderMetrics {
 			timerGauges: Object.fromEntries(this.#timerGauges),
 			helperStats: this.#helperStats(),
 			lineCounts: this.#lineCountStats(),
+			structuralCounters: this.#structuralCounterStats(),
 		};
 	}
 }

package/src/stdin-buffer.ts

@@ -26,6 +26,25 @@ const BRACKETED_PASTE_END = "\x1b[201~";
 const SGR_QUARANTINE_MAX_BYTES = 256;
 const SGR_QUARANTINE_TIMEOUT_MS = 100;
 
+// Bounds for holding an incomplete terminal capability-probe reply instead of
+// flushing its fragments into the input stream.
+const PROBE_FRAGMENT_HOLD_MAX_MS = 500;
+const PROBE_FRAGMENT_MAX_BYTES = 256;
+const PROBE_ESCAPE_HOLD_MAX_MS = 150;
+const PROBE_REPLY_WINDOW_MS = 2500;
+
+/**
+ * True when the buffer is an escape sequence that only a terminal reply can
+ * complete: an OSC without its BEL/ST terminator (OSC 11 background color) or a
+ * private CSI without its final byte (DA1, kitty flags, Mode 2031 DSR).
+ * SGR mouse prefixes are excluded; they have their own quarantine.
+ */
+function isIncompleteProbeReplyPrefix(buffer: string): boolean {
+	if (buffer.length > PROBE_FRAGMENT_MAX_BYTES) return false;
+	if (/^\x1b\][^\x07\x1b]*$/.test(buffer)) return true;
+	return /^\x1b\[\??[\d;]*$/.test(buffer);
+}
+
 /** True for complete SGR mouse CSI reports. These remain control input, never text. */
 export function isSgrMouseSequence(sequence: string): boolean {
 	return /^\x1b\[<\d+;\d+;\d+[Mm]$/.test(sequence);
@@ -238,6 +257,19 @@ function parseUnmodifiedKittyPrintableCodepoint(sequence: string): number | unde
 	return codepoint >= 32 ? codepoint : undefined;
 }
 
+/**
+ * True when the ESC at `index` can still continue the escape sequence that
+ * started at offset 0, i.e. it is (or may become) the ST terminator `ESC \` of
+ * an OSC/DCS/APC string. Anywhere else an ESC cancels the sequence in progress.
+ */
+function continuesAsStringTerminator(remaining: string, index: number): boolean {
+	const introducer = remaining[1];
+	if (introducer !== "]" && introducer !== "P" && introducer !== "_") return false;
+	const afterEsc = remaining[index + 1];
+	// Terminator not fully delivered yet: keep buffering rather than guessing.
+	return afterEsc === undefined || afterEsc === "\\";
+}
+
 function extractCompleteSequences(buffer: string): { sequences: string[]; remainder: string } {
 	const sequences: string[] = [];
 	let pos = 0;
@@ -270,6 +302,15 @@ function extractCompleteSequences(buffer: string): { sequences: string[]; remain
 					pos += seqEnd;
 					break;
 				} else if (status === "incomplete") {
+					// An ESC cancels an escape sequence already in progress; it can only
+					// continue one as the ST terminator of an OSC/DCS/APC string. Cutting
+					// here keeps an unterminated sequence from swallowing the next key.
+					// seqEnd === 1 is excluded so Meta sequences (ESC ESC) still parse.
+					if (remaining[seqEnd] === ESC && seqEnd >= 2 && !continuesAsStringTerminator(remaining, seqEnd)) {
+						sequences.push(candidate);
+						pos += seqEnd;
+						break;
+					}
 					seqEnd++;
 				} else {
 					// Should not happen when starting with ESC
@@ -346,6 +387,10 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 	#sgrQuarantineBytes = 0;
 	#sgrQuarantineSemicolons = 0;
 	#sgrQuarantineHasDigit = false;
+	// Probe-reply fragment hold.
+	#probeHoldStartedAt: number | undefined;
+	#probeHoldBuffer = "";
+	#probeReplyWindowUntil = 0;
 
 	constructor(options: StdinBufferOptions = {}) {
 		super();
@@ -497,17 +542,10 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 			this.#emitDataSequence(sequence);
 		}
 
-		if (this.#buffer.length > 0) {
-			this.#timeout = setTimeout(() => {
-				if (isSgrMousePrefix(this.#buffer)) {
-					this.#beginSgrQuarantine();
-					return;
-				}
-				const flushed = this.flush();
-				for (const sequence of flushed) {
-					this.#emitDataSequence(sequence);
-				}
-			}, this.#timeoutMs);
+		if (this.#buffer.length === 0) {
+			this.#probeHoldStartedAt = undefined;
+		} else {
+			this.#timeout = setTimeout(() => this.#onFlushTimeout(), this.#timeoutMs);
 		}
 	}
 
@@ -599,12 +637,61 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		this.emit("data", sequence);
 	}
 
+	/**
+	 * ProcessTerminal calls this right after writing a capability probe so a lone
+	 * ESC arriving inside the reply window is treated as a possible reply fragment
+	 * rather than a keypress.
+	 */
+	noteProbeIssued(windowMs: number = PROBE_REPLY_WINDOW_MS): void {
+		this.#probeReplyWindowUntil = Date.now() + windowMs;
+	}
+
+	#onFlushTimeout(): void {
+		if (isSgrMousePrefix(this.#buffer)) {
+			this.#beginSgrQuarantine();
+			return;
+		}
+		if (this.#shouldHoldProbeFragment()) {
+			this.#timeout = setTimeout(() => this.#onFlushTimeout(), this.#timeoutMs);
+			return;
+		}
+		this.#probeHoldStartedAt = undefined;
+		const flushed = this.flush();
+		for (const sequence of flushed) {
+			this.#emitDataSequence(sequence);
+		}
+	}
+
+	#shouldHoldProbeFragment(): boolean {
+		const buffer = this.#buffer;
+		if (buffer.length === 0) return false;
+		const now = Date.now();
+		const bareEscape = buffer === "\x1b";
+		if (bareEscape) {
+			// A lone ESC is a real key press: only hold it while a probe reply is
+			// still expected, and only briefly.
+			if (now >= this.#probeReplyWindowUntil) return false;
+		} else if (!isIncompleteProbeReplyPrefix(buffer)) {
+			return false;
+		}
+		if (this.#probeHoldStartedAt === undefined || this.#probeHoldBuffer !== buffer) {
+			// Restart the clock whenever the fragment makes progress. A start stamp left
+			// over from an earlier fragment expired every later hold instantly, so a
+			// reply split across many reads still leaked character by character.
+			this.#probeHoldStartedAt = now;
+			this.#probeHoldBuffer = buffer;
+		}
+		const limit = bareEscape ? PROBE_ESCAPE_HOLD_MAX_MS : PROBE_FRAGMENT_HOLD_MAX_MS;
+		return now - this.#probeHoldStartedAt < limit;
+	}
+
 	flush(): string[] {
 		if (this.#timeout) {
 			clearTimeout(this.#timeout);
 			this.#timeout = undefined;
 		}
 		if (this.#sgrQuarantine) this.#endSgrQuarantine();
+		this.#probeHoldStartedAt = undefined;
 
 		const pendingMeta = this.#consumePendingSingleUtf8LeadAsMeta();
 
@@ -637,6 +724,7 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 		this.#sgrQuarantineBytes = 0;
 		this.#sgrQuarantineSemicolons = 0;
 		this.#sgrQuarantineHasDigit = false;
+		this.#probeHoldStartedAt = undefined;
 		// Drop any incomplete multi-byte sequence the decoder is holding so a
 		// stale partial prefix cannot combine with future input. destroy()
 		// resets the decoder by calling clear().

package/src/terminal-capabilities.ts

@@ -514,6 +514,68 @@ export function encodeKittyPlacement(options: {
 	return `\x1b_Ga=p,i=${options.imageId},p=${options.placementId},c=${options.columns},r=${options.rows},C=1,q=2\x1b\\`;
 }
 
+export interface KittyPlacementReference {
+	imageId: number;
+	placementId: number;
+	rows: number;
+}
+
+const MAX_KITTY_CONTROL_CHARS = 4096;
+const MAX_KITTY_PLACEMENTS_PER_LINE = 1024;
+const MAX_KITTY_PLACEMENT_SCAN_CHARS = 256 * 1024;
+const MAX_KITTY_PLACEMENT_SCAN_BYTES = 256 * 1024;
+const MAX_KITTY_UINT32 = 0xffff_ffff;
+const MAX_KITTY_CONTROL_FIELDS = 64;
+
+function parseKittyUint32(raw: string | undefined): number | null {
+	if (raw === undefined || raw.length === 0 || raw.length > 10 || !/^\d+$/u.test(raw)) return null;
+	const value = Number(raw);
+	return Number.isInteger(value) && value > 0 && value <= MAX_KITTY_UINT32 ? value : null;
+}
+
+/** Extract bounded, named kitty placements from a rendered line. */
+export function extractKittyPlacementReferences(line: string): KittyPlacementReference[] {
+	if (line.length > MAX_KITTY_PLACEMENT_SCAN_CHARS) return [];
+	if (!line.includes(ImageProtocol.Kitty) || Buffer.byteLength(line) > MAX_KITTY_PLACEMENT_SCAN_BYTES) return [];
+	const placements: KittyPlacementReference[] = [];
+	for (const match of line.matchAll(/\x1b_G([^;\x1b]*)(?:;([^\x1b]*))?\x1b\\/gu)) {
+		const control = match[1] ?? "";
+		if (control.length === 0 || control.length > MAX_KITTY_CONTROL_CHARS || match[2] !== undefined) continue;
+		const parts = control.split(",");
+		if (parts.length > MAX_KITTY_CONTROL_FIELDS) continue;
+
+		const params = new Map<string, string>();
+		let valid = true;
+		for (const part of parts) {
+			const separator = part.indexOf("=");
+			if (separator !== 1 || part.length === 2) {
+				valid = false;
+				break;
+			}
+			const key = part[0];
+			if (!/[A-Za-z]/u.test(key) || params.has(key)) {
+				valid = false;
+				break;
+			}
+			params.set(key, part.slice(2));
+		}
+		if (!valid || params.get("a") !== "p" || params.get("C") !== "1" || params.has("m")) continue;
+
+		const imageId = parseKittyUint32(params.get("i"));
+		const placementId = parseKittyUint32(params.get("p"));
+		const rows = parseKittyUint32(params.get("r"));
+		if (imageId === null || placementId === null || rows === null) continue;
+		placements.push({ imageId, placementId, rows });
+		if (placements.length > MAX_KITTY_PLACEMENTS_PER_LINE) return [];
+	}
+	return placements;
+}
+
+/** Soft-delete one named kitty placement while retaining its transmitted pixels. */
+export function encodeKittyPlacementDelete(reference: KittyPlacementReference): string {
+	return `\x1b_Ga=d,d=i,i=${reference.imageId},p=${reference.placementId},q=2\x1b\\`;
+}
+
 export function encodeITerm2(
 	base64Data: string,
 	options: {
@@ -755,8 +817,8 @@ export function renderImage(
 		// and ALL of its placements (breaking sibling components showing the
 		// same content) and would re-send multi-MB payloads on every repaint.
 		if (!transmittedKittyImageIds.has(imageId)) {
-			transmittedKittyImageIds.add(imageId);
 			(options.onTransmit ?? kittyTransmitWriter)(encodeKittyTransmit(base64Data, imageId));
+			transmittedKittyImageIds.add(imageId);
 		}
 		const sequence = encodeKittyPlacement({ imageId, placementId, columns: fit.columns, rows: fit.rows });
 		return { sequence, rows: fit.rows, cursorNeutral: true };