@oh-my-pi/pi-tui 18.2.0 → 18.2.1

package/src/components/image.ts

@@ -57,6 +57,48 @@ interface PlacementEmitState {
 	 */
 	cellsArchived: boolean;
 }
+
+/** A surface the renderer paints frames on. */
+type Surface = "screen" | "alt";
+const SURFACES: readonly Surface[] = ["screen", "alt"];
+
+/**
+ * The live/text split of one drawing surface. The normal screen and the
+ * alternate buffer hold separate frames with separate display orders, so each
+ * carries its own thresholds: a modal's split describes the modal, and applying
+ * it to the transcript would demote — and purge — images the modal never showed.
+ */
+interface SurfaceSplit {
+	/**
+	 * Suppress threshold reflected in the frame currently on this surface: images
+	 * at display indices `[0, onTerminal)` are shown as text there.
+	 */
+	onTerminal: number;
+	/** Suppress threshold the current/next render of this surface should apply. */
+	planned: number;
+	/** Images the last full pass on this surface observed. */
+	lastTotal: number;
+	/**
+	 * Image ids shown as text in the frame currently on this surface: the
+	 * display-order prefix [0, onTerminal) of its last full pass, snapshotted by
+	 * id so a partial pass reproduces the on-screen live/text split without a
+	 * full, correctly-ordered walk.
+	 */
+	suppressedIds: Set<number>;
+}
+
+function newSurfaceSplit(): SurfaceSplit {
+	return { onTerminal: 0, planned: 0, lastTotal: 0, suppressedIds: new Set() };
+}
+
+/** Return a split to "nothing has been painted on this surface yet", in place. */
+function resetSurfaceSplit(split: SurfaceSplit): void {
+	split.onTerminal = 0;
+	split.planned = 0;
+	split.lastTotal = 0;
+	split.suppressedIds = new Set();
+}
+
 let nextImageBudgetSeed = Math.floor(Math.random() * 0xffffff);
 function nextImageIdSeed(): number {
 	nextImageBudgetSeed = (nextImageBudgetSeed + 0x10000) & 0xffffff;
@@ -76,6 +118,16 @@ function nextImageIdSeed(): number {
  * rewritten) plus an explicit graphics purge of the demoted ids. {@link Image}
  * reports display order via {@link observe}; when that reveals a stricter split,
  * the TUI repeats the pass before emitting its terminal frame.
+ * Retired frames no longer observe their images, so the resident store is also
+ * bounded across passes. Evicting retired graphics removes their scrollback
+ * placements; a later replay can render or demote those images again.
+ *
+ * `cap` bounds one surface's live images, not the terminal's whole store. A
+ * fullscreen overlay's frame and the normal screen standing behind it are both
+ * on the terminal, and neither may delete the other's graphics — see
+ * {@link limitResidentImages} — so while a modal is up the store legitimately
+ * holds up to `cap` per surface. Read `cap` as "how many images one frame shows
+ * as graphics", not as a hard residency ceiling.
  *
  * `cap <= 0` disables budgeting: every image stays a live graphic.
  */
@@ -90,19 +142,29 @@ export class ImageBudget {
 	/** Per-id suppression decision from the first observation in this pass. */
 	#passSuppression = new Map<number, boolean>();
 	/**
-	 * Suppress threshold reflected in the frame currently on the terminal: images
-	 * at display indices `[0, #onTerminal)` are shown as text there.
+	 * Display index each observation was decided at, so {@link #passShowsLive}
+	 * can re-check it against a reconciled threshold without scanning
+	 * {@link #passIds} once per image.
 	 */
-	#onTerminal = 0;
-	/** Suppress threshold the current/next render should apply. */
-	#planned = 0;
+	#passIndex = new Map<number, number>();
+	/** Live/text split of the normal screen. */
+	#screenSplit = newSurfaceSplit();
+	/** Live/text split of the alternate buffer (fullscreen overlay, resize borrow). */
+	#altSplit = newSurfaceSplit();
+	/** The split the in-flight pass reads and writes; selected by {@link beginPass}. */
+	#split = this.#screenSplit;
 	/**
 	 * True while the in-flight pass applies a stricter threshold than the terminal
 	 * shows — the demotion frame that must purge graphics and fully repaint.
 	 */
 	#applyingReset = false;
-	#lastTotal = 0;
 	#purgeIds: number[] = [];
+	/**
+	 * Deletions that belong to a pending destructive reset, kept out of
+	 * {@link #purgeIds} so only that reset's own repaint can emit them. See
+	 * {@link forgetTransmitted}.
+	 */
+	#resetPurgeIds: number[] = [];
 	/** Image ids whose data is believed to be loaded in the terminal's store. */
 	#transmitted = new Set<number>();
 	/** Transmit sequences (full base64) to write once, before this frame's placements. */
@@ -112,11 +174,15 @@ export class ImageBudget {
 	// tail, bottom-up. Such a pass cannot derive display order from observe()
 	// call order, so its suppression decisions replay the committed split below.
 	#stablePass = false;
-	// Image ids shown as text in the frame currently on the terminal: the
-	// display-order prefix [0, #onTerminal) of the last full pass, snapshotted by
-	// id so a partial pass reproduces the on-screen live/text split without a
-	// full, correctly-ordered walk.
-	#suppressedIds = new Set<number>();
+	/** The surface the in-flight pass composes for; selected by {@link beginPass}. */
+	#surface: Surface = "screen";
+	/**
+	 * Image ids rendered as live graphics by the frame standing on each surface.
+	 * A pass walks one surface, so the other's entry is what stops {@link #retire}
+	 * from deleting a graphic that is merely out of view — the transcript behind a
+	 * fullscreen overlay keeps its placements and is restored from cache on exit.
+	 */
+	#liveIds: Record<Surface, Set<number>> = { screen: new Set(), alt: new Set() };
 	/**
 	 * Per-image direct-placement emit state: source pixel geometry for the
 	 * renderer's clipped source rectangle, plus the placement-id epoch (see
@@ -155,7 +221,7 @@ export class ImageBudget {
 		const next = normalizeCap(cap);
 		if (next === this.#cap) return;
 		this.#cap = next;
-		this.#reconcile(this.#lastTotal);
+		if (!this.#reconcile(this.#split.lastTotal)) this.#requestRender();
 	}
 
 	/**
@@ -178,18 +244,51 @@ export class ImageBudget {
 		return id;
 	}
 
+	/**
+	 * Start an alternate-buffer lifecycle. Call once per `?1049h`, before the
+	 * first pass of the fullscreen overlay or resize borrow that owns the buffer.
+	 *
+	 * The alt split is a claim about the frame standing on that surface, and
+	 * `?1049h` hands over a cleared one: the previous occupant's threshold would
+	 * suppress this buffer's leading images against a frame that no longer
+	 * exists, painting them as text until a corrective render lands. Passes
+	 * *within* one lifecycle must keep sharing the split — that is what lets an
+	 * over-cap discovery pass converge before the frame is emitted.
+	 */
+	beginAltScreenLifecycle(): void {
+		resetSurfaceSplit(this.#altSplit);
+		this.#liveIds.alt.clear();
+	}
+
 	/**
 	 * Begin a render pass. Called by the renderer before composing the frame.
 	 * Pass `stable: true` for a partial/throwaway pass that does not walk the
 	 * whole tree in display order (the resize viewport fast path): {@link observe}
 	 * then replays the last committed per-id decision instead of one derived from
 	 * call order, and the pass must NOT be closed with {@link endPass}.
+	 *
+	 * Pass `altScreen: true` when the frame is painted on the alternate buffer
+	 * (fullscreen overlay, resize borrow). The pass then reads and writes that
+	 * surface's own {@link SurfaceSplit} and its live set adds to the recorded
+	 * normal-screen one instead of replacing it, so a modal's threshold never
+	 * reaches the transcript standing behind it.
 	 */
-	beginPass(stable = false): void {
+	beginPass(stable = false, altScreen = false): void {
 		this.#passIds.length = 0;
 		this.#passSuppression.clear();
+		this.#passIndex.clear();
 		this.#stablePass = stable;
-		this.#applyingReset = !stable && this.#cap > 0 && this.#planned > this.#onTerminal;
+		this.#surface = altScreen ? "alt" : "screen";
+		this.#split = altScreen ? this.#altSplit : this.#screenSplit;
+		// Composing for the screen means the alternate buffer holds no frame to
+		// protect: live renders reach the normal-screen paths only when
+		// TUI#doRender has ruled out both alt-buffer owners, and the one caller
+		// outside that dispatch — the shutdown history flush — writes `?1049l`
+		// first. Note that leaving alt mode is not the same as unstacking a
+		// fullscreen overlay: the flush must exclude one that is still stacked
+		// from the pass itself, which is that caller's job, not this line's.
+		if (!altScreen) this.#liveIds.alt.clear();
+		this.#applyingReset = !stable && this.#cap > 0 && this.#split.planned > this.#split.onTerminal;
 	}
 
 	/**
@@ -198,22 +297,23 @@ export class ImageBudget {
 	 * on a cache hit, so the image keeps its display-order slot.
 	 *
 	 * During a `stable` pass ({@link beginPass}) the call order and visible subset
-	 * are not authoritative, so the decision is the committed on-terminal split
-	 * (`#suppressedIds`) keyed by id — order- and partiality-independent.
+	 * are not authoritative, so the decision is the surface's committed
+	 * on-terminal split, keyed by id — order- and partiality-independent.
 	 */
 	observe(imageId: number): boolean {
 		const existing = this.#passSuppression.get(imageId);
 		if (existing !== undefined) return existing;
 		if (this.#stablePass) {
-			const suppressed = this.#cap > 0 && this.#suppressedIds.has(imageId);
+			const suppressed = this.#cap > 0 && this.#split.suppressedIds.has(imageId);
 			this.#passSuppression.set(imageId, suppressed);
 			if (suppressed) this.#forgetKeyForId(imageId);
 			return suppressed;
 		}
 		const index = this.#passIds.length;
 		this.#passIds.push(imageId);
-		const suppressed = this.#cap > 0 && index < this.#planned;
+		const suppressed = this.#cap > 0 && index < this.#split.planned;
 		this.#passSuppression.set(imageId, suppressed);
+		this.#passIndex.set(imageId, index);
 		if (suppressed) this.#forgetKeyForId(imageId);
 		return suppressed;
 	}
@@ -224,29 +324,101 @@ export class ImageBudget {
 	 */
 	endPass(): boolean {
 		const total = this.#passIds.length;
-		this.#lastTotal = total;
+		const split = this.#split;
+		split.lastTotal = total;
 		if (this.#applyingReset) {
-			for (let i = this.#onTerminal; i < this.#planned && i < total; i++) {
-				const id = this.#passIds[i];
-				// A transmit queued by a discarded discovery pass never reached
-				// the terminal, so cancel it instead of transmitting then purging.
-				if (!this.#pendingTransmits.delete(id)) this.#purgeIds.push(id);
-				this.#transmitted.delete(id);
-				this.#deletePlacementState(id);
-				this.#forgetKeyForId(id);
+			// This frame replaced these with their text fallback, so their graphics
+			// are retired as far as this surface is concerned.
+			for (let i = split.onTerminal; i < split.planned && i < total; i++) {
+				this.#retire(this.#passIds[i]);
 			}
-			this.#onTerminal = this.#planned;
+			split.onTerminal = split.planned;
 			this.#applyingReset = false;
 		}
 		const retry = this.#reconcile(total);
 		// Snapshot the committed display-order suppression by id: the prefix
-		// [0, #onTerminal) is what the terminal currently shows as text. Partial
+		// [0, onTerminal) is what this surface currently shows as text. Partial
 		// passes replay this per id (see #stablePass) instead of re-deriving it
 		// from a reversed, tail-only walk.
-		this.#suppressedIds = new Set(this.#passIds.slice(0, this.#onTerminal));
+		split.suppressedIds = new Set(this.#passIds.slice(0, split.onTerminal));
 		return retry;
 	}
 
+	/**
+	 * Bound the terminal's image store to `cap`. Demotion ({@link endPass}) already
+	 * retires the graphics this frame replaced with text; this sweeps the ones no
+	 * frame shows any more — images the pass simply stopped observing.
+	 *
+	 * Also records what this frame leaves standing on its surface, which is how
+	 * the next pass on the *other* surface knows what it may not destroy.
+	 */
+	limitResidentImages(): void {
+		this.#liveIds[this.#surface] = new Set(this.#passIds.filter(id => this.#passShowsLive(id)));
+		if (this.#cap <= 0 || this.#transmitted.size <= this.#cap) return;
+		for (const id of this.#transmitted) {
+			if (this.#transmitted.size <= this.#cap) break;
+			this.#retire(id);
+		}
+	}
+
+	/**
+	 * Whether this pass leaves `imageId` on its surface as a live graphic.
+	 *
+	 * Not simply "was not suppressed". A pass decides suppression from the
+	 * threshold standing at {@link beginPass}, and {@link endPass} may then
+	 * reconcile that threshold *downwards* — the frame is emitted with a text
+	 * fallback the very next frame will replace with the graphic again. Reading
+	 * such a decision as retirement would delete an image the surface is about to
+	 * show, and `d=I` takes placements no repaint can restore. So a suppression
+	 * the reconcile has since undercut counts as live.
+	 */
+	#passShowsLive(imageId: number): boolean {
+		const suppressed = this.#passSuppression.get(imageId);
+		if (suppressed === undefined) return false;
+		if (!suppressed) return true;
+		// Absent (a `stable` pass replays the committed split rather than deriving
+		// an order) counts as live, so an unknown decision never authorises a
+		// delete.
+		const index = this.#passIndex.get(imageId);
+		return index === undefined || index >= this.#split.planned;
+	}
+
+	/**
+	 * Drop `imageId` from the terminal's image store: queue its `d=I` (or cancel
+	 * a transmit that never went out) and forget its placement ledger and key.
+	 *
+	 * The single gate on every destruction path. `d=I` removes an image's
+	 * placements everywhere, scrollback included, and a frame diff only rewrites
+	 * rows whose text changed — so a graphic some standing frame still shows
+	 * cannot be repaired once deleted, and must never be a candidate. Refuses
+	 * when the in-flight pass renders the image live, or when the frame on any
+	 * surface this pass is not repainting does. Returns whether it was retired.
+	 */
+	#retire(imageId: number): boolean {
+		if (this.#passShowsLive(imageId)) return false;
+		for (const surface of SURFACES) {
+			if (surface !== this.#surface && this.#liveIds[surface].has(imageId)) return false;
+		}
+		// A transmit queued by a discarded discovery pass never reached the
+		// terminal, so cancel it instead of transmitting then purging.
+		if (!this.#pendingTransmits.delete(imageId)) this.#purgeIds.push(imageId);
+		this.#transmitted.delete(imageId);
+		this.#deletePlacementState(imageId);
+		this.#forgetKeyForId(imageId);
+		return true;
+	}
+
+	/**
+	 * Image ids a destructive reset must delete explicitly, alongside its `d=A`.
+	 * Emit only from that reset's repaint; clears the queue.
+	 */
+	takeResetPurgeIds(): readonly number[] {
+		if (this.#resetPurgeIds.length === 0) return EMPTY_IDS;
+		const ids = this.#resetPurgeIds;
+		this.#resetPurgeIds = [];
+		return ids;
+	}
+
 	/** Image ids to delete from the terminal this frame; clears the pending set. */
 	takePurgeIds(): readonly number[] {
 		if (this.#purgeIds.length === 0) return EMPTY_IDS;
@@ -261,11 +433,13 @@ export class ImageBudget {
 		const ids = [...this.#transmitted];
 		this.#transmitted.clear();
 		this.#purgeIds = [];
+		this.#resetPurgeIds = [];
 		this.#pendingTransmits.clear();
 		this.#keyToId.clear();
 		this.#idToKey.clear();
 		this.#placementState.clear();
 		this.#watchedPlacements.clear();
+		for (const surface of SURFACES) this.#liveIds[surface].clear();
 		return ids;
 	}
 
@@ -407,18 +581,17 @@ export class ImageBudget {
 	}
 
 	/**
-	 * True when the budget has nothing in flight: no live images observed on
-	 * the last pass, no queued transmits, no pending purges, and no stricter
-	 * threshold left to apply. A component-scoped frame may skip the observe
-	 * pass only then — a partial tree walk would under-count display order.
+	 * True when the budget has nothing in flight on either surface: no live images
+	 * observed on the last pass, no queued transmits, no pending purges, and no
+	 * stricter threshold left to apply. A component-scoped frame may skip the
+	 * observe pass only then — a partial tree walk would under-count display order.
 	 */
 	get quiescent(): boolean {
-		return (
-			this.#lastTotal === 0 &&
-			this.#pendingTransmits.size === 0 &&
-			this.#purgeIds.length === 0 &&
-			this.#planned === this.#onTerminal
-		);
+		if (this.#pendingTransmits.size > 0 || this.#purgeIds.length > 0) return false;
+		for (const split of [this.#screenSplit, this.#altSplit]) {
+			if (split.lastTotal !== 0 || split.planned !== split.onTerminal) return false;
+		}
+		return true;
 	}
 
 	/** Transmit sequences to write before this frame's placements; clears the queue. */
@@ -439,11 +612,36 @@ export class ImageBudget {
 	 */
 	forgetTransmitted(): void {
 		if (this.#transmitted.size === 0 && this.#pendingTransmits.size === 0) return;
+		for (const id of this.#transmitted) {
+			if (!this.#pendingTransmits.has(id)) this.#resetPurgeIds.push(id);
+		}
+		// The ids go to #resetPurgeIds, drained only by the destructive repaint
+		// itself — never to #purgeIds, which any frame drains. That is how a
+		// deletion used to ride out on an alternate-buffer frame and leave the
+		// normal screen blank with no repaint left to restore it.
+		//
+		// `d=A` alone is not enough to skip these: Kitty excludes *virtual*
+		// placements from it, and erasing placeholder text does not remove the
+		// prototype either. Forgetting drops the id from tracking, so without an
+		// explicit `d=I` no later sweep can ever find that placement again.
 		this.#transmitted.clear();
 		this.#pendingTransmits.clear();
 	}
 
+	/**
+	 * Release `id`'s stable key so a component recreated under it gets a fresh id
+	 * — but only once the terminal no longer holds `id`'s data, because a key must
+	 * never resolve to an id whose graphic is gone.
+	 *
+	 * Key lifetime follows residency, not the live/text split. The two usually
+	 * agree: an image shown as text has had its graphic purged. They diverge when
+	 * {@link #retire} refuses, which leaves a suppressed image resident on another
+	 * surface — and releasing a resident id's key orphans it. The recreation mints
+	 * a new id, nothing observes the old one again, and the next pass retires it,
+	 * deleting every placement it ever made including scrollback copies.
+	 */
 	#forgetKeyForId(id: number): void {
+		if (this.#transmitted.has(id)) return;
 		const key = this.#idToKey.get(id);
 		if (key === undefined) return;
 		this.#idToKey.delete(id);
@@ -451,21 +649,22 @@ export class ImageBudget {
 	}
 
 	#reconcile(total: number): boolean {
+		const split = this.#split;
 		const desired = this.#cap > 0 ? Math.max(0, total - this.#cap) : 0;
-		if (desired === this.#planned) {
+		if (desired === split.planned) {
 			// Budget relaxed without a stricter frame (cap raised or images
 			// removed): surviving graphics are untouched and re-exposed rows
 			// repaint normally, so just track the looser threshold.
-			if (this.#planned < this.#onTerminal) this.#onTerminal = this.#planned;
+			if (split.planned < split.onTerminal) split.onTerminal = split.planned;
 			return false;
 		}
-		const retry = desired > this.#onTerminal;
-		this.#planned = desired;
+		const retry = desired > split.onTerminal;
+		split.planned = desired;
 		// More images must be demoted than the terminal shows: schedule the purge +
 		// full-redraw frame. Fewer: no ghosts to clear, so just catch the tracking
 		// up — a normal repaint re-exposes the un-demoted images. Either way a
 		// render is needed to apply the new threshold.
-		if (desired <= this.#onTerminal) this.#onTerminal = desired;
+		if (desired <= split.onTerminal) split.onTerminal = desired;
 		this.#requestRender();
 		return retry;
 	}

package/src/terminal-capabilities.ts

@@ -325,9 +325,11 @@ export function isWindowsTerminalPreviewSixelSupported(
 	env: NodeJS.ProcessEnv = Bun.env,
 	platform: NodeJS.Platform = process.platform,
 ): boolean {
-	if (platform !== "win32") return false;
-	if (!env.WT_SESSION) return false;
-	if (env.TERM_PROGRAM && env.TERM_PROGRAM.toLowerCase() !== "windows_terminal") {
+	if (
+		platform !== "win32" ||
+		!env.WT_SESSION ||
+		(env.TERM_PROGRAM && env.TERM_PROGRAM.toLowerCase() !== "windows_terminal")
+	) {
 		return false;
 	}
 	const version = parseMajorMinorVersion(env.TERM_PROGRAM_VERSION);
@@ -386,7 +388,7 @@ export function shouldEnableSynchronizedOutputByDefault(
 	if (override !== null) return override;
 
 	if (advertisesSynchronizedOutput(env.TERM_FEATURES)) return true;
-	if (env.WT_SESSION) return true;
+	if (env.WT_SESSION && (!env.TERM_PROGRAM || env.TERM_PROGRAM.toLowerCase() === "windows_terminal")) return true;
 	if (isInsideHerdr(env)) return true;
 
 	// Risky multiplexers start off even when an inner terminal id leaks through:
@@ -442,6 +444,45 @@ export function detectRectangularSgrSupport(terminalId: TerminalId, env: NodeJS.
 	}
 	return true;
 }
+/**
+ * Whether the terminal implements colon-subparameter SGR styled underlines —
+ * `CSI 4 : 3 m` (curly) plus `CSI 58` / `CSI 59` underline color — as opposed to
+ * only the legacy `CSI 4 m` / `CSI 24 m` on/off underline.
+ *
+ * This is an underline-style capability, not a color depth, so it is keyed on
+ * the detected terminal, never on `TERM`/`COLORTERM`. kitty, Ghostty, WezTerm,
+ * and iTerm2 (>= 3.5) implement the full pair. Apple Terminal does NOT: it
+ * renders `CSI 4 : 0 m` (the reset half) as a solid black background that
+ * persists to end of line, and ignores SGR 58/59 — so it, along with every
+ * other unproven terminal, gets the flat underline instead. Disabled under any
+ * multiplexer: GNU screen and older tmux drop colon-form SGR, and the outer
+ * terminal's id leaks into the session env, so a proven id is not proof the
+ * bytes survive — the same reason DECCARA and synchronized output gate on it.
+ */
+export function detectStyledUnderlineSupport(terminalId: TerminalId, env: NodeJS.ProcessEnv = Bun.env): boolean {
+	// A multiplexer in the path (GNU screen, older tmux) does not forward the
+	// colon-form underline, yet the outer terminal's id leaks through the session
+	// env, so the switch below would otherwise trust an unreachable capability.
+	if (isInsideTerminalMultiplexer(env)) return false;
+	switch (terminalId) {
+		case "kitty":
+		case "ghostty":
+		case "wezterm":
+			return true;
+		case "iterm2": {
+			// The full curly-and-colored pair did not ship together until iTerm2 3.5
+			// (curly first targeted 3.3.12; SGR 58/59 underline color was beta,
+			// expected for 3.5), so 3.0–3.4 would receive the colon reset they cannot
+			// render. Enable only on a confirmed major.minor >= 3.5; an absent or
+			// unparseable version keeps the flat fallback so only proven terminals
+			// get the colon form.
+			const version = parseMajorMinorVersion(env.TERM_PROGRAM_VERSION);
+			return version !== null && (version.major > 3 || (version.major === 3 && version.minor >= 5));
+		}
+		default:
+			return false;
+	}
+}
 /**
  * Resolve an explicit user override for OSC 8 hyperlinks. Returns `false` for
  * an opt-out, `true` for a force-on, or `null` when the user has expressed no
@@ -689,6 +730,8 @@ export interface RuntimeTerminal extends TerminalInfo {
 	supportsScreenToScrollback: boolean;
 	/** Whether OSC 66 text sizing is currently enabled. */
 	textSizing: boolean;
+	/** Whether the terminal implements colon-subparameter styled underlines (curly + colored). */
+	styledUnderlines: boolean;
 }
 
 export const TERMINAL: RuntimeTerminal = (() => {
@@ -715,6 +758,11 @@ export const TERMINAL: RuntimeTerminal = (() => {
 	// ignores DECCARA) exercises the padded-string fallback. Integration tests opt
 	// in explicitly through setTerminalDeccara.
 	resolved.deccara = detectRectangularSgrSupport(resolved.id, Bun.env) && !isBunTestRuntime();
+	// Styled-underline capability: colon-form curly underline + SGR 58/59 color.
+	// Keyed on the detected terminal (an underline-style capability, not a color
+	// depth), so Apple Terminal and other unproven hosts fall back to the flat
+	// CSI 4 m / CSI 24 m underline the typo renderer needs to avoid black bars.
+	resolved.styledUnderlines = detectStyledUnderlineSupport(resolved.id, Bun.env);
 	return resolved;
 })();
 

package/src/terminal-multiplexer.ts

@@ -10,15 +10,36 @@ export function isInsideHerdr(env: NodeJS.ProcessEnv = Bun.env): boolean {
 	return false;
 }
 
-/** Detect whether a terminal multiplexer owns the current screen grid. */
-export function isInsideTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): boolean {
-	// TMUX/STY/ZELLIJ, Herdr, and CMUX workspace/surface/remote-transport
-	// markers are authoritative session signals. TERM can also survive when those are
-	// stripped (`sudo` without -E, `su`, env-sanitizing launchers/ssh). Do not
-	// use CMUX_SOCKET_PATH here: it is a CLI socket override and can be set
-	// outside a CMUX terminal.
-	if (env.TMUX || env.STY || env.ZELLIJ || isInsideHerdr(env)) return true;
-	if (env.CMUX_WORKSPACE_ID || env.CMUX_SURFACE_ID || env.CMUX_REMOTE_TRANSPORT) return true;
+/** Terminal multiplexers omp recognizes as owning the screen grid. */
+export type TerminalMultiplexer = "herdr" | "tmux" | "screen" | "zellij" | "cmux" | "wmux";
+
+/**
+ * Classify which terminal multiplexer owns the current screen grid, or `null`
+ * for a direct terminal. Single source of truth for both the render-path gate
+ * (`isInsideTerminalMultiplexer`) and the debug snapshot label.
+ *
+ * TMUX/STY/ZELLIJ, Herdr, and the CMUX/WMUX workspace/surface/remote-transport
+ * markers are authoritative session signals. TERM can also survive when those
+ * are stripped (`sudo` without -E, `su`, env-sanitizing launchers/ssh). Do not
+ * use CMUX_SOCKET_PATH / WMUX_CLI / WMUX_PIPE here: they are CLI socket/path
+ * overrides and can be set outside a CMUX/WMUX terminal. wmux is a Windows
+ * multiplexer (Electron + xterm.js) modeled on cmux/herdr that repaints its
+ * pane in place and exports WMUX=1 plus a native WMUX_SURFACE_ID.
+ */
+export function classifyTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): TerminalMultiplexer | null {
+	if (isInsideHerdr(env)) return "herdr";
+	if (env.TMUX) return "tmux";
+	if (env.STY) return "screen";
+	if (env.ZELLIJ) return "zellij";
+	if (env.CMUX_WORKSPACE_ID || env.CMUX_SURFACE_ID || env.CMUX_REMOTE_TRANSPORT) return "cmux";
+	if (env.WMUX === "1" || env.WMUX_SURFACE_ID) return "wmux";
 	const term = env.TERM?.toLowerCase() ?? "";
-	return term.startsWith("tmux") || term.startsWith("screen");
+	if (term.startsWith("tmux")) return "tmux";
+	if (term.startsWith("screen")) return "screen";
+	return null;
+}
+
+/** True when a terminal multiplexer owns the current screen grid. */
+export function isInsideTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	return classifyTerminalMultiplexer(env) !== null;
 }

package/src/terminal.ts

@@ -514,6 +514,20 @@ export interface Terminal {
 	 */
 	readonly pendingOutputBytes?: number;
 
+	/**
+	 * Whether a pseudoconsole host owns the grid this terminal writes to, so
+	 * neither the cursor nor the painted rows survive a resize under the
+	 * application's own model. Measured on Windows conhost: resizing the
+	 * pseudoconsole makes it re-emit its whole viewport from `CSI H` with
+	 * absolute addressing while the application writes nothing, and it re-homes
+	 * the cursor, so a DSR reply after a resize reports column 1 instead of the
+	 * column the application parked. The renderer's resize anchor recovery needs
+	 * both properties, so it takes the rebuild path instead when this is set.
+	 * Optional so custom Terminals built against older pi-tui versions keep
+	 * working; absent means the terminal itself owns the grid.
+	 */
+	readonly hostOwnsGridOnResize?: boolean;
+
 	// Whether Kitty keyboard protocol is active
 	get kittyProtocolActive(): boolean;
 
@@ -656,8 +670,9 @@ function isPrivateModeSupported(status: string): boolean {
 export interface ProcessTerminalOptions {
 	/**
 	 * Force ConPTY-hosted behavior on or off. Defaults to live detection via
-	 * {@link isConPTYHosted}. Tests set this so the kitty-flag and write-chunking
-	 * paths stay hermetic regardless of the ambient WSL env (`WSL_DISTRO_NAME` /
+	 * {@link isConPTYHosted}. Tests set this so the kitty-flag, write-chunking
+	 * and resize-routing ({@link Terminal.hostOwnsGridOnResize}) paths stay
+	 * hermetic regardless of the ambient WSL env (`WSL_DISTRO_NAME` /
 	 * `WSL_INTEROP`) — the suite must behave identically on WSL and on CI.
 	 */
 	conpty?: boolean;
@@ -1989,6 +2004,14 @@ export class ProcessTerminal implements Terminal {
 		return process.stdout.writableLength ?? 0;
 	}
 
+	get hostOwnsGridOnResize(): boolean {
+		// #conpty, not a fresh isConPTYHosted() call: the construction override
+		// must gate every ConPTY-dependent path uniformly, or an injected
+		// `conpty` value models one host for writes and kitty flags and the
+		// opposite host for resize routing.
+		return this.#conpty;
+	}
+
 	/**
 	 * Reconcile the stdout backlog after a write or a poll. The watchdog runs an
 	 * episode from the moment the backlog crosses the arm cap until it drains to