@oh-my-pi/pi-tui 17.3.4 → 17.3.7

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [17.3.5] - 2026-08-16
+
+### Fixed
+
+- Fixed long CPU-bound event-loop stalls being misclassified as system sleep and omitted from loop-blocked diagnostics.
+- Fixed focused components with markers falling back to full-screen redraws instead of direct row updates, preserving cursor position and native scrollback across marker changes.
+
 ## [17.3.4] - 2026-08-14
 
 ### Fixed

package/dist/types/loop-watchdog.d.ts

@@ -3,10 +3,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;
 }
@@ -30,10 +32,13 @@ 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 declare class LoopWatchdog {
     #private;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "17.3.4",
+	"version": "17.3.7",
 	"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": "17.3.4",
-		"@oh-my-pi/pi-utils": "17.3.4"
+		"@oh-my-pi/pi-natives": "17.3.7",
+		"@oh-my-pi/pi-utils": "17.3.7"
 	},
 	"devDependencies": {
 		"ghostty-web": "^0.4.0"

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/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);