@linxiraos/pi-tui 1.0.4 → 1.0.6

package/dist/types/utils.d.ts

@@ -0,0 +1,112 @@
+import { Ellipsis, type ExtractSegmentsResult, type SliceResult } from "@linxiraos/pi-natives";
+export { Ellipsis } from "@linxiraos/pi-natives";
+export { DEFAULT_TAB_WIDTH } from "@linxiraos/pi-utils";
+export type HangulCompatibilityJamoWidth = "platform" | "unicode" | 1 | 2;
+export declare function getHangulCompatibilityJamoWidth(): HangulCompatibilityJamoWidth;
+export declare function getWidthConfigEpoch(): number;
+/** Publish exact per-line visible widths for a rendered lines array. */
+export declare function publishLineWidths(lines: readonly string[], widths: readonly number[]): void;
+/** Exact per-line visible widths for an unchanged `lines` array under the current width config. */
+export declare function getPublishedLineWidths(lines: readonly string[]): readonly number[] | undefined;
+export declare function setHangulCompatibilityJamoWidth(width: HangulCompatibilityJamoWidth): boolean;
+export declare function resetHangulCompatibilityJamoWidthForTests(): void;
+export type TextSizingScale = 1 | 2 | 3;
+export type TextSizingVerticalAlign = "top" | "bottom" | "center";
+export type TextSizingHorizontalAlign = "left" | "right" | "center";
+export interface TextSizingOptions {
+    scale?: TextSizingScale;
+    widthCells?: number;
+    verticalAlign?: TextSizingVerticalAlign;
+    horizontalAlign?: TextSizingHorizontalAlign;
+}
+/**
+ * Encode a plain-text span using Kitty's OSC 66 text-sizing protocol. The TUI
+ * emits only safe UTF-8 payloads and ST terminators so its ANSI parser and the
+ * terminal agree on span boundaries.
+ */
+export declare function encodeTextSized(text: string, options?: TextSizingOptions): string;
+export declare function sliceWithWidth(line: string, startCol: number, length: number, strict?: boolean | null): SliceResult;
+export declare function truncateToWidth(text: string, maxWidth: number, ellipsisKind?: Ellipsis | null | "", pad?: boolean | null): string;
+export declare function wrapTextWithAnsi(text: string, width: number): string[];
+export declare function extractSegments(line: string, beforeEnd: number, afterStart: number, afterLen: number, strictAfter: boolean): ExtractSegmentsResult;
+export declare function replaceTabs(text: string): string;
+/**
+ * Returns a string of n spaces. Uses a pre-allocated buffer for efficiency.
+ */
+export declare function padding(n: number): string;
+/**
+ * Get the shared grapheme segmenter instance.
+ */
+export declare function getSegmenter(): Intl.Segmenter;
+/**
+ * Visible width of a string in terminal columns, excluding ANSI/OSC escapes.
+ *
+ * `Bun.stringWidth` does the heavy lifting (UAX#11 width tables + ANSI/OSC
+ * stripping); this adds the two corrections it omits — tabs (expanded to
+ * `tabWidth` cells) and OSC 66 text-sizing payloads (scaled by `s=`).
+ */
+export declare function visibleWidth(str: string): number;
+/**
+ * True when a row carries a Kitty OSC 66 text-sizing span (`\x1b]66;…`).
+ * Scaled spans must bypass wrapping/padding and, when scaled up, reserve the
+ * terminal rows their multicell glyphs flow into.
+ */
+export declare function isOsc66Line(line: string): boolean;
+/**
+ * Largest `s=` scale among the OSC 66 spans in a line (1 when none is scaled).
+ * A scale-`s` heading occupies `s` terminal rows, so the `s - 1` blank rows
+ * beneath it are the glyph's lower half and must never be erased or overdrawn.
+ */
+export declare function osc66MaxScale(line: string): number;
+/**
+ * Normalize text for terminal output without changing logical editor content.
+ * Some terminals render precomposed Thai/Lao AM vowels inconsistently during
+ * differential repaint. Their compatibility decompositions have the same cell
+ * width but avoid stale-cell artifacts in terminal renderers.
+ */
+export declare function normalizeTerminalOutput(str: string): string;
+/**
+ * Check if a character is whitespace.
+ */
+export declare function isWhitespaceChar(char: string): boolean;
+/**
+ * Check if a character is punctuation.
+ */
+export declare function isPunctuationChar(char: string): boolean;
+export type WordNavKind = "whitespace" | "delimiter" | "cjk" | "word" | "other";
+/**
+ * Coarse Unicode-aware character classification for word navigation (Option/Alt + Left/Right).
+ * This intentionally avoids language-specific word segmentation for predictability across scripts.
+ */
+export declare function getWordNavKind(grapheme: string): WordNavKind;
+export declare function isWordNavJoiner(grapheme: string): boolean;
+/**
+ * Move the cursor one "word" to the left using Unicode-aware coarse navigation.
+ *
+ * Returns a new cursor index in the range [0, text.length].
+ */
+export declare function moveWordLeft(text: string, cursor: number): number;
+/**
+ * Move the cursor one "word" to the right using Unicode-aware coarse navigation.
+ *
+ * Returns a new cursor index in the range [0, text.length].
+ */
+export declare function moveWordRight(text: string, cursor: number): number;
+/**
+ * Apply background color to a line, padding to full width.
+ *
+ * @param line - Line of text (may contain ANSI codes)
+ * @param width - Total width to pad to
+ * @param bgFn - Background color function
+ * @returns Line with background applied and padded to width
+ */
+export declare function applyBackgroundToLine(line: string, width: number, bgFn: (text: string) => string): string;
+/**
+ * Extract a range of visible columns from a line. Handles ANSI codes and wide chars.
+ *
+ * @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,69 +1,70 @@
-{
-  "type": "module",
-  "name": "@linxiraos/pi-tui",
-  "version": "1.0.4",
-  "description": "Terminal User Interface library with differential rendering for efficient text-based applications",
-  "homepage": "https://linxira-os.github.io",
-  "author": "Can Boluk",
-  "contributors": [
-    "Mario Zechner"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
-    "directory": "packages/tui"
-  },
-  "bugs": {
-    "url": "https://github.com/can1357/oh-my-pi/issues"
-  },
-  "keywords": [
-    "tui",
-    "terminal",
-    "ui",
-    "text-editor",
-    "differential-rendering",
-    "typescript",
-    "cli"
-  ],
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
-  "scripts": {
-    "check": "biome check . && bun run check:types",
-    "check:types": "tsgo -p tsconfig.json --noEmit",
-    "lint": "biome lint .",
-    "test": "bun test --parallel test/*.test.ts",
-    "fix": "biome check --write --unsafe .",
-    "fmt": "biome format --write ."
-  },
-  "dependencies": {
-    "@linxiraos/pi-natives": "1.0.2",
-    "@linxiraos/pi-utils": "1.0.4"
-  },
-  "devDependencies": {
-    "ghostty-web": "^0.4.0"
-  },
-  "engines": {
-    "bun": ">=1.3.14"
-  },
-  "files": [
-    "src",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
-    },
-    "./*": {
-      "types": "./src/*.ts",
-      "import": "./src/*.ts"
-    },
-    "./components/*": {
-      "types": "./src/components/*.ts",
-      "import": "./src/components/*.ts"
-    },
-    "./*.js": "./src/*.ts"
-  }
-}
+{
+	"type": "module",
+	"name": "@linxiraos/pi-tui",
+	"version": "1.0.6",
+	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
+	"homepage": "https://linxira-os.github.io",
+	"author": "Can Boluk",
+	"contributors": [
+		"Mario Zechner"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
+		"directory": "packages/tui"
+	},
+	"bugs": {
+		"url": "https://github.com/can1357/oh-my-pi/issues"
+	},
+	"keywords": [
+		"tui",
+		"terminal",
+		"ui",
+		"text-editor",
+		"differential-rendering",
+		"typescript",
+		"cli"
+	],
+	"main": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"test": "bun test --parallel test/*.test.ts",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"@linxiraos/pi-natives": "1.0.2",
+		"@linxiraos/pi-utils": "1.0.6"
+	},
+	"devDependencies": {
+		"ghostty-web": "^0.4.0"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"dist/types"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./dist/types/*.d.ts",
+			"import": "./src/*.ts"
+		},
+		"./components/*": {
+			"types": "./dist/types/components/*.d.ts",
+			"import": "./src/components/*.ts"
+		},
+		"./*.js": "./src/*.ts"
+	}
+}

package/src/keys.ts

@@ -198,7 +198,7 @@ export type KeyId = BaseKey | ModifiedKeyId<BaseKey>;
  * modifier methods return precisely-typed concatenations (e.g. `Key.ctrl("c")`
  * is `"ctrl+c"`, not just `string`). This mirrors the upstream
  * `@mariozechner/pi-tui` `Key` export verbatim so plugins built against any
- * scope alias (`@mariozechner`, `@earendil-works`, `@oh-my-pi`) keep working
+ * scope alias (`@mariozechner`, `@earendil-works`, `@linxiraos`) keep working
  * once the specifier shim remaps them to this package.
  */
 export const Key = {

package/src/loop-watchdog.ts

@@ -6,10 +6,12 @@ export interface LoopWatchdogOptions {
 	intervalMs?: number;
 	/** A tick later than this past its deadline counts as a block. Default 250. */
 	thresholdMs?: number;
-	/** Overshoot beyond this likely includes system sleep, so it is suppressed. Default 60_000. */
+	/** Overshoot beyond this is suppressed only when the process burned negligible CPU. Default 60_000. */
 	sleepMs?: number;
 	/** Monotonic clock source; injectable for tests. Default `performance.now`. */
 	now?: () => number;
+	/** Process CPU time in ms; injectable for tests. Default `process.cpuUsage`. */
+	cpuNow?: () => number;
 	/** Timer source; injectable for tests. Default `setTimeout`. */
 	schedule?: (cb: () => void, ms: number) => LoopWatchdogTimer;
 }
@@ -23,6 +25,15 @@ interface LoopWatchdogTimer {
 	cancel?(): void;
 }
 
+/**
+ * Fraction of a missed interval that may be process CPU time while the gap is
+ * still treated as system sleep. Keep this near zero: cgroup throttling and
+ * scheduler contention can make a CPU-bound loop consume far less CPU than wall
+ * time. One percent allows a little measurement/background jitter while erring
+ * toward reporting a severe stall instead of hiding it.
+ */
+const CPU_BUSY_RATIO = 0.01;
+
 /**
  * Always-on event-loop lag probe. Each tick is scheduled `intervalMs` ahead of
  * a recorded deadline; a tick that fires `thresholdMs` past its deadline means
@@ -35,18 +46,23 @@ interface LoopWatchdogTimer {
  * The handle is `unref`'d so the probe never keeps the process alive, and stop()
  * cancels the armed timer when the handle exposes `cancel` (the default
  * `setTimeout` handle does, via `clearTimeout`). The `#generation` guard remains
- * as a fallback for injected handles that cannot cancel. An overshoot beyond
- * `sleepMs` is treated as system sleep rather than a synchronous stall: the
- * process could not have run JS during the missed interval, and one resume
- * should not produce a multi-minute `ui.loop-blocked` record.
+ * as a fallback for injected handles that cannot cancel.
+ *
+ * A long overshoot is classified by CPU time rather than by duration. System
+ * sleep and a CPU-bound wedge both produce an arbitrarily large gap, so duration
+ * alone cannot tell them apart, and suppressing on duration discards exactly the
+ * worst stalls. Only a gap the process spent negligible CPU on is treated as
+ * sleep. CPU accounting is process-wide, so worker activity errs toward logging.
  */
 export class LoopWatchdog {
 	#intervalMs: number;
 	#thresholdMs: number;
 	#sleepMs: number;
 	#now: () => number;
+	#cpuNow: () => number;
 	#schedule: (cb: () => void, ms: number) => LoopWatchdogTimer;
 	#expected = 0;
+	#expectedCpu = 0;
 	#wasBlocked = false;
 	#running = false;
 	// Bumped by stop(); each scheduled tick captures the generation it was armed
@@ -60,6 +76,12 @@ export class LoopWatchdog {
 		this.#thresholdMs = options.thresholdMs ?? 250;
 		this.#sleepMs = options.sleepMs ?? 60_000;
 		this.#now = options.now ?? (() => performance.now());
+		this.#cpuNow =
+			options.cpuNow ??
+			(() => {
+				const usage = process.cpuUsage();
+				return (usage.user + usage.system) / 1000;
+			});
 		this.#schedule =
 			options.schedule ??
 			((cb, ms) => {
@@ -86,6 +108,7 @@ export class LoopWatchdog {
 	#armTick(): void {
 		const generation = this.#generation;
 		this.#expected = this.#now() + this.#intervalMs;
+		this.#expectedCpu = this.#cpuNow();
 		this.#handle = this.#schedule(() => this.#tick(generation), this.#intervalMs);
 		this.#handle.unref?.();
 	}
@@ -93,17 +116,20 @@ export class LoopWatchdog {
 	#tick(generation: number): void {
 		if (!this.#running || generation !== this.#generation) return;
 		const blockedMs = this.#now() - this.#expected;
+		const cpuMs = this.#cpuNow() - this.#expectedCpu;
 		// Consume the recent phase every tick (block or not) so attribution is
 		// scoped to the just-elapsed interval and never carries a stale phase
 		// forward to a later, phase-less block.
 		const phase = takeRecentLoopPhase();
 		if (blockedMs > this.#thresholdMs) {
-			if (blockedMs > this.#sleepMs) {
+			if (blockedMs > this.#sleepMs && cpuMs < blockedMs * CPU_BUSY_RATIO) {
+				// A long gap the process did not spend CPU on: it was suspended.
 				this.#wasBlocked = false;
 			} else if (!this.#wasBlocked) {
 				this.#wasBlocked = true;
 				logger.warn("ui.loop-blocked", {
 					blockedMs: Math.round(blockedMs),
+					cpuMs: Math.round(cpuMs),
 					phase: phase ?? "unknown",
 				});
 			}

package/src/terminal.ts

@@ -945,10 +945,11 @@ export class ProcessTerminal implements Terminal {
 			// flush timeout elapses mid-sequence, the prefix `\x1b[?<digits>` arrives as
 			// one event and the tail `;...<terminator>` arrives as individual character
 			// events that would otherwise leak into the prompt as keystrokes. See #1238.
-			if (
-				this.#privateCsiResponseBuffer ||
-				(privateCsiPartialPattern.test(sequence) && this.#da1SentinelOwners.length > 0)
-			) {
+			// A private CSI (`\x1b[?…`) is a terminal->host report, never a keystroke, so
+			// reassembly stays armed for the whole session — not just while a probe
+			// sentinel is outstanding — otherwise a reply that lands after the sentinel
+			// FIFO drains (slow SSH/PTY links) leaks its tail into the composer (#8542).
+			if (this.#privateCsiResponseBuffer || privateCsiPartialPattern.test(sequence)) {
 				if (this.#privateCsiResponseBuffer && sequence.startsWith("\x1b")) {
 					// New escape arrived mid-reassembly — abandon partial and re-process the new sequence.
 					this.#privateCsiResponseBuffer = "";
@@ -1038,10 +1039,16 @@ export class ProcessTerminal implements Terminal {
 			}
 
 			// DA1 response: swallow our sentinel reply regardless of whether an
-			// earlier capability-specific response already succeeded. Other terminal
-			// probes should never see these replies.
-			if (da1ResponsePattern.test(sequence) && this.#da1SentinelOwners.length > 0) {
-				const owner = this.#da1SentinelOwners.shift()!;
+			// earlier capability-specific response already succeeded. `CSI ? … c` is
+			// exclusively a terminal->host report, so it is swallowed even with no
+			// outstanding sentinel — a reply that arrives after the FIFO drains (slow
+			// SSH/PTY links) must never reach the composer as literal text (#8542).
+			if (da1ResponsePattern.test(sequence)) {
+				const owner = this.#da1SentinelOwners.shift();
+				if (!owner) {
+					// Late/unowned reply: nothing to resolve, just drop the bytes.
+					return;
+				}
 				switch (owner.kind) {
 					case "osc11": {
 						if (this.#osc11Pending) {

package/src/tui.ts

@@ -1772,13 +1772,76 @@ export class TUI extends Container {
 		markers.length = keep;
 	}
 
+	/**
+	 * Replace the cursor markers contributed by one fixed-size root segment.
+	 * The ledger stays sorted by absolute frame row; entries belonging to later
+	 * siblings move as one tail and otherwise retain their identity.
+	 */
+	#replaceFrameCursorMarkers(startRow: number, lines: readonly string[]): void {
+		const markers = this.#frameCursorMarkers;
+		const endRow = startRow + lines.length;
+		let intervalStart = 0;
+		while (intervalStart < markers.length && markers[intervalStart]!.row < startRow) intervalStart++;
+		let intervalEnd = intervalStart;
+		while (intervalEnd < markers.length && markers[intervalEnd]!.row < endRow) intervalEnd++;
+
+		let nextCount = 0;
+		for (let row = 0; row < lines.length; row++) {
+			if (lines[row]!.includes(CURSOR_MARKER)) nextCount++;
+		}
+
+		const previousCount = intervalEnd - intervalStart;
+		const delta = nextCount - previousCount;
+		const previousLength = markers.length;
+		if (delta > 0) {
+			markers.length = previousLength + delta;
+			for (let index = previousLength - 1; index >= intervalEnd; index--) {
+				markers[index + delta] = markers[index]!;
+			}
+		} else if (delta < 0) {
+			for (let index = intervalEnd; index < previousLength; index++) {
+				markers[index + delta] = markers[index]!;
+			}
+			markers.length = previousLength + delta;
+		}
+
+		const reusableCount = Math.min(previousCount, nextCount);
+		let markerSlot = intervalStart;
+		for (let row = 0; row < lines.length; row++) {
+			const line = lines[row]!;
+			const markerIndex = line.indexOf(CURSOR_MARKER);
+			if (markerIndex === -1) continue;
+			const absoluteRow = startRow + row;
+			const col = visibleWidth(line.slice(0, markerIndex));
+			if (markerSlot < intervalStart + reusableCount) {
+				const marker = markers[markerSlot]!;
+				marker.row = absoluteRow;
+				marker.col = col;
+			} else {
+				markers[markerSlot] = { row: absoluteRow, col };
+			}
+			markerSlot++;
+		}
+	}
+
+	/** Strip every internal cursor sentinel from one rendered row. */
+	#stripCursorMarkers(line: string, markerIndex = line.indexOf(CURSOR_MARKER)): string {
+		if (markerIndex === -1) return line;
+		let stripped = line;
+		while (markerIndex !== -1) {
+			stripped = stripped.slice(0, markerIndex) + stripped.slice(markerIndex + CURSOR_MARKER.length);
+			markerIndex = stripped.indexOf(CURSOR_MARKER, markerIndex);
+		}
+		return stripped;
+	}
+
 	/**
 	 * Append one row to the composed frame, stripping CURSOR_MARKER occurrences
 	 * (internal sentinels that must never reach the terminal, the committed
 	 * prefix, or the resync audit) and recording the first marker's position.
 	 */
 	#ingestFrameRow(line: string): void {
-		let markerIndex = line.indexOf(CURSOR_MARKER);
+		const markerIndex = line.indexOf(CURSOR_MARKER);
 		if (markerIndex === -1) {
 			this.#composedFrame.push(line);
 			return;
@@ -1787,12 +1850,7 @@ export class TUI extends Container {
 			row: this.#composedFrame.length,
 			col: visibleWidth(line.slice(0, markerIndex)),
 		});
-		let stripped = line;
-		while (markerIndex !== -1) {
-			stripped = stripped.slice(0, markerIndex) + stripped.slice(markerIndex + CURSOR_MARKER.length);
-			markerIndex = stripped.indexOf(CURSOR_MARKER, markerIndex);
-		}
-		this.#composedFrame.push(stripped);
+		this.#composedFrame.push(this.#stripCursorMarkers(line, markerIndex));
 	}
 
 	#syncTerminalCursorMode(component: Component | null): void {
@@ -2558,12 +2616,6 @@ export class TUI extends Container {
 			this.requestComponentRender(component);
 			return;
 		}
-		for (const line of nextLines) {
-			if (line.includes(CURSOR_MARKER)) {
-				this.requestComponentRender(component);
-				return;
-			}
-		}
 
 		let firstChanged = -1;
 		let lastChanged = -1;
@@ -2571,8 +2623,9 @@ export class TUI extends Container {
 		for (let i = 0; i < nextLines.length; i++) {
 			const frameRow = segment.start + i;
 			const raw = nextLines[i]!;
-			const prepared = this.#prepareLine(raw, width);
-			this.#composedFrame[frameRow] = raw;
+			const composed = this.#stripCursorMarkers(raw);
+			const prepared = this.#prepareLine(composed, width);
+			this.#composedFrame[frameRow] = composed;
 			this.#preparedMeta[frameRow] = prepared;
 			this.#preparedFrame[frameRow] = prepared.line;
 			if (previousWindow[screenStart + i] === prepared.line) continue;
@@ -2580,7 +2633,8 @@ export class TUI extends Container {
 			if (firstChanged === -1) firstChanged = i;
 			lastChanged = i;
 		}
-		segments[segmentIndex] = { ...segment, lines: nextLines };
+		this.#replaceFrameCursorMarkers(segment.start, nextLines);
+		segment.lines = nextLines;
 		this.#preparedValidRows = Math.max(this.#preparedValidRows, segment.start + nextLines.length);
 		this.#renderStablePrefixRows = Math.min(this.#renderStablePrefixRows, segment.start);