@linxiraos/pi-tui 1.0.0

package/src/loop-watchdog.ts

@@ -0,0 +1,115 @@
+import { performance } from "node:perf_hooks";
+import { logger, takeRecentLoopPhase } from "@linxiraos/pi-utils";
+
+export interface LoopWatchdogOptions {
+	/** How far ahead each probe tick is scheduled, in ms. Default 250. */
+	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. */
+	sleepMs?: number;
+	/** Monotonic clock source; injectable for tests. Default `performance.now`. */
+	now?: () => number;
+	/** Timer source; injectable for tests. Default `setTimeout`. */
+	schedule?: (cb: () => void, ms: number) => LoopWatchdogTimer;
+}
+
+/**
+ * Timer handle the watchdog arms. `cancel`, when present, is invoked on stop()
+ * so a stopped watchdog leaves no armed timer to wake the loop even once.
+ */
+interface LoopWatchdogTimer {
+	unref?(): void;
+	cancel?(): void;
+}
+
+/**
+ * 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
+ * the loop was blocked that long. The overshoot is logged once on the rising
+ * edge (one block ⇒ one line, deduped via `#wasBlocked`), tagged with the phase
+ * active during the elapsed interval via {@link takeRecentLoopPhase} — which
+ * survives the synchronous push/pop the instrumented hot paths do before this
+ * delayed tick can run — so the stall names its cause instead of "unknown".
+ *
+ * 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.
+ */
+export class LoopWatchdog {
+	#intervalMs: number;
+	#thresholdMs: number;
+	#sleepMs: number;
+	#now: () => number;
+	#schedule: (cb: () => void, ms: number) => LoopWatchdogTimer;
+	#expected = 0;
+	#wasBlocked = false;
+	#running = false;
+	// Bumped by stop(); each scheduled tick captures the generation it was armed
+	// under and no-ops if it no longer matches, so a start()→stop()→start() cycle
+	// cannot leave the pre-stop timer chain rescheduling itself in parallel.
+	#generation = 0;
+	#handle: LoopWatchdogTimer | undefined;
+
+	constructor(options: LoopWatchdogOptions = {}) {
+		this.#intervalMs = options.intervalMs ?? 250;
+		this.#thresholdMs = options.thresholdMs ?? 250;
+		this.#sleepMs = options.sleepMs ?? 60_000;
+		this.#now = options.now ?? (() => performance.now());
+		this.#schedule =
+			options.schedule ??
+			((cb, ms) => {
+				const timer = setTimeout(cb, ms);
+				return { unref: () => timer.unref?.(), cancel: () => clearTimeout(timer) };
+			});
+	}
+
+	start(): void {
+		if (this.#running) return;
+		this.#running = true;
+		this.#wasBlocked = false;
+		this.#armTick();
+	}
+
+	stop(): void {
+		this.#running = false;
+		this.#wasBlocked = false;
+		this.#generation++;
+		this.#handle?.cancel?.();
+		this.#handle = undefined;
+	}
+
+	#armTick(): void {
+		const generation = this.#generation;
+		this.#expected = this.#now() + this.#intervalMs;
+		this.#handle = this.#schedule(() => this.#tick(generation), this.#intervalMs);
+		this.#handle.unref?.();
+	}
+
+	#tick(generation: number): void {
+		if (!this.#running || generation !== this.#generation) return;
+		const blockedMs = this.#now() - this.#expected;
+		// 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) {
+				this.#wasBlocked = false;
+			} else if (!this.#wasBlocked) {
+				this.#wasBlocked = true;
+				logger.warn("ui.loop-blocked", {
+					blockedMs: Math.round(blockedMs),
+					phase: phase ?? "unknown",
+				});
+			}
+		} else {
+			this.#wasBlocked = false;
+		}
+		this.#armTick();
+	}
+}

package/src/mouse.ts

@@ -0,0 +1,105 @@
+/**
+ * SGR mouse report parsing (`\x1b[<button;col;rowM` / `…m`).
+ *
+ * Mouse tracking is enabled only while a fullscreen overlay holds the
+ * alternate screen (see tui.ts MOUSE_TRACKING_ON), so consumers are
+ * fullscreen components hit-testing against their own rendered frame:
+ * the frame paints from screen row 0, hence `row`/`col` are exposed
+ * 0-based for direct indexing into rendered lines.
+ */
+
+/** A decoded SGR mouse report. */
+export interface SgrMouseEvent {
+	/** Raw button code (bit 32 = motion, bit 64 = wheel, low bits = button). */
+	button: number;
+	/** 0-based column of the event. */
+	col: number;
+	/** 0-based row of the event. */
+	row: number;
+	/** True for a release report (`m` suffix). */
+	release: boolean;
+	/** Wheel direction: -1 up, 1 down, null when not a wheel event. */
+	wheel: -1 | 1 | null;
+	/** True when the pointer moved (hover or drag) rather than clicked. */
+	motion: boolean;
+	/** True for a left-button press (not motion, not release, not wheel). */
+	leftClick: boolean;
+}
+
+/**
+ * Decode an SGR mouse report, or return null when `data` is not one.
+ * Callers on hot keypress paths should pre-check `data.startsWith("\x1b[<")`
+ * before paying for the regex.
+ */
+export function parseSgrMouse(data: string): SgrMouseEvent | null {
+	const match = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/.exec(data);
+	if (!match) return null;
+	const button = Number(match[1]);
+	const col = Number(match[2]) - 1;
+	const row = Number(match[3]) - 1;
+	const release = match[4] === "m";
+	const wheel = button & 64 ? ((button & 1 ? 1 : -1) as 1 | -1) : null;
+	const motion = (button & 32) !== 0 && wheel === null;
+	const leftClick = !release && wheel === null && !motion && (button & 3) === 0;
+	return { button, col, row, release, wheel, motion, leftClick };
+}
+
+/** Handler invoked with a decoded SGR event; returning `false` reports unhandled. */
+export type SgrMouseHandler = (event: SgrMouseEvent) => boolean | undefined;
+
+/**
+ * Decode an SGR mouse report and forward it to `handler`. Returns `false` when
+ * `data` is not an SGR mouse report (or fails to parse), so callers can fall
+ * through to other input handling. Centralizes the repeated
+ * `data.startsWith("\x1b[<")` + `parseSgrMouse()` pattern.
+ */
+export function routeSgrMouseInput(data: string, handler: SgrMouseHandler): boolean {
+	if (!data.startsWith("\x1b[<")) return false;
+	const event = parseSgrMouse(data);
+	if (!event) return false;
+	return handler(event) !== false;
+}
+
+/**
+ * Structural view of a SelectList-like target for mouse routing. Declared here
+ * (rather than importing the component) to keep this core module free of any
+ * component-to-core import cycle.
+ */
+export interface SelectListMouseTarget {
+	handleWheel(delta: -1 | 1): void;
+	hitTest(line: number): number | undefined;
+	setHoverIndex(index: number | null): void;
+	clickItem(index: number): void;
+}
+
+/**
+ * Route a decoded mouse event against a SelectList-like target at the given
+ * 0-based frame-local `line`. Centralizes the repeated wheel/hit-test/hover/
+ * click pattern. Returns `true` when the event was consumed.
+ */
+export function routeSelectListMouse(target: SelectListMouseTarget, event: SgrMouseEvent, line: number): boolean {
+	if (event.wheel !== null) {
+		target.handleWheel(event.wheel);
+		return true;
+	}
+	const index = target.hitTest(line);
+	if (event.motion) {
+		target.setHoverIndex(index ?? null);
+		return true;
+	}
+	if (event.leftClick && index !== undefined) {
+		target.clickItem(index);
+		return true;
+	}
+	return false;
+}
+
+/**
+ * Implemented by components that accept routed mouse events at frame-local
+ * coordinates. Hosts translate screen coordinates to the component's own
+ * rendered lines before forwarding.
+ */
+export interface MouseRoutable {
+	/** `line`/`col` are 0-based within the component's rendered output. */
+	routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+}