@oh-my-pi/pi-utils 18.1.4 → 18.1.5

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [18.1.5] - 2026-09-03
+
+### Added
+
+- Added `TerminalQueryResponder` to `@oh-my-pi/pi-utils/vterm`, enabling headless PTY consumers to answer common terminal queries for cursor position, device status and attributes, and foreground/background colors without maintaining a screen buffer.
+
 ## [18.1.3] - 2026-09-02
 
 ### Fixed

package/dist/types/async.d.ts

@@ -1,9 +1,9 @@
 /**
  * Wrap a promise with a timeout and optional abort signal.
- * Rejects with the given message if the timeout fires first.
- * Cleans up all listeners on settlement.
+ * Rejects with the given error or a new error containing the given message if
+ * the timeout fires first. Cleans up all listeners on settlement.
  */
-export declare function withTimeout<T>(promise: Promise<T>, ms: number, message: string, signal?: AbortSignal): Promise<T>;
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, timeout: string | Error, signal?: AbortSignal): Promise<T>;
 /**
  * Coalesces rapid-fire writes into one deferred batch. `push` queues a value
  * and returns a promise for the batch flush; the first push of a batch arms a

package/dist/types/vterm/query-responder.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Answers terminal capability queries emitted by programs on a headless PTY.
+ *
+ * A PTY that advertises `TERM=xterm-256color` but has no terminal behind it
+ * leaves capability probes unanswered: a program writes a query escape to
+ * stdout and blocks on stdin until the reply arrives (or its timeout expires,
+ * seconds later). This scanner watches raw PTY output for the standard queries
+ * and returns the bytes a real xterm-class terminal would send back, so the
+ * caller can write them into the PTY. It keeps no screen state — cursor
+ * position reports are answered with the home position — which makes it cheap
+ * enough to run on every byte of a long-lived supervised process. Use the full
+ * {@link Terminal} when the caller also renders the output.
+ *
+ * Queries can straddle chunk boundaries, so an unfinished trailing escape is
+ * carried into the next {@link feed}.
+ */
+export declare class TerminalQueryResponder {
+    #private;
+    /**
+     * Feed one raw PTY output chunk. Returns the reply bytes to write back into
+     * the PTY, or an empty string when the chunk held no answerable query.
+     */
+    feed(chunk: string): string;
+}

package/dist/types/vterm.d.ts

@@ -1,5 +1,6 @@
 /** Behavior-compatible reimplementation of @xterm/headless's used surface. */
 export * from "./vterm/buffer.js";
+export * from "./vterm/query-responder.js";
 export * from "./vterm/terminal.js";
 import { Terminal } from "./vterm/terminal.js";
 declare const vterm: {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.1.4",
+	"version": "18.1.5",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -31,7 +31,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.1.4"
+		"@oh-my-pi/pi-natives": "18.1.5"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/async.ts

@@ -1,9 +1,14 @@
 /**
  * Wrap a promise with a timeout and optional abort signal.
- * Rejects with the given message if the timeout fires first.
- * Cleans up all listeners on settlement.
+ * Rejects with the given error or a new error containing the given message if
+ * the timeout fires first. Cleans up all listeners on settlement.
  */
-export function withTimeout<T>(promise: Promise<T>, ms: number, message: string, signal?: AbortSignal): Promise<T> {
+export function withTimeout<T>(
+	promise: Promise<T>,
+	ms: number,
+	timeout: string | Error,
+	signal?: AbortSignal,
+): Promise<T> {
 	if (signal?.aborted) {
 		const reason = signal.reason instanceof Error ? signal.reason : new Error("Aborted");
 		return Promise.reject(reason);
@@ -15,7 +20,7 @@ export function withTimeout<T>(promise: Promise<T>, ms: number, message: string,
 		if (settled) return;
 		settled = true;
 		if (signal) signal.removeEventListener("abort", onAbort);
-		reject(new Error(message));
+		reject(typeof timeout === "string" ? new Error(timeout) : timeout);
 	}, ms);
 
 	const onAbort = () => {

package/src/vterm/query-responder.ts

@@ -0,0 +1,76 @@
+/**
+ * Answers terminal capability queries emitted by programs on a headless PTY.
+ *
+ * A PTY that advertises `TERM=xterm-256color` but has no terminal behind it
+ * leaves capability probes unanswered: a program writes a query escape to
+ * stdout and blocks on stdin until the reply arrives (or its timeout expires,
+ * seconds later). This scanner watches raw PTY output for the standard queries
+ * and returns the bytes a real xterm-class terminal would send back, so the
+ * caller can write them into the PTY. It keeps no screen state — cursor
+ * position reports are answered with the home position — which makes it cheap
+ * enough to run on every byte of a long-lived supervised process. Use the full
+ * {@link Terminal} when the caller also renders the output.
+ *
+ * Queries can straddle chunk boundaries, so an unfinished trailing escape is
+ * carried into the next {@link feed}.
+ */
+export class TerminalQueryResponder {
+	/** Trailing bytes that may be the start of an unfinished query escape. */
+	#residual = "";
+
+	/**
+	 * Feed one raw PTY output chunk. Returns the reply bytes to write back into
+	 * the PTY, or an empty string when the chunk held no answerable query.
+	 */
+	feed(chunk: string): string {
+		const buffer = this.#residual + chunk;
+		let replies = "";
+		let lastEnd = 0;
+		QUERY.lastIndex = 0;
+		for (let match = QUERY.exec(buffer); match !== null; match = QUERY.exec(buffer)) {
+			lastEnd = match.index + match[0].length;
+			replies += replyFor(match);
+		}
+		// Keep only a short unmatched trailing escape: a query split across
+		// chunks completes on the next feed, while a long tail is ordinary output
+		// that can never become a query.
+		const tailEscape = buffer.lastIndexOf("\x1b");
+		this.#residual =
+			tailEscape >= lastEnd && buffer.length - tailEscape <= MAX_PARTIAL_QUERY ? buffer.slice(tailEscape) : "";
+		return replies;
+	}
+}
+
+/** Longest query escape we answer, bounding the cross-chunk residual. */
+const MAX_PARTIAL_QUERY = 32;
+
+/**
+ * CSI DSR/DA queries (final byte `n` or `c`) and OSC 10/11 color queries. Only
+ * forms with canned answers are matched; everything else stays plain output.
+ */
+const QUERY = /\x1b\[([?>=]?)([0-9;]*)([nc])|\x1b\](10|11);\?(\x07|\x1b\\)/gu;
+
+/** Reply a real xterm-class terminal would send for one matched query. */
+function replyFor(match: RegExpExecArray): string {
+	const final = match[3];
+	if (final !== undefined) {
+		const intermediate = match[1];
+		const params = match[2] ?? "";
+		if (final === "c") {
+			if (intermediate === ">") return "\x1b[>0;10;1c"; // secondary DA: VT100-class, firmware 10
+			if (intermediate === "" || intermediate === "0") return "\x1b[?1;2c"; // primary DA: VT100 with AVO
+			return ""; // tertiary (`=`) DA has no widely expected reply
+		}
+		if (intermediate !== "") return ""; // private DSR forms (DECXCPR, appearance) stay unanswered
+		const selector = params.split(";", 1)[0];
+		if (selector === "6") return "\x1b[1;1R"; // cursor position: home, there is no screen
+		if (selector === "5") return "\x1b[0n"; // device status: OK
+		return "";
+	}
+	// OSC color queries: neutral colors, terminated the way the request was.
+	const selector = match[4];
+	const terminator = match[5] ?? "\x07";
+	if (selector === "10") return `\x1b]10;rgb:ffff/ffff/ffff${terminator}`; // foreground
+	if (selector === "11") return `\x1b]11;rgb:0000/0000/0000${terminator}`; // background
+	return "";
+}

package/src/vterm.ts

@@ -1,5 +1,6 @@
 /** Behavior-compatible reimplementation of @xterm/headless's used surface. */
 export * from "./vterm/buffer";
+export * from "./vterm/query-responder";
 export * from "./vterm/terminal";
 
 import { Terminal } from "./vterm/terminal";