@oh-my-pi/pi-tui 16.0.3 → 16.0.5

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [16.0.5] - 2026-06-17
+
+### Added
+
+- Added tight layout support (`setTuiTight`/`getPaddingX`) to dynamically remove 1-character horizontal padding from Text, Markdown, Box, and TruncatedText components.
+
+### Changed
+
+- Coalesced byte-adjacent SGR sequences in emitted lines into a single `CSI … m`. The component tree styles each span as `<set>text<reset>`, so adjacent spans emit runs of back-to-back SGR sequences (e.g. a `CSI 39 m` fg-reset immediately followed by the next span's `CSI 38;2;r;g;b m`); merging the run is behavior-preserving because SGR parameters apply left-to-right regardless of framing. On a real transcript this drops ~30-40% of all SGR sequences, cutting the per-frame byte volume and SGR-dispatch count a slow terminal engine (e.g. xterm.js/WebGL under a large viewport) must process. Each emitted sequence is capped at 16 parameter tokens so a long adjacent run is split across several valid CSIs instead of overflowing a terminal's parameter buffer (xterm.js caps at 32 and silently truncates, corrupting colors). A run is never extended past a parameter list that ends in an incomplete semicolon-form extended color (`38/48/58;2` missing a channel or `;5` missing the index), so a following code can't be absorbed as the missing component. Disable with `PI_NO_SGR_COALESCE=1`.
+
+### Fixed
+
+- Fixed image cache invalidation when terminal image protocol, Kitty placeholder mode, or cell dimensions change, preventing stale rendered output
+- Fixed direct inline-image placements leaving the cursor inside the reserved image block, which let following chat rows overwrite the middle of rendered screenshots ([#2863](https://github.com/can1357/oh-my-pi/issues/2863)).
+- Fixed inline-image replay after startup or resume fallback paints by invalidating cached image rows when the terminal image protocol, Kitty placeholder mode, or cell dimensions change.
+
 ## [16.0.3] - 2026-06-16
 
 ### Added

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

@@ -5,6 +5,7 @@ import type { Component } from "../tui";
 export declare class Box implements Component {
     #private;
     children: Component[];
+    setIgnoreTight(ignore: boolean): this;
     constructor(paddingX?: number, paddingY?: number, bgFn?: (text: string) => string);
     addChild(component: Component): void;
     removeChild(component: Component): void;

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

@@ -94,6 +94,15 @@ export declare class ImageBudget {
     get quiescent(): boolean;
     /** Transmit sequences to write before this frame's placements; clears the queue. */
     takeTransmits(): readonly string[];
+    /**
+     * Drop transmit tracking so every still-live image re-enqueues its data
+     * (`a=t`) on the next render. Recovers when the terminal dropped the original
+     * transmit — e.g. Ghostty discarding graphics sent during its post-startup
+     * window — where a placement-only replay can never bind a Unicode placeholder.
+     * Pair with a component invalidate + forced repaint so the data and placement
+     * re-emit together; keeps no base64 in budget state (the transmit-once design).
+     */
+    forgetTransmitted(): void;
 }
 export declare class Image implements Component {
     #private;

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

@@ -49,6 +49,7 @@ export interface MarkdownTheme {
 }
 export declare class Markdown implements Component {
     #private;
+    setIgnoreTight(ignore: boolean): this;
     constructor(text: string, paddingX: number, paddingY: number, theme: MarkdownTheme, defaultTextStyle?: DefaultTextStyle, codeBlockIndent?: number);
     setText(text: string): void;
     invalidate(): void;

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

@@ -4,6 +4,7 @@ import type { Component } from "../tui";
  */
 export declare class Text implements Component {
     #private;
+    setIgnoreTight(ignore: boolean): this;
     constructor(text?: string, paddingX?: number, paddingY?: number, customBgFn?: (text: string) => string);
     getText(): string;
     setText(text: string): boolean;

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

@@ -191,10 +191,12 @@ export declare function encodeKitty(base64Data: string, options?: {
  */
 export declare function encodeKittyTransmit(base64Data: string, imageId: number): string;
 /**
- * Display a previously transmitted image (`a=p`) at the cursor. Carrying a
- * stable `placementId` (`p=`) means re-emitting the sequence on a repaint
- * *replaces* the existing placement (moving/resizing it without flicker) rather
- * than stacking a duplicate.
+ * Display a previously transmitted image (`a=p`) at the cursor. `C=1` keeps
+ * the terminal cursor anchored at the placement origin so the renderer's
+ * explicit cursor movement remains the only row accounting. Carrying a stable
+ * `placementId` (`p=`) means re-emitting the sequence on a repaint *replaces*
+ * the existing placement (moving/resizing it without flicker) rather than
+ * stacking a duplicate.
  */
 export declare function encodeKittyPlacement(options: {
     imageId: number;

package/dist/types/tui.d.ts

@@ -58,6 +58,10 @@ export interface Component {
      * Called when theme changes or when component needs to re-render from scratch.
      */
     invalidate?(): void;
+    /**
+     * Optional hook to set whether this component ignores tight layout mode.
+     */
+    setIgnoreTight?(ignore: boolean): any;
     /**
      * Optional teardown. Called when the component is permanently removed from
      * the live tree (e.g. a transcript reset). Release timers, intervals, and
@@ -265,6 +269,7 @@ export interface OverlayHandle {
 export declare class Container implements Component {
     #private;
     children: Component[];
+    setIgnoreTight(ignore: boolean): this;
     addChild(component: Component): void;
     removeChild(component: Component): void;
     clear(): void;
@@ -277,6 +282,13 @@ export declare class Container implements Component {
     dispose(): void;
     render(width: number): readonly string[];
 }
+/**
+ * Merge runs of byte-adjacent SGR sequences (`CSI [0-9;:]* m`) into one. Only
+ * CSI-SGR sequences are touched; text, cursor moves, OSC, hyperlinks and image
+ * payloads pass through verbatim. Returns the original reference when nothing
+ * merges, so SGR-light lines incur only a single `indexOf` scan.
+ */
+export declare function coalesceAdjacentSgr(line: string): string;
 /**
  * Decide whether `frame` still aligns with the committed prefix, and where to
  * re-anchor the commit index when it does not. Returns the resync row index,

package/dist/types/utils.d.ts

@@ -90,3 +90,6 @@ export declare function applyBackgroundToLine(line: string, width: number, bgFn:
  * @param strict - If true, exclude wide chars at boundary that would extend past the range
  */
 export declare function sliceByColumn(line: string, startCol: number, length: number, strict?: boolean): string;
+export declare function setTuiTight(tight: boolean): void;
+export declare function isTuiTight(): boolean;
+export declare function getPaddingX(basePadding: number): number;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "16.0.3",
+	"version": "16.0.5",
 	"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": "16.0.3",
-		"@oh-my-pi/pi-utils": "16.0.3",
+		"@oh-my-pi/pi-natives": "16.0.5",
+		"@oh-my-pi/pi-utils": "16.0.5",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.5"
 	},

package/src/components/box.ts

@@ -1,5 +1,5 @@
 import type { Component } from "../tui";
-import { applyBackgroundToLine, padding, visibleWidth } from "../utils";
+import { applyBackgroundToLine, getPaddingX, padding, visibleWidth } from "../utils";
 
 type Cache = {
 	width: number;
@@ -17,6 +17,14 @@ export class Box implements Component {
 	#paddingY: number;
 	#bgFn?: (text: string) => string;
 
+	#ignoreTight = false;
+
+	setIgnoreTight(ignore: boolean): this {
+		this.#ignoreTight = ignore;
+		this.#invalidateCache();
+		return this;
+	}
+
 	// Cache for rendered output
 	#cached?: Cache;
 
@@ -28,6 +36,9 @@ export class Box implements Component {
 
 	addChild(component: Component): void {
 		this.children.push(component);
+		if (this.#ignoreTight) {
+			component.setIgnoreTight?.(true);
+		}
 		this.#invalidateCache();
 	}
 
@@ -75,7 +86,8 @@ export class Box implements Component {
 	render(width: number): readonly string[] {
 		const children = this.children;
 		const count = children.length;
-		const contentWidth = Math.max(1, width - this.#paddingX * 2);
+		const paddingX = this.#ignoreTight ? this.#paddingX : getPaddingX(this.#paddingX);
+		const contentWidth = Math.max(1, width - paddingX * 2);
 		// bgFn output can change without the function reference changing (theme
 		// mutation); sample it so a silent palette swap still misses the cache.
 		const bgSample = this.#bgFn ? this.#bgFn("test") : undefined;
@@ -102,7 +114,7 @@ export class Box implements Component {
 
 		const result: string[] = [];
 		if (contentRows > 0) {
-			const leftPad = padding(this.#paddingX);
+			const leftPad = padding(paddingX);
 			// Top padding
 			for (let i = 0; i < this.#paddingY; i++) {
 				result.push(this.#applyBg("", width));

package/src/components/image.ts

@@ -1,4 +1,6 @@
+import { getKittyGraphics } from "../kitty-graphics";
 import {
+	getCellDimensions,
 	getImageDimensions,
 	type ImageDimensions,
 	imageFallback,
@@ -27,6 +29,8 @@ export interface ImageOptions {
 
 const EMPTY_IDS: readonly number[] = [];
 const EMPTY_TRANSMITS: readonly string[] = [];
+const SAVE_CURSOR = "\x1b7";
+const RESTORE_CURSOR = "\x1b8";
 // Direct placements reserve height with leading zero-width rows. Keep them
 // non-plain so transcript blank-edge trimming does not collapse image-only blocks.
 const RESERVED_IMAGE_ROW = "\x1b[0m";
@@ -34,6 +38,11 @@ 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;
 
+let nextImageBudgetSeed = Math.floor(Math.random() * 0xffffff);
+function nextImageIdSeed(): number {
+	nextImageBudgetSeed = (nextImageBudgetSeed + 0x10000) & 0xffffff;
+	return nextImageBudgetSeed || 1;
+}
 /**
  * Bounds how many inline images render as live terminal graphics at once.
  *
@@ -54,7 +63,7 @@ export const DEFAULT_MAX_INLINE_IMAGES = 8;
 export class ImageBudget {
 	#cap: number;
 	#requestRender: () => void;
-	#nextId = 1;
+	#nextId = nextImageIdSeed();
 	#keyToId = new Map<string, number>();
 	/** Display-order image ids observed during the in-flight pass. */
 	#passIds: number[] = [];
@@ -120,11 +129,14 @@ export class ImageBudget {
 		if (key) {
 			const existing = this.#keyToId.get(key);
 			if (existing !== undefined) return existing;
-			const id = this.#nextId++;
+			const id = this.#nextId;
+			this.#nextId = (this.#nextId + 1) & 0xffffff || 1;
 			this.#keyToId.set(key, id);
 			return id;
 		}
-		return this.#nextId++;
+		const id = this.#nextId;
+		this.#nextId = (this.#nextId + 1) & 0xffffff || 1;
+		return id;
 	}
 
 	/**
@@ -248,6 +260,20 @@ export class ImageBudget {
 		return sequences;
 	}
 
+	/**
+	 * Drop transmit tracking so every still-live image re-enqueues its data
+	 * (`a=t`) on the next render. Recovers when the terminal dropped the original
+	 * transmit — e.g. Ghostty discarding graphics sent during its post-startup
+	 * window — where a placement-only replay can never bind a Unicode placeholder.
+	 * Pair with a component invalidate + forced repaint so the data and placement
+	 * re-emit together; keeps no base64 in budget state (the transmit-once design).
+	 */
+	forgetTransmitted(): void {
+		if (this.#transmitted.size === 0 && this.#pendingTransmits.length === 0) return;
+		this.#transmitted.clear();
+		this.#pendingTransmits = [];
+	}
+
 	#reconcile(total: number): void {
 		const desired = this.#cap > 0 ? Math.max(0, total - this.#cap) : 0;
 		if (desired === this.#planned) {
@@ -284,6 +310,10 @@ export class Image implements Component {
 	#cachedLines?: string[];
 	#cachedWidth?: number;
 	#cachedSuppressed = false;
+	#cachedImageProtocol: typeof TERMINAL.imageProtocol = null;
+	#cachedCellWidthPx = 0;
+	#cachedCellHeightPx = 0;
+	#cachedKittyUnicodePlaceholders = false;
 	// Tallest graphic placement this image has rendered. The text fallback
 	// pads itself to this height so a budget demotion never shrinks the block
 	// (its rows may already be committed to native scrollback).
@@ -311,14 +341,25 @@ export class Image implements Component {
 	}
 
 	render(width: number): readonly string[] {
-		const hasProtocol = TERMINAL.imageProtocol != null;
+		const imageProtocol = TERMINAL.imageProtocol;
+		const hasProtocol = imageProtocol != null;
+		const cellDimensions = getCellDimensions();
+		const kittyUnicodePlaceholders = getKittyGraphics().unicodePlaceholders;
 		// observe() must run on every pass — even a cache hit — so the image keeps
 		// its display-order slot in the budget. Only graphics-capable frames count
 		// toward (and are demoted by) the budget; without a protocol every image is
 		// already text.
 		const suppressed = hasProtocol && this.#budget !== undefined ? this.#budget.observe(this.#imageId ?? 0) : false;
 
-		if (this.#cachedLines && this.#cachedWidth === width && this.#cachedSuppressed === suppressed) {
+		if (
+			this.#cachedLines &&
+			this.#cachedWidth === width &&
+			this.#cachedSuppressed === suppressed &&
+			this.#cachedImageProtocol === imageProtocol &&
+			this.#cachedCellWidthPx === cellDimensions.widthPx &&
+			this.#cachedCellHeightPx === cellDimensions.heightPx &&
+			this.#cachedKittyUnicodePlaceholders === kittyUnicodePlaceholders
+		) {
 			return this.#cachedLines;
 		}
 
@@ -349,13 +390,18 @@ export class Image implements Component {
 			} else if (result) {
 				// Direct placement: return `rows` lines so TUI accounts for image
 				// height. First (rows-1) lines are empty (TUI clears them); the last
-				// moves the cursor back up, then emits the image sequence.
+				// 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.
 				lines = [];
 				for (let i = 0; i < result.rows - 1; i++) {
 					lines.push(RESERVED_IMAGE_ROW);
 				}
-				const moveUp = result.rows > 1 ? `\x1b[${result.rows - 1}A` : "";
-				lines.push(moveUp + (result.sequence ?? ""));
+				const cursorRows = result.rows - 1;
+				const moveUp = cursorRows > 0 ? `\x1b[${cursorRows}A` : "";
+				const placement = moveUp + (result.sequence ?? "");
+				lines.push(cursorRows > 0 ? SAVE_CURSOR + placement + RESTORE_CURSOR : placement);
 			} else {
 				lines = this.#fallbackLines();
 			}
@@ -367,6 +413,10 @@ export class Image implements Component {
 		this.#cachedLines = lines;
 		this.#cachedWidth = width;
 		this.#cachedSuppressed = suppressed;
+		this.#cachedImageProtocol = imageProtocol;
+		this.#cachedCellWidthPx = cellDimensions.widthPx;
+		this.#cachedCellHeightPx = cellDimensions.heightPx;
+		this.#cachedKittyUnicodePlaceholders = kittyUnicodePlaceholders;
 
 		return lines;
 	}

package/src/components/markdown.ts

@@ -9,6 +9,7 @@ import {
 	applyBackgroundToLine,
 	Ellipsis,
 	encodeTextSized,
+	getPaddingX,
 	getSegmenter,
 	padding,
 	replaceTabs,
@@ -475,6 +476,14 @@ export class Markdown implements Component {
 	#streamPrefixText?: string;
 	#streamPrefixTokens?: Token[];
 
+	#ignoreTight = false;
+
+	setIgnoreTight(ignore: boolean): this {
+		this.#ignoreTight = ignore;
+		this.invalidate();
+		return this;
+	}
+
 	constructor(
 		text: string,
 		paddingX: number,
@@ -599,7 +608,8 @@ export class Markdown implements Component {
 		}
 
 		// Calculate available width for content (subtract horizontal padding)
-		const contentWidth = Math.max(1, width - this.#paddingX * 2);
+		const paddingX = this.#ignoreTight ? this.#paddingX : getPaddingX(this.#paddingX);
+		const contentWidth = Math.max(1, width - paddingX * 2);
 
 		// Don't render anything if there's no actual text
 		if (!this.#text || this.#text.trim() === "") {
@@ -628,7 +638,7 @@ export class Markdown implements Component {
 		if (!this.transientRenderCache) {
 			const bgColorProbe = this.#defaultTextStyle?.bgColor ? this.#defaultTextStyle.bgColor("\x01") : "";
 			const headingProbe = this.#theme.heading("");
-			cacheKey = `${normalizedText}\x00${width}\x00${this.#paddingX}\x00${this.#paddingY}\x00${this.#codeBlockIndent}\x00${objectId(this.#theme)}\x00${this.#defaultTextStyle ? objectId(this.#defaultTextStyle) : -1}\x00${TERMINAL.imageProtocol ?? ""}\x00${TERMINAL.hyperlinks ? 1 : 0}\x00${TERMINAL.textSizing ? 1 : 0}\x00${bgColorProbe}\x00${headingProbe}`;
+			cacheKey = `${normalizedText}\x00${width}\x00${paddingX}\x00${this.#paddingY}\x00${this.#codeBlockIndent}\x00${objectId(this.#theme)}\x00${this.#defaultTextStyle ? objectId(this.#defaultTextStyle) : -1}\x00${TERMINAL.imageProtocol ?? ""}\x00${TERMINAL.hyperlinks ? 1 : 0}\x00${TERMINAL.textSizing ? 1 : 0}\x00${bgColorProbe}\x00${headingProbe}`;
 			const cached = renderCache.get(cacheKey);
 			if (cached !== undefined) {
 				// Populate L1 so subsequent calls from this instance are O(1) map lookup.
@@ -665,8 +675,8 @@ export class Markdown implements Component {
 		}
 
 		// Add margins and background to each wrapped line
-		const leftMargin = padding(this.#paddingX);
-		const rightMargin = padding(this.#paddingX);
+		const leftMargin = padding(paddingX);
+		const rightMargin = padding(paddingX);
 		const bgFn = this.#defaultTextStyle?.bgColor;
 		const contentLines: string[] = [];
 

package/src/components/text.ts

@@ -1,5 +1,5 @@
 import type { Component } from "../tui";
-import { applyBackgroundToLine, padding, replaceTabs, visibleWidth, wrapTextWithAnsi } from "../utils";
+import { applyBackgroundToLine, getPaddingX, padding, replaceTabs, visibleWidth, wrapTextWithAnsi } from "../utils";
 
 /**
  * Text component - displays multi-line text with word wrapping
@@ -10,6 +10,14 @@ export class Text implements Component {
 	#paddingY: number; // Top/bottom padding
 	#customBgFn?: (text: string) => string;
 
+	#ignoreTight = false;
+
+	setIgnoreTight(ignore: boolean): this {
+		this.#ignoreTight = ignore;
+		this.invalidate();
+		return this;
+	}
+
 	// Cache for rendered output
 	#cachedText?: string;
 	#cachedWidth?: number;
@@ -69,14 +77,14 @@ export class Text implements Component {
 		const normalizedText = replaceTabs(this.#text);
 
 		// Calculate content width (subtract left/right margins)
-		const contentWidth = Math.max(1, width - this.#paddingX * 2);
-
+		const paddingX = this.#ignoreTight ? this.#paddingX : getPaddingX(this.#paddingX);
+		const contentWidth = Math.max(1, width - paddingX * 2);
 		// Wrap text (this preserves ANSI codes but does NOT pad)
 		const wrappedLines = wrapTextWithAnsi(normalizedText, contentWidth);
 
 		// Add margins and background to each line
-		const leftMargin = padding(this.#paddingX);
-		const rightMargin = padding(this.#paddingX);
+		const leftMargin = padding(paddingX);
+		const rightMargin = padding(paddingX);
 		const contentLines: string[] = [];
 
 		for (const line of wrappedLines) {

package/src/terminal-capabilities.ts

@@ -544,7 +544,7 @@ export function encodeKitty(
 		imageId?: number;
 	} = {},
 ): string {
-	const params: string[] = ["a=T", "f=100", "q=2"];
+	const params: string[] = ["a=T", "f=100", "q=2", "C=1"];
 	if (options.columns) params.push(`c=${options.columns}`);
 	if (options.rows) params.push(`r=${options.rows}`);
 	if (options.imageId) params.push(`i=${options.imageId}`);
@@ -563,10 +563,12 @@ export function encodeKittyTransmit(base64Data: string, imageId: number): string
 }
 
 /**
- * Display a previously transmitted image (`a=p`) at the cursor. Carrying a
- * stable `placementId` (`p=`) means re-emitting the sequence on a repaint
- * *replaces* the existing placement (moving/resizing it without flicker) rather
- * than stacking a duplicate.
+ * Display a previously transmitted image (`a=p`) at the cursor. `C=1` keeps
+ * the terminal cursor anchored at the placement origin so the renderer's
+ * explicit cursor movement remains the only row accounting. Carrying a stable
+ * `placementId` (`p=`) means re-emitting the sequence on a repaint *replaces*
+ * the existing placement (moving/resizing it without flicker) rather than
+ * stacking a duplicate.
  */
 export function encodeKittyPlacement(options: {
 	imageId: number;
@@ -574,7 +576,7 @@ export function encodeKittyPlacement(options: {
 	columns?: number;
 	rows?: number;
 }): string {
-	const params: string[] = ["a=p", "q=2", `i=${options.imageId}`];
+	const params: string[] = ["a=p", "q=2", "C=1", `i=${options.imageId}`];
 	if (options.placementId) params.push(`p=${options.placementId}`);
 	if (options.columns) params.push(`c=${options.columns}`);
 	if (options.rows) params.push(`r=${options.rows}`);

package/src/tui.ts

@@ -161,6 +161,10 @@ export interface Component {
 	 * Called when theme changes or when component needs to re-render from scratch.
 	 */
 	invalidate?(): void;
+	/**
+	 * Optional hook to set whether this component ignores tight layout mode.
+	 */
+	setIgnoreTight?(ignore: boolean): any;
 
 	/**
 	 * Optional teardown. Called when the component is permanently removed from
@@ -505,8 +509,22 @@ export class Container implements Component {
 	#memoChildLines: (readonly string[])[] = [];
 	#memoWidth = -1;
 
+	#ignoreTight = false;
+
+	setIgnoreTight(ignore: boolean): this {
+		this.#ignoreTight = ignore;
+		for (const child of this.children) {
+			child.setIgnoreTight?.(ignore);
+		}
+		this.invalidate();
+		return this;
+	}
+
 	addChild(component: Component): void {
 		this.children.push(component);
+		if (this.#ignoreTight) {
+			component.setIgnoreTight?.(true);
+		}
 		this.#memoLines = undefined;
 	}
 
@@ -640,6 +658,139 @@ interface PreparedLine {
 
 const SGR_SEQUENCE = /\x1b\[[0-9;:]*m/g;
 
+// SGR coalescing. The renderer's component tree emits a styled span as
+// `<set-color>text<reset>`, so adjacent spans produce runs of byte-adjacent
+// SGR sequences (e.g. a `CSI 39 m` fg-reset immediately followed by the next
+// span's `CSI 38;2;r;g;b m`). Two byte-adjacent SGR sequences are semantically
+// identical to one SGR carrying both parameter lists (SGR params apply
+// left-to-right), so merging the run into a single `CSI … m` is
+// behavior-preserving: it drops the redundant `ESC[`/`m` framing and lets the
+// terminal dispatch one SGR instead of several. On a real transcript ~40% of
+// all SGR sequences are collapsible this way, which meaningfully cuts the
+// per-frame byte volume and SGR-dispatch count a slow (xterm.js/WebGL) terminal
+// must process. On by default; `PI_NO_SGR_COALESCE=1` disables it.
+const SGR_COALESCE_ENABLED = !$flag("PI_NO_SGR_COALESCE");
+const CC_ESC = 0x1b;
+const CC_BRACKET = 0x5b; // [
+const CC_M = 0x6d; // m
+const CC_SEMI = 0x3b; // ;
+const CC_COLON = 0x3a; // :
+// Max parameter tokens per emitted merged SGR. Kept well under xterm.js's
+// 32-param cap (and the tighter limits of some real terminals) so a long
+// adjacent run is split into several valid CSIs instead of overflowing one.
+const MERGE_TOKEN_CAP = 16;
+
+function isSgrParamByte(c: number): boolean {
+	return (c >= 0x30 && c <= 0x39) || c === CC_SEMI || c === CC_COLON;
+}
+
+// True when a parameter list ends mid extended-color spec in the ambiguous
+// semicolon form: `38/48/58;2` with fewer than three channel values, or
+// `38/48/58;5` with no palette index. Concatenating another list after such a
+// run would let the next code be absorbed as the missing channel/index (e.g.
+// `38;2;255;0` + `31` → `38;2;255;0;31`, where `31` becomes blue instead of a
+// standalone fg-red), changing the rendered color. The self-delimiting colon
+// form (`38:2::r:g:b`) is unambiguous — its tokens never equal a bare `38`, so
+// the scan treats it as a complete unit and merging stays safe.
+function endsWithIncompleteExtendedColor(params: string): boolean {
+	const t = params.split(";");
+	let i = 0;
+	while (i < t.length) {
+		const tok = t[i];
+		if (tok === "38" || tok === "48" || tok === "58") {
+			const mode = t[i + 1];
+			if (mode === undefined) return true; // introducer with no mode
+			if (mode === "2") {
+				if (i + 4 >= t.length) return true; // missing r/g/b
+				i += 5;
+				continue;
+			}
+			if (mode === "5") {
+				if (i + 2 >= t.length) return true; // missing index
+				i += 3;
+				continue;
+			}
+		}
+		i += 1;
+	}
+	return false;
+}
+
+/**
+ * Merge runs of byte-adjacent SGR sequences (`CSI [0-9;:]* m`) into one. Only
+ * CSI-SGR sequences are touched; text, cursor moves, OSC, hyperlinks and image
+ * payloads pass through verbatim. Returns the original reference when nothing
+ * merges, so SGR-light lines incur only a single `indexOf` scan.
+ */
+export function coalesceAdjacentSgr(line: string): string {
+	if (!SGR_COALESCE_ENABLED || line.indexOf("\x1b[") === -1) return line;
+	const n = line.length;
+	let out = "";
+	let copiedUpto = 0;
+	let i = 0;
+	while (i < n) {
+		if (line.charCodeAt(i) !== CC_ESC || line.charCodeAt(i + 1) !== CC_BRACKET) {
+			i++;
+			continue;
+		}
+		// Scan a candidate SGR sequence: ESC [ <params> m.
+		let j = i + 2;
+		while (j < n && isSgrParamByte(line.charCodeAt(j))) j++;
+		if (j >= n || line.charCodeAt(j) !== CC_M) {
+			// Not an SGR (e.g. cursor move); leave it in the pending region.
+			i = j;
+			continue;
+		}
+		// Collect the run of adjacent SGR sequences starting here.
+		const params: string[] = [line.slice(i + 2, j)];
+		let k = j + 1;
+		while (k < n && line.charCodeAt(k) === CC_ESC && line.charCodeAt(k + 1) === CC_BRACKET) {
+			let p = k + 2;
+			while (p < n && isSgrParamByte(line.charCodeAt(p))) p++;
+			if (p >= n || line.charCodeAt(p) !== CC_M) break;
+			params.push(line.slice(k + 2, p));
+			k = p + 1;
+		}
+		if (params.length > 1) {
+			out += line.slice(copiedUpto, i);
+			// Emit the merged run, but flush the current group before appending a
+			// list when (a) the previous list ended mid extended-color, so the
+			// next code cannot be absorbed as its missing channel/index, or (b)
+			// the token count would exceed MERGE_TOKEN_CAP. SGR params apply
+			// left-to-right regardless of how they are grouped across adjacent
+			// CSIs, so a capped/guarded split stays behavior-preserving — while a
+			// single unbounded merge would overflow a terminal's CSI parameter
+			// buffer (xterm.js caps at 32 and silently truncates the rest,
+			// corrupting colors). Empty params (`CSI m`) mean a full reset;
+			// normalize to `0` so the merged list stays unambiguous.
+			let group = "";
+			let groupTokens = 0;
+			let groupOpenSafe = true;
+			for (let q = 0; q < params.length; q++) {
+				const norm = params[q]!.length === 0 ? "0" : params[q]!;
+				let tk = 1;
+				for (let z = 0; z < norm.length; z++) {
+					const cc = norm.charCodeAt(z);
+					if (cc === CC_SEMI || cc === CC_COLON) tk++;
+				}
+				if (groupTokens > 0 && (!groupOpenSafe || groupTokens + tk > MERGE_TOKEN_CAP)) {
+					out += `\x1b[${group}m`;
+					group = "";
+					groupTokens = 0;
+				}
+				group += group.length === 0 ? norm : `;${norm}`;
+				groupTokens += tk;
+				groupOpenSafe = !endsWithIncompleteExtendedColor(norm);
+			}
+			if (group.length > 0) out += `\x1b[${group}m`;
+			copiedUpto = k;
+		}
+		i = k;
+	}
+	if (copiedUpto === 0) return line;
+	return out + line.slice(copiedUpto);
+}
+
 /** Compare two rows ignoring SGR styling (theme restyles keep alignment). */
 function rowsEquivalent(a: string, b: string): boolean {
 	if (a === b) return true;
@@ -1218,6 +1369,7 @@ export class TUI extends Container {
 	 * Returns a handle to control the overlay's visibility.
 	 */
 	showOverlay(component: Component, options?: OverlayOptions): OverlayHandle {
+		component.setIgnoreTight?.(true);
 		const entry = { component, options, preFocus: this.#focusedComponent, hidden: false };
 		this.overlayStack.push(entry);
 		// Only focus if overlay is actually visible
@@ -2249,7 +2401,8 @@ export class TUI extends Container {
 
 	#terminalLine(line: string): string {
 		if (TERMINAL.isImageLine(line)) return line;
-		return line + (line.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
+		const coalesced = coalesceAdjacentSgr(line);
+		return coalesced + (line.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
 	}
 
 	/**
@@ -2521,14 +2674,11 @@ export class TUI extends Container {
 		this.#logRedraw(intent, frameLength, height);
 
 		// Load newly-displayed image data once, before this frame's placements
-		// (and any emitter) reference it. `a=t` produces no display, so writing
-		// it ahead of the synchronized paint is artifact-free.
-		const imageTransmits = this.#imageBudget.takeTransmits();
-		if (imageTransmits.length > 0) {
-			let transmitBuffer = "";
-			for (const seq of imageTransmits) transmitBuffer += seq;
-			this.terminal.write(transmitBuffer);
-		}
+		// reference it. For full paints, the emitter may need to place the
+		// transmit after a destructive clear (ED2/ED3) but before row replay, so
+		// build the buffer here and let the emitter decide where it lands.
+		let imageTransmitBuffer = "";
+		for (const seq of this.#imageBudget.takeTransmits()) imageTransmitBuffer += seq;
 		// Purge graphics for images the budget demoted to text. Kitty keeps
 		// images in a store that text clears don't touch; demoted rows still
 		// visible re-render as text and the window diff repaints them.
@@ -2543,7 +2693,7 @@ export class TUI extends Container {
 
 		// 6. Emit.
 		if (intent.kind === "fullPaint") {
-			this.#emitFullPaint(frame, window, width, height, cursorPos, purgeSequence, {
+			this.#emitFullPaint(frame, window, width, height, cursorPos, purgeSequence, imageTransmitBuffer, {
 				clearScrollback: intent.clearScrollback,
 				chunkTo,
 				windowTop,
@@ -2555,6 +2705,9 @@ export class TUI extends Container {
 			if (!firstPaint && frameLength > height) this.#armPostFullPaintSettle();
 			return;
 		}
+		if (imageTransmitBuffer.length > 0) {
+			this.terminal.write(imageTransmitBuffer);
+		}
 		this.#emitUpdate(frame, window, width, height, cursorPos, purgeSequence, {
 			chunkTo,
 			windowTop,
@@ -2909,6 +3062,7 @@ export class TUI extends Container {
 		height: number,
 		cursorPos: { row: number; col: number } | null,
 		purgeSequence: string,
+		imageTransmitBuffer: string,
 		options: { clearScrollback: boolean; chunkTo: number; windowTop: number },
 	): void {
 		this.#fullRedrawCount += 1;
@@ -2925,6 +3079,7 @@ export class TUI extends Container {
 			if (TERMINAL.supportsScreenToScrollback) buffer += "\x1b[22J";
 			buffer += "\x1b[2J\x1b[H";
 		}
+		if (imageTransmitBuffer.length > 0) buffer += imageTransmitBuffer;
 		// DECCARA fills optimize only the rows that stay visible; history-bound
 		// rows are written as full styled strings (their background must
 		// survive in scrollback, which DECCARA cannot reach).

package/src/utils.ts

@@ -482,3 +482,17 @@ export function applyBackgroundToLine(line: string, width: number, bgFn: (text:
 export function sliceByColumn(line: string, startCol: number, length: number, strict = false): string {
 	return sliceWithWidth(line, startCol, length, strict).text;
 }
+
+let globalTight = false;
+
+export function setTuiTight(tight: boolean): void {
+	globalTight = tight;
+}
+
+export function isTuiTight(): boolean {
+	return globalTight;
+}
+
+export function getPaddingX(basePadding: number): number {
+	return globalTight ? Math.max(0, basePadding - 1) : basePadding;
+}