@oh-my-pi/pi-tui 18.1.2 → 18.1.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [18.1.3] - 2026-09-02
+
+### Fixed
+
+- Fixed the TUI tearing in Herdr panes so the live viewport updates as one frame instead of leaving the top frozen while only the bottom refreshed. Pane identity vars (`HERDR_PANE_ID` / `HERDR_TAB_ID` / `HERDR_WORKSPACE_ID`) also count as inside Herdr, not only `HERDR_ENV=1`. A DECRPM “unrecognized” report keeps synchronized output on; a “permanently reset” report, or a custom terminal that omits the DECRPM status, still turns it off.
+
 ## [18.1.0] - 2026-09-01
 
 ### Fixed

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

@@ -85,9 +85,15 @@ export declare function synchronizedOutputUserOverride(env?: NodeJS.ProcessEnv):
  *   2. Positive `TERM_FEATURES` advertisement (`Sy`) — survives SSH/mux wrapping.
  *   3. Windows Terminal (1.24+) via `WT_SESSION`, on native win32 and the
  *      WSL/SSH-fronted host alike.
- *   4. Known direct terminals with confirmed support. SSH does *not* disable —
+ *   4. Herdr panes. Herdr is otherwise treated as a multiplexer so leaked
+ *      kitty/ghostty identities cannot enable placeholder graphics, but its
+ *      pane VTE is libghostty and already suppresses compositing while DEC 2026
+ *      is set. Leaving sync off lets CUP-diff paints and split write(2) chunks
+ *      composite as dirty-row patches — the live viewport tears, with the top
+ *      frozen while only the bottom refreshes.
+ *   5. Known direct terminals with confirmed support. SSH does *not* disable —
  *      DEC 2026 passes through SSH when the outer terminal honors it.
- *   5. Everything else starts off, including risky multiplexers; the runtime
+ *   6. Everything else starts off, including risky multiplexers; the runtime
  *      DECRQM probe upgrades any of them when the terminal actually reports
  *      `?2026` supported (current zellij, tmux master, foot, contour, mintty…).
  */

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

@@ -1,2 +1,4 @@
+/** True when this process is running inside a Herdr pane. */
+export declare function isInsideHerdr(env?: NodeJS.ProcessEnv): boolean;
 /** Detect whether a terminal multiplexer owns the current screen grid. */
 export declare function isInsideTerminalMultiplexer(env?: NodeJS.ProcessEnv): boolean;

package/dist/types/terminal.d.ts

@@ -99,6 +99,13 @@ export interface TerminalStartOptions {
 }
 /** Identity of an accepted explicit terminal appearance refresh request. */
 export type TerminalAppearanceRequestToken = number;
+/**
+ * Fired once per DEC private mode when DECRQM support resolves.
+ * `confirmed` is false when only the DA1 sentinel arrived.
+ * `status` is the DECRPM value (0 unrecognized, 1/2 set/reset, 3 permanently
+ * set, 4 permanently reset) when the terminal answered DECRQM.
+ */
+export type PrivateModeReportHandler = (mode: number, supported: boolean, confirmed?: boolean, status?: number) => void;
 export interface Terminal {
     start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void, options?: TerminalStartOptions): void;
     /**
@@ -177,8 +184,9 @@ export interface Terminal {
      * status resolves. `confirmed` is false when the terminal answered the DA1
      * sentinel without answering DECRQM, which proves only that querying support
      * is unavailable — not that the private mode itself is unsupported.
+     * `status` is the DECRPM value when the terminal answered DECRQM.
      */
-    onPrivateModeReport?(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void;
+    onPrivateModeReport?(callback: PrivateModeReportHandler): void;
 }
 /**
  * True when stdout flows through a ConPTY pseudo-console (native win32, or
@@ -223,7 +231,7 @@ export declare class ProcessTerminal implements Terminal {
      * probes remain direct. Suppressed while inactive, headless, or after teardown.
      */
     refreshAppearance(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | void;
-    onPrivateModeReport(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void;
+    onPrivateModeReport(callback: PrivateModeReportHandler): void;
     start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void, options?: TerminalStartOptions): void;
     enableInput(): void;
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "18.1.2",
+	"version": "18.1.3",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -37,8 +37,8 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.1.2",
-		"@oh-my-pi/pi-utils": "18.1.2"
+		"@oh-my-pi/pi-natives": "18.1.3",
+		"@oh-my-pi/pi-utils": "18.1.3"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/kitty-graphics.ts

@@ -15,7 +15,7 @@
  * forms. Protocol gating (`imageProtocol === Kitty`) lives in the caller.
  */
 
-import { isInsideTerminalMultiplexer } from "./terminal-multiplexer";
+import { isInsideHerdr, isInsideTerminalMultiplexer } from "./terminal-multiplexer";
 import { wrapTmuxPassthroughIfNeeded } from "./tmux";
 
 /** Kitty Unicode placeholder base character (U+10EEEE, Plane 16 PUA). */
@@ -81,7 +81,7 @@ export function detectKittyUnicodePlaceholdersSupport(terminalId: string, env: N
 	if (force === "0" || force === "false" || force === "off" || force === "no" || force === "n") return false;
 	const insideMultiplexer = isInsideTerminalMultiplexer(env);
 	if (insideMultiplexer && env.PI_FORCE_IMAGE_PROTOCOL?.trim().toLowerCase() === "kitty") return true;
-	if (env.HERDR_ENV === "1") return false;
+	if (isInsideHerdr(env)) return false;
 	return terminalId === "kitty" || terminalId === "ghostty";
 }
 

package/src/terminal-capabilities.ts

@@ -9,7 +9,7 @@ import {
 	renderKittyPlaceholderLines,
 	setKittyGraphics,
 } from "./kitty-graphics";
-import { isInsideTerminalMultiplexer } from "./terminal-multiplexer";
+import { isInsideHerdr, isInsideTerminalMultiplexer } from "./terminal-multiplexer";
 import { isInsideTmux, wrapTmuxPassthrough, wrapTmuxPassthroughIfNeeded } from "./tmux";
 import type { HangulCompatibilityJamoWidth } from "./utils";
 
@@ -289,9 +289,15 @@ function advertisesSynchronizedOutput(termFeatures: string | undefined): boolean
  *   2. Positive `TERM_FEATURES` advertisement (`Sy`) — survives SSH/mux wrapping.
  *   3. Windows Terminal (1.24+) via `WT_SESSION`, on native win32 and the
  *      WSL/SSH-fronted host alike.
- *   4. Known direct terminals with confirmed support. SSH does *not* disable —
+ *   4. Herdr panes. Herdr is otherwise treated as a multiplexer so leaked
+ *      kitty/ghostty identities cannot enable placeholder graphics, but its
+ *      pane VTE is libghostty and already suppresses compositing while DEC 2026
+ *      is set. Leaving sync off lets CUP-diff paints and split write(2) chunks
+ *      composite as dirty-row patches — the live viewport tears, with the top
+ *      frozen while only the bottom refreshes.
+ *   5. Known direct terminals with confirmed support. SSH does *not* disable —
  *      DEC 2026 passes through SSH when the outer terminal honors it.
- *   5. Everything else starts off, including risky multiplexers; the runtime
+ *   6. Everything else starts off, including risky multiplexers; the runtime
  *      DECRQM probe upgrades any of them when the terminal actually reports
  *      `?2026` supported (current zellij, tmux master, foot, contour, mintty…).
  */
@@ -304,6 +310,7 @@ export function shouldEnableSynchronizedOutputByDefault(
 
 	if (advertisesSynchronizedOutput(env.TERM_FEATURES)) return true;
 	if (env.WT_SESSION) return true;
+	if (isInsideHerdr(env)) return true;
 
 	// Risky multiplexers start off even when an inner terminal id leaks through:
 	// older tmux/screen synchronized-output handling is flaky and a mux may not
@@ -507,7 +514,7 @@ export function resolveImageProtocol(
 	// Herdr owns the pane grid but does not expose whether the attached client
 	// enabled its experimental Kitty renderer. Outer-terminal identity variables
 	// can leak into the pane, so only the explicit protocol override is safe.
-	if (imageProtocol !== null && env.HERDR_ENV === "1") {
+	if (imageProtocol !== null && isInsideHerdr(env)) {
 		return null;
 	}
 	return imageProtocol;

package/src/terminal-multiplexer.ts

@@ -1,3 +1,15 @@
+/** True when this process is running inside a Herdr pane. */
+export function isInsideHerdr(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	// HERDR_ENV=1 is canonical. Identity vars survive env-sanitizing launchers
+	// that drop HERDR_ENV. Do not use HERDR_SOCKET_PATH, HERDR_BIN_PATH,
+	// HERDR_SESSION, HERDR_CONFIG_PATH, or HERDR_CLIENT_SOCKET_PATH here: they
+	// are client-side and can be set outside a Herdr pane, matching the
+	// CMUX_SOCKET_PATH warning below.
+	if (env.HERDR_ENV === "1") return true;
+	if (env.HERDR_PANE_ID || env.HERDR_TAB_ID || env.HERDR_WORKSPACE_ID) return true;
+	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
@@ -5,7 +17,7 @@ export function isInsideTerminalMultiplexer(env: NodeJS.ProcessEnv = Bun.env): b
 	// 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 || env.HERDR_ENV === "1") return true;
+	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;
 	const term = env.TERM?.toLowerCase() ?? "";
 	return term.startsWith("tmux") || term.startsWith("screen");

package/src/terminal.ts

@@ -454,6 +454,13 @@ export interface TerminalStartOptions {
 }
 /** Identity of an accepted explicit terminal appearance refresh request. */
 export type TerminalAppearanceRequestToken = number;
+/**
+ * Fired once per DEC private mode when DECRQM support resolves.
+ * `confirmed` is false when only the DA1 sentinel arrived.
+ * `status` is the DECRPM value (0 unrecognized, 1/2 set/reset, 3 permanently
+ * set, 4 permanently reset) when the terminal answered DECRQM.
+ */
+export type PrivateModeReportHandler = (mode: number, supported: boolean, confirmed?: boolean, status?: number) => void;
 export interface Terminal {
 	// Start the terminal with input, resize, and host-disconnect handlers.
 	start(
@@ -577,8 +584,9 @@ export interface Terminal {
 	 * status resolves. `confirmed` is false when the terminal answered the DA1
 	 * sentinel without answering DECRQM, which proves only that querying support
 	 * is unavailable — not that the private mode itself is unsupported.
+	 * `status` is the DECRPM value when the terminal answered DECRQM.
 	 */
-	onPrivateModeReport?(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void;
+	onPrivateModeReport?(callback: PrivateModeReportHandler): void;
 }
 
 /**
@@ -724,7 +732,7 @@ export class ProcessTerminal implements Terminal {
 	#da1SentinelOwners: Da1SentinelOwner[] = [];
 	/** Resolved DECRQM support per private mode (mode → supported). */
 	#privateModeSupport = new Map<number, boolean>();
-	#privateModeCallbacks: Array<(mode: number, supported: boolean, confirmed: boolean) => void> = [];
+	#privateModeCallbacks: PrivateModeReportHandler[] = [];
 	/** Whether DEC 2048 in-band resize notifications are currently enabled. */
 	#inBandResizeActive = false;
 	/** Reassembly buffer for a DEC 2048 in-band resize report split across stdin reads. */
@@ -815,7 +823,7 @@ export class ProcessTerminal implements Terminal {
 		return token;
 	}
 
-	onPrivateModeReport(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void {
+	onPrivateModeReport(callback: PrivateModeReportHandler): void {
 		this.#privateModeCallbacks.push(callback);
 	}
 
@@ -1537,7 +1545,7 @@ export class ProcessTerminal implements Terminal {
 	}
 
 	#handlePrivateModeReport(mode: number, status: string): void {
-		this.#resolvePrivateMode(mode, isPrivateModeSupported(status), true);
+		this.#resolvePrivateMode(mode, isPrivateModeSupported(status), true, Number.parseInt(status, 10));
 		if (isXtermScrollToBottomMode(mode) && isPrivateModeSet(status)) {
 			this.#disableXtermScrollToBottomMode(mode);
 		}
@@ -1549,12 +1557,12 @@ export class ProcessTerminal implements Terminal {
 	 * unsupported response from an absent response followed by the DA1 sentinel.
 	 * Enables DEC 2048 in-band resize only after positive confirmation.
 	 */
-	#resolvePrivateMode(mode: number, supported: boolean, confirmed: boolean): void {
+	#resolvePrivateMode(mode: number, supported: boolean, confirmed: boolean, status?: number): void {
 		if (this.#privateModeSupport.has(mode)) return;
 		this.#privateModeSupport.set(mode, supported);
 		for (const cb of this.#privateModeCallbacks) {
 			try {
-				cb(mode, supported, confirmed);
+				cb(mode, supported, confirmed, status);
 			} catch {
 				// Ignore subscriber errors — capability reporting must not crash input.
 			}

package/src/tui.ts

@@ -26,6 +26,7 @@ import {
 	encodeKittyPlacementLine,
 	ImageProtocol,
 	isImageProtocolForced,
+	isInsideHerdr,
 	isInsideTerminalMultiplexer,
 	parseKittyDirectPlacementLine,
 	setCellDimensions,
@@ -1108,9 +1109,15 @@ export class TUI extends Container {
 		// implementing DECRQM, so retain the statically detected default instead of
 		// exposing destructive full paints. An explicit user opt-out/force still
 		// wins, so skip every probe result in that case.
-		this.terminal.onPrivateModeReport?.((mode, supported, confirmed = true) => {
+		this.terminal.onPrivateModeReport?.((mode, supported, confirmed = true, status) => {
 			if (mode !== 2026 || !confirmed) return;
 			if (synchronizedOutputUserOverride() !== null) return;
+			// Herdr's Ghostty VTE honors DEC 2026 even when DECRQM is unanswered or
+			// reports unrecognized (status 0). Other confirmed unsupported reports
+			// still disable: status 4 is permanently reset, and a three-argument
+			// callback (`status` omitted) is a definitive unsupported from a
+			// custom Terminal that does not distinguish DECRPM codes.
+			if (!supported && isInsideHerdr() && status === 0) return;
 			this.#setSynchronizedOutput(supported);
 		});
 		this.terminal.start(