@gajae-code/tui 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-06-05
+
+### Changed
+
+- Added replay-gate helper timing for text-layout utilities so Stage 5 native offload decisions are benchmark-gated by measured hot paths rather than speculative rewrites.
+
 ## [0.2.2] - 2026-05-31
 
 ### Changed

package/dist/types/index.d.ts

@@ -16,6 +16,7 @@ export type * from "./editor-component";
 export * from "./fuzzy";
 export * from "./keybindings";
 export * from "./keys";
+export * from "./metrics";
 export * from "./stdin-buffer";
 export type * from "./symbols";
 export * from "./terminal";

package/dist/types/metrics.d.ts

@@ -0,0 +1,78 @@
+/** Number of consecutive unexpected full redraws that constitute a "storm". */
+export declare const REPAINT_STORM_THRESHOLD = 3;
+/** Hard cap on retained metric label keys; overflow is aggregated under `other`. */
+export declare const MAX_LABEL_MAP_ENTRIES = 128;
+export interface DurationStats {
+    count: number;
+    meanMs: number;
+    p50Ms: number;
+    p95Ms: number;
+    p99Ms: number;
+    maxMs: number;
+}
+export interface RssStats {
+    samples: number;
+    baselineBytes: number | null;
+    lastBytes: number | null;
+    peakBytes: number;
+    growthBytes: number;
+    /** RSS sampled after the run + a forced GC (informational). */
+    returnBytes: number | null;
+    /** Heap used at baseline and after the run + forced GC (reclaimable signal). */
+    heapBaselineBytes: number | null;
+    heapReturnBytes: number | null;
+    /** (heapReturn - heapBaseline) / heapBaseline; <= tolerance means heap returned. */
+    returnWithinBaselineFraction: number | null;
+}
+export interface HelperStat {
+    count: number;
+    totalMs: number;
+    meanMs: number;
+}
+export interface RenderMetricsSnapshot {
+    enabled: boolean;
+    renderCount: number;
+    renderDurations: DurationStats;
+    durationsTruncated: boolean;
+    requestSources: Record<string, number>;
+    fullRedrawCount: number;
+    fullRedrawCauses: Record<string, number>;
+    repaintStorms: number;
+    maxConsecutiveFullRedraws: number;
+    rss: RssStats;
+    ownerGauges: Record<string, number>;
+    timerGauges: Record<string, number>;
+    helperStats: Record<string, HelperStat>;
+}
+export declare class RenderMetrics {
+    #private;
+    constructor(enabled?: boolean);
+    get enabled(): boolean;
+    enable(): void;
+    disable(): void;
+    /** Reset all collected data (keeps the enabled state). */
+    reset(): void;
+    /** High-resolution clock for timing render passes. Returns 0 when disabled. */
+    now(): number;
+    /** Record that a render was requested, attributed to a caller source. */
+    recordRequest(source?: string): void;
+    /** Record one completed `#doRender` pass duration (ms). */
+    recordRender(durationMs: number): void;
+    /** Record a full-redraw event and classify its cause for storm detection. */
+    recordFullRedraw(cause: string): void;
+    /** Sample current RSS. Records baseline on first sample, tracks peak/last. */
+    sampleRss(): number;
+    setOwnerGauge(name: string, value: number): void;
+    setTimerGauge(name: string, value: number): void;
+    /** Accumulate timing/count for a named render helper (e.g. "renderTree"). */
+    recordHelper(name: string, durationMs: number): void;
+    /**
+     * Force a GC when the runtime exposes one and sample RSS as the post-run
+     * "return" value used by the memory-leak gate. Callers should drop large
+     * references before calling so reclaimable memory is actually freed.
+     */
+    sampleReturn(): number;
+    snapshot(): RenderMetricsSnapshot;
+}
+/** Shared metrics instance used by the TUI render loop. */
+export declare const renderMetrics: RenderMetrics;

package/dist/types/tui.d.ts

@@ -158,5 +158,5 @@ export declare class TUI extends Container {
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
     stop(): void;
-    requestRender(force?: boolean): void;
+    requestRender(force?: boolean, source?: string): void;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -33,12 +33,13 @@
 		"check:types": "tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
 		"test": "bun test test/*.test.ts",
+		"test:perf": "PI_TUI_PERF_GATES=1 bun test test/perf-gates.test.ts",
 		"fix": "biome check --write --unsafe .",
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.3.0",
-		"@gajae-code/utils": "0.3.0",
+		"@gajae-code/natives": "0.3.2",
+		"@gajae-code/utils": "0.3.2",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/components/loader.ts

@@ -7,13 +7,17 @@ import { Text } from "./text";
  * message colorizer is time-dependent (e.g. shimmer/KITT) animate smoothly.
  *
  * Two cadences are interleaved on a single timer:
- *   - **Render tick** (every `RENDER_INTERVAL_MS`) → asks the TUI to redraw.
- *     The TUI already throttles at 16ms (`MIN_RENDER_INTERVAL_MS`), so this
- *     is the natural upper bound; static messageColorFns produce identical
- *     output and the differ drops the no-op redraw at ~zero cost.
+ *   - **Recompute tick** (every `RENDER_INTERVAL_MS`) → recomposes the spinner +
+ *     colorized message every 16ms. A redraw is requested only when that composed
+ *     text actually changed since the last tick (`#lastDisplayed`), so animated
+ *     colorizers (shimmer/KITT) and spinner-frame advances still repaint, while
+ *     static loaders skip the redundant no-op render requests between advances.
  *   - **Spinner advance** (every `SPINNER_ADVANCE_MS`) → bumps the spinner
- *     frame index. Decoupled from the render cadence so the spinner keeps
+ *     frame index. Decoupled from the recompute cadence so the spinner keeps
  *     its classic ~12.5fps step pace regardless of shimmer state.
+ *
+ * The animation timer is `unref`'d so an active loader never keeps the event
+ * loop alive on its own.
  */
 const RENDER_INTERVAL_MS = 16;
 const SPINNER_ADVANCE_MS = 80;
@@ -24,6 +28,7 @@ export class Loader extends Text {
 	#intervalId?: NodeJS.Timeout;
 	#ui: TUI | null = null;
 	#lastSpinnerTick = 0;
+	#lastDisplayed?: string;
 
 	constructor(
 		ui: TUI,
@@ -62,6 +67,8 @@ export class Loader extends Text {
 			}
 			this.#updateDisplay();
 		}, RENDER_INTERVAL_MS);
+		// Don't let the animation timer keep the event loop alive on its own.
+		this.#intervalId?.unref?.();
 	}
 
 	stop() {
@@ -78,9 +85,15 @@ export class Loader extends Text {
 
 	#updateDisplay() {
 		const frame = this.#frames[this.#currentFrame];
-		this.setText(`${this.spinnerColorFn(frame)} ${this.messageColorFn(this.message)}`);
-		if (this.#ui) {
-			this.#ui.requestRender();
-		}
+		const next = `${this.spinnerColorFn(frame)} ${this.messageColorFn(this.message)}`;
+		// Only touch the component and ask the TUI to repaint when the rendered
+		// text actually changed. Time-dependent colorizers (shimmer/KITT) produce
+		// new text every tick and still animate; static loaders skip the ~16ms
+		// no-op render requests between 80ms spinner advances. Output is unchanged
+		// because a suppressed frame would have produced a no-op write anyway.
+		if (next === this.#lastDisplayed) return;
+		this.#lastDisplayed = next;
+		this.setText(next);
+		this.#ui?.requestRender(false, "loader");
 	}
 }

package/src/index.ts

@@ -24,6 +24,8 @@ export * from "./fuzzy";
 export * from "./keybindings";
 // Kitty keyboard protocol helpers
 export * from "./keys";
+// Renderer/runtime observability metrics (opt-in)
+export * from "./metrics";
 // Mermaid diagram support
 // Input buffering for batch splitting
 export * from "./stdin-buffer";

package/src/metrics.ts

@@ -0,0 +1,355 @@
+/**
+ * Opt-in renderer/runtime observability counters for the TUI.
+ *
+ * This module is the Stage 1 "observability foundation" surface. It is OFF by
+ * default and only collects data when explicitly enabled, either via the
+ * `PI_TUI_METRICS` environment flag or programmatically (used by the replay
+ * harness and tests). When disabled, every record call is a single boolean
+ * check at the call site, so default runtime overhead is negligible and no
+ * existing render behavior changes.
+ *
+ * It tracks:
+ *  - `#doRender` durations (p50/p95/p99/max/mean) — frame-time histogram.
+ *  - `requestRender` source attribution — which callers ask for renders.
+ *  - Full-redraw cause classification — why a frame fell back to full repaint.
+ *  - Repaint-storm detection — runs of consecutive unexpected full redraws.
+ *  - RSS samples — baseline/peak/last for memory-growth gates.
+ *  - Owner/timer gauges — long-lived resource counts for leak gates.
+ */
+import { performance } from "node:perf_hooks";
+import { $flag } from "@gajae-code/utils";
+
+/** Number of consecutive unexpected full redraws that constitute a "storm". */
+export const REPAINT_STORM_THRESHOLD = 3;
+
+/** Hard cap on retained render-duration samples to keep memory bounded. */
+const MAX_DURATION_SAMPLES = 200_000;
+
+/** Hard cap on retained metric label keys; overflow is aggregated under `other`. */
+export const MAX_LABEL_MAP_ENTRIES = 128;
+
+const LABEL_OVERFLOW_KEY = "other";
+
+/**
+ * Normalize full-redraw causes before retaining them as metric labels. Some
+ * render paths include dimensions in debug-facing reason strings; metrics keep
+ * the stable cause class so resize/delete storms cannot create unbounded label
+ * cardinality.
+ */
+function normalizeFullRedrawCause(cause: string): string {
+	const c = cause.toLowerCase();
+	if (c.startsWith("first render")) return "first render";
+	if (c.startsWith("terminal width changed")) return "terminal width changed";
+	if (c.startsWith("terminal height changed")) return "terminal height changed";
+	if (c.startsWith("clearonshrink")) return "clearOnShrink";
+	if (c.startsWith("extralines > height")) return "extraLines > height";
+	if (c.startsWith("firstchanged < viewporttop")) return "firstChanged < viewportTop";
+	return cause;
+}
+
+/**
+ * Full-redraw causes that are expected and do not count toward repaint storms.
+ * These are legitimate, unavoidable full repaints (first frame, resize, shrink
+ * clearing). Steady-stream storms come from any other repeated full redraw.
+ */
+function isExpectedFullRedraw(cause: string): boolean {
+	const c = cause.toLowerCase();
+	return (
+		c.startsWith("first render") ||
+		c.includes("width changed") ||
+		c.includes("height changed") ||
+		c.startsWith("clearonshrink") ||
+		c.includes("forced") ||
+		c.includes("force")
+	);
+}
+
+function retainedLabel<T>(map: Map<string, T>, label: string): string {
+	if (map.has(label) || label === LABEL_OVERFLOW_KEY) return label;
+	return map.size < MAX_LABEL_MAP_ENTRIES - 1 ? label : LABEL_OVERFLOW_KEY;
+}
+
+function incrementCount(map: Map<string, number>, label: string): void {
+	const retained = retainedLabel(map, label);
+	map.set(retained, (map.get(retained) ?? 0) + 1);
+}
+
+export interface DurationStats {
+	count: number;
+	meanMs: number;
+	p50Ms: number;
+	p95Ms: number;
+	p99Ms: number;
+	maxMs: number;
+}
+
+export interface RssStats {
+	samples: number;
+	baselineBytes: number | null;
+	lastBytes: number | null;
+	peakBytes: number;
+	growthBytes: number;
+	/** RSS sampled after the run + a forced GC (informational). */
+	returnBytes: number | null;
+	/** Heap used at baseline and after the run + forced GC (reclaimable signal). */
+	heapBaselineBytes: number | null;
+	heapReturnBytes: number | null;
+	/** (heapReturn - heapBaseline) / heapBaseline; <= tolerance means heap returned. */
+	returnWithinBaselineFraction: number | null;
+}
+
+export interface HelperStat {
+	count: number;
+	totalMs: number;
+	meanMs: number;
+}
+
+export interface RenderMetricsSnapshot {
+	enabled: boolean;
+	renderCount: number;
+	renderDurations: DurationStats;
+	durationsTruncated: boolean;
+	requestSources: Record<string, number>;
+	fullRedrawCount: number;
+	fullRedrawCauses: Record<string, number>;
+	repaintStorms: number;
+	maxConsecutiveFullRedraws: number;
+	rss: RssStats;
+	ownerGauges: Record<string, number>;
+	timerGauges: Record<string, number>;
+	helperStats: Record<string, HelperStat>;
+}
+
+function emptyDurationStats(): DurationStats {
+	return { count: 0, meanMs: 0, p50Ms: 0, p95Ms: 0, p99Ms: 0, maxMs: 0 };
+}
+
+function percentile(sorted: number[], p: number): number {
+	if (sorted.length === 0) return 0;
+	const rank = (p / 100) * (sorted.length - 1);
+	const lo = Math.floor(rank);
+	const hi = Math.ceil(rank);
+	if (lo === hi) return sorted[lo];
+	const frac = rank - lo;
+	return sorted[lo] * (1 - frac) + sorted[hi] * frac;
+}
+
+export class RenderMetrics {
+	#enabled: boolean;
+	#renderCount = 0;
+	#durations: number[] = [];
+	#durationsTruncated = false;
+	#requestSources = new Map<string, number>();
+	#fullRedrawCount = 0;
+	#fullRedrawCauses = new Map<string, number>();
+	#pendingUnexpectedFullRedraw = false;
+	#consecutiveFullRedraws = 0;
+	#maxConsecutiveFullRedraws = 0;
+	#repaintStorms = 0;
+	#rssSamples = 0;
+	#rssBaseline: number | null = null;
+	#rssLast: number | null = null;
+	#rssPeak = 0;
+	#ownerGauges = new Map<string, number>();
+	#timerGauges = new Map<string, number>();
+	#helpers = new Map<string, { count: number; totalMs: number }>();
+	#rssReturn: number | null = null;
+	#heapBaseline: number | null = null;
+	#heapReturn: number | null = null;
+
+	constructor(enabled = $flag("PI_TUI_METRICS")) {
+		this.#enabled = enabled;
+	}
+
+	get enabled(): boolean {
+		return this.#enabled;
+	}
+
+	enable(): void {
+		this.#enabled = true;
+	}
+
+	disable(): void {
+		this.#enabled = false;
+	}
+
+	/** Reset all collected data (keeps the enabled state). */
+	reset(): void {
+		this.#renderCount = 0;
+		this.#durations = [];
+		this.#durationsTruncated = false;
+		this.#requestSources.clear();
+		this.#fullRedrawCount = 0;
+		this.#fullRedrawCauses.clear();
+		this.#pendingUnexpectedFullRedraw = false;
+		this.#consecutiveFullRedraws = 0;
+		this.#maxConsecutiveFullRedraws = 0;
+		this.#repaintStorms = 0;
+		this.#rssSamples = 0;
+		this.#rssBaseline = null;
+		this.#rssLast = null;
+		this.#rssPeak = 0;
+		this.#ownerGauges.clear();
+		this.#timerGauges.clear();
+		this.#helpers.clear();
+		this.#rssReturn = null;
+		this.#heapBaseline = null;
+		this.#heapReturn = null;
+	}
+
+	/** High-resolution clock for timing render passes. Returns 0 when disabled. */
+	now(): number {
+		return this.#enabled ? performance.now() : 0;
+	}
+
+	/** Record that a render was requested, attributed to a caller source. */
+	recordRequest(source = "unknown"): void {
+		if (!this.#enabled) return;
+		incrementCount(this.#requestSources, source);
+	}
+
+	/** Record one completed `#doRender` pass duration (ms). */
+	recordRender(durationMs: number): void {
+		if (!this.#enabled) return;
+		this.#renderCount += 1;
+		if (this.#durations.length < MAX_DURATION_SAMPLES) {
+			this.#durations.push(durationMs);
+		} else {
+			this.#durationsTruncated = true;
+		}
+
+		// Storm bookkeeping: a render that performed an unexpected full redraw
+		// extends the current run; any other render breaks it.
+		if (this.#pendingUnexpectedFullRedraw) {
+			this.#consecutiveFullRedraws += 1;
+			if (this.#consecutiveFullRedraws > this.#maxConsecutiveFullRedraws) {
+				this.#maxConsecutiveFullRedraws = this.#consecutiveFullRedraws;
+			}
+			if (this.#consecutiveFullRedraws === REPAINT_STORM_THRESHOLD) {
+				this.#repaintStorms += 1;
+			}
+		} else {
+			this.#consecutiveFullRedraws = 0;
+		}
+		this.#pendingUnexpectedFullRedraw = false;
+	}
+
+	/** Record a full-redraw event and classify its cause for storm detection. */
+	recordFullRedraw(cause: string): void {
+		if (!this.#enabled) return;
+		this.#fullRedrawCount += 1;
+		const normalizedCause = normalizeFullRedrawCause(cause);
+		incrementCount(this.#fullRedrawCauses, normalizedCause);
+		if (!isExpectedFullRedraw(normalizedCause)) {
+			this.#pendingUnexpectedFullRedraw = true;
+		}
+	}
+
+	/** Sample current RSS. Records baseline on first sample, tracks peak/last. */
+	sampleRss(): number {
+		if (!this.#enabled) return 0;
+		const mem = process.memoryUsage();
+		const rss = mem.rss;
+		this.#rssSamples += 1;
+		if (this.#rssBaseline === null) this.#rssBaseline = rss;
+		if (this.#heapBaseline === null) this.#heapBaseline = mem.heapUsed;
+		this.#rssLast = rss;
+		if (rss > this.#rssPeak) this.#rssPeak = rss;
+		return rss;
+	}
+
+	setOwnerGauge(name: string, value: number): void {
+		if (!this.#enabled) return;
+		this.#ownerGauges.set(name, value);
+	}
+
+	setTimerGauge(name: string, value: number): void {
+		if (!this.#enabled) return;
+		this.#timerGauges.set(name, value);
+	}
+
+	/** Accumulate timing/count for a named render helper (e.g. "renderTree"). */
+	recordHelper(name: string, durationMs: number): void {
+		if (!this.#enabled) return;
+		const retained = retainedLabel(this.#helpers, name);
+		const cur = this.#helpers.get(retained) ?? { count: 0, totalMs: 0 };
+		cur.count += 1;
+		cur.totalMs += durationMs;
+		this.#helpers.set(retained, cur);
+	}
+
+	/**
+	 * Force a GC when the runtime exposes one and sample RSS as the post-run
+	 * "return" value used by the memory-leak gate. Callers should drop large
+	 * references before calling so reclaimable memory is actually freed.
+	 */
+	sampleReturn(): number {
+		if (!this.#enabled) return 0;
+		const bunGc = (globalThis as { Bun?: { gc?: (force: boolean) => void } }).Bun?.gc;
+		const nodeGc = (globalThis as { gc?: () => void }).gc;
+		if (typeof bunGc === "function") bunGc(true);
+		else if (typeof nodeGc === "function") nodeGc();
+		const mem = process.memoryUsage();
+		this.#rssReturn = mem.rss;
+		this.#heapReturn = mem.heapUsed;
+		if (this.#rssBaseline === null) this.#rssBaseline = mem.rss;
+		if (this.#heapBaseline === null) this.#heapBaseline = mem.heapUsed;
+		return mem.rss;
+	}
+
+	#durationStats(): DurationStats {
+		if (this.#durations.length === 0) return emptyDurationStats();
+		const sorted = [...this.#durations].sort((a, b) => a - b);
+		const sum = sorted.reduce((acc, v) => acc + v, 0);
+		return {
+			count: sorted.length,
+			meanMs: sum / sorted.length,
+			p50Ms: percentile(sorted, 50),
+			p95Ms: percentile(sorted, 95),
+			p99Ms: percentile(sorted, 99),
+			maxMs: sorted[sorted.length - 1],
+		};
+	}
+
+	#helperStats(): Record<string, HelperStat> {
+		const out: Record<string, HelperStat> = {};
+		for (const [name, v] of this.#helpers) {
+			out[name] = { count: v.count, totalMs: v.totalMs, meanMs: v.count ? v.totalMs / v.count : 0 };
+		}
+		return out;
+	}
+
+	snapshot(): RenderMetricsSnapshot {
+		return {
+			enabled: this.#enabled,
+			renderCount: this.#renderCount,
+			renderDurations: this.#durationStats(),
+			durationsTruncated: this.#durationsTruncated,
+			requestSources: Object.fromEntries(this.#requestSources),
+			fullRedrawCount: this.#fullRedrawCount,
+			fullRedrawCauses: Object.fromEntries(this.#fullRedrawCauses),
+			repaintStorms: this.#repaintStorms,
+			maxConsecutiveFullRedraws: this.#maxConsecutiveFullRedraws,
+			rss: {
+				samples: this.#rssSamples,
+				baselineBytes: this.#rssBaseline,
+				lastBytes: this.#rssLast,
+				peakBytes: this.#rssPeak,
+				growthBytes: this.#rssBaseline === null ? 0 : this.#rssPeak - this.#rssBaseline,
+				returnBytes: this.#rssReturn,
+				heapBaselineBytes: this.#heapBaseline,
+				heapReturnBytes: this.#heapReturn,
+				returnWithinBaselineFraction:
+					this.#heapBaseline && this.#heapReturn !== null
+						? (this.#heapReturn - this.#heapBaseline) / this.#heapBaseline
+						: null,
+			},
+			ownerGauges: Object.fromEntries(this.#ownerGauges),
+			timerGauges: Object.fromEntries(this.#timerGauges),
+			helperStats: this.#helperStats(),
+		};
+	}
+}
+
+/** Shared metrics instance used by the TUI render loop. */
+export const renderMetrics = new RenderMetrics();

package/src/terminal.ts

@@ -34,6 +34,8 @@ export function emergencyTerminalRestore(): void {
 			// This avoids writing escape sequences for non-TUI commands (grep, commit, etc.)
 			process.stdout.write(
 				"\x1b[?2004l" + // Disable bracketed paste
+					"\x1b[?1000l" + // Disable normal mouse reporting
+					"\x1b[?1006l" + // Disable SGR extended mouse reporting
 					"\x1b[?2031l" + // Disable Mode 2031 appearance notifications
 					"\x1b[<u" + // Pop kitty keyboard protocol
 					"\x1b[>4;0m" + // Disable modifyOtherKeys fallback
@@ -572,6 +574,8 @@ export class ProcessTerminal implements Terminal {
 
 		// Disable bracketed paste mode
 		this.#safeWrite("\x1b[?2004l");
+		this.#safeWrite("\x1b[?1000l");
+		this.#safeWrite("\x1b[?1006l");
 
 		// Disable Mode 2031 appearance change notifications
 		this.#safeWrite("\x1b[?2031l");

package/src/tui.ts

@@ -6,6 +6,7 @@ import * as path from "node:path";
 import { performance } from "node:perf_hooks";
 import { $flag, getDebugLogPath } from "@gajae-code/utils";
 import { isKeyRelease, matchesKey } from "./keys";
+import { renderMetrics } from "./metrics";
 import type { Terminal } from "./terminal";
 import { ImageProtocol, setCellDimensions, setTerminalImageProtocol, TERMINAL } from "./terminal-capabilities";
 import {
@@ -433,6 +434,7 @@ export class TUI extends Container {
 		if (this.#renderTimer) {
 			clearTimeout(this.#renderTimer);
 			this.#renderTimer = undefined;
+			if (renderMetrics.enabled) renderMetrics.setTimerGauge("tui.renderTimer", 0);
 		}
 		this.#clearSixelProbeState();
 	}
@@ -619,6 +621,7 @@ export class TUI extends Container {
 		if (this.#renderTimer) {
 			clearTimeout(this.#renderTimer);
 			this.#renderTimer = undefined;
+			if (renderMetrics.enabled) renderMetrics.setTimerGauge("tui.renderTimer", 0);
 		}
 		// Move cursor to the end of the content to prevent overwriting/artifacts on exit
 		if (this.#previousLines.length > 0) {
@@ -640,11 +643,12 @@ export class TUI extends Container {
 		}
 	}
 
-	requestRender(force = false): void {
+	requestRender(force = false, source = "unknown"): void {
 		if (!this.terminalAvailable) {
 			this.#markTerminalUnavailable();
 			return;
 		}
+		if (renderMetrics.enabled) renderMetrics.recordRequest(source);
 		if (force) {
 			this.#previousLines = [];
 			this.#previousWidth = -1; // -1 triggers widthChanged, forcing a full clear
@@ -656,6 +660,7 @@ export class TUI extends Container {
 			if (this.#renderTimer) {
 				clearTimeout(this.#renderTimer);
 				this.#renderTimer = undefined;
+				if (renderMetrics.enabled) renderMetrics.setTimerGauge("tui.renderTimer", 0);
 			}
 			this.#renderRequested = true;
 			process.nextTick(() => {
@@ -664,7 +669,9 @@ export class TUI extends Container {
 				}
 				this.#renderRequested = false;
 				this.#lastRenderAt = performance.now();
+				const t0 = renderMetrics.now();
 				this.#doRender();
+				if (renderMetrics.enabled) renderMetrics.recordRender(renderMetrics.now() - t0);
 			});
 			return;
 		}
@@ -681,16 +688,20 @@ export class TUI extends Container {
 		const delay = Math.max(0, TUI.#MIN_RENDER_INTERVAL_MS - elapsed);
 		this.#renderTimer = setTimeout(() => {
 			this.#renderTimer = undefined;
+			if (renderMetrics.enabled) renderMetrics.setTimerGauge("tui.renderTimer", 0);
 			if (this.#stopped || !this.#renderRequested) {
 				return;
 			}
 			this.#renderRequested = false;
 			this.#lastRenderAt = performance.now();
+			const t0 = renderMetrics.now();
 			this.#doRender();
+			if (renderMetrics.enabled) renderMetrics.recordRender(renderMetrics.now() - t0);
 			if (this.#renderRequested) {
 				this.#scheduleRender();
 			}
 		}, delay);
+		if (renderMetrics.enabled) renderMetrics.setTimerGauge("tui.renderTimer", 1);
 	}
 
 	#handleInput(data: string): void {
@@ -1108,7 +1119,9 @@ export class TUI extends Container {
 		};
 
 		// Render all components to get new lines
+		const renderTreeStart = renderMetrics.now();
 		let newLines = this.render(width);
+		if (renderMetrics.enabled) renderMetrics.recordHelper("renderTree", renderMetrics.now() - renderTreeStart);
 
 		// Composite overlays into the rendered lines (before differential compare)
 		if (this.overlayStack.length > 0) {
@@ -1130,8 +1143,9 @@ export class TUI extends Container {
 		const heightChanged = this.#previousHeight !== 0 && this.#previousHeight !== height;
 
 		// Helper to clear scrollback and viewport and render all new lines
-		const fullRender = (clear: boolean): void => {
+		const fullRender = (clear: boolean, reason = "full render"): void => {
 			this.#fullRedrawCount += 1;
+			if (renderMetrics.enabled) renderMetrics.recordFullRedraw(reason);
 			let buffer = "\x1b[?2026h"; // Begin synchronized output
 			// Skip clearing scrollback (3J) in multiplexers — users actively navigate scrollback history
 			if (clear) buffer += isMultiplexerSession() ? "\x1b[2J\x1b[H" : "\x1b[2J\x1b[H\x1b[3J";
@@ -1161,6 +1175,7 @@ export class TUI extends Container {
 
 		const multiplexerViewportRepaint = (reason: string): void => {
 			this.#fullRedrawCount += 1;
+			if (renderMetrics.enabled) renderMetrics.recordFullRedraw(reason);
 			const nextViewportTop = Math.max(0, newLines.length - height);
 			const currentScreenRow = Math.max(0, Math.min(height - 1, hardwareCursorRow - prevViewportTop));
 			let buffer = "\x1b[?2026h";
@@ -1225,14 +1240,14 @@ export class TUI extends Container {
 		// First render - just output everything without clearing (assumes clean screen)
 		if (this.#previousLines.length === 0 && !widthChanged && !heightChanged) {
 			logRedraw("first render");
-			fullRender(false);
+			fullRender(false, "first render");
 			return;
 		}
 
 		// Width changes always need a full re-render because wrapping changes.
 		if (widthChanged) {
 			logRedraw(`terminal width changed (${this.#previousWidth} -> ${width})`);
-			fullRender(true);
+			fullRender(true, "terminal width changed");
 			return;
 		}
 
@@ -1246,7 +1261,7 @@ export class TUI extends Container {
 			}
 			if (!isTermuxSession() && !isMultiplexerSession()) {
 				logRedraw(`terminal height changed (${this.#previousHeight} -> ${height})`);
-				fullRender(true);
+				fullRender(true, "terminal height changed");
 				return;
 			}
 		}
@@ -1256,7 +1271,7 @@ export class TUI extends Container {
 		// Configurable via setClearOnShrink() or PI_CLEAR_ON_SHRINK=0 env var
 		if (this.#clearOnShrink && newLines.length < this.#previousLines.length && this.overlayStack.length === 0) {
 			logRedraw(`clearOnShrink (prev=${this.#previousLines.length}, new=${newLines.length})`);
-			fullRender(true);
+			fullRender(true, "clearOnShrink");
 			return;
 		}
 
@@ -1308,7 +1323,7 @@ export class TUI extends Container {
 					if (isMultiplexerSession() && !useLegacyMultiplexerFullRender()) {
 						multiplexerViewportRepaint(`extraLines > height (${extraLines} > ${height})`);
 					} else {
-						fullRender(true);
+						fullRender(true, "extraLines > height");
 					}
 					return;
 				}
@@ -1347,7 +1362,7 @@ export class TUI extends Container {
 			if (isMultiplexerSession() && !useLegacyMultiplexerFullRender()) {
 				multiplexerViewportRepaint(`firstChanged < viewportTop (${firstChanged} < ${prevViewportTop})`);
 			} else {
-				fullRender(true);
+				fullRender(true, "firstChanged < viewportTop");
 			}
 			return;
 		}

package/src/utils.ts

@@ -8,11 +8,22 @@ import {
 	type SliceResult,
 } from "@gajae-code/natives";
 import { getDefaultTabWidth, getIndentation } from "@gajae-code/utils";
+import { renderMetrics } from "./metrics";
 
 export { Ellipsis } from "@gajae-code/natives";
 
 export { getDefaultTabWidth, getIndentation } from "@gajae-code/utils";
 
+function recordTextHelper<T>(name: string, fn: () => T): T {
+	if (!renderMetrics.enabled) return fn();
+	const start = renderMetrics.now();
+	try {
+		return fn();
+	} finally {
+		renderMetrics.recordHelper(name, renderMetrics.now() - start);
+	}
+}
+
 export function sliceWithWidth(line: string, startCol: number, length: number, strict?: boolean | null): SliceResult {
 	return nativeSliceWithWidth(line, startCol, length, strict ?? null, getDefaultTabWidth());
 }
@@ -98,31 +109,37 @@ export function visibleWidthRaw(str: string): number {
 	if (!str) {
 		return 0;
 	}
+	if (str.length === 1) {
+		const code = str.charCodeAt(0);
+		if (code >= 0x20 && code <= 0x7e) return 1;
+		if (code === 9) return getDefaultTabWidth();
+	}
 
-	// Fast path: pure ASCII printable
-	let tabLength = 0;
-	const tabWidth = getDefaultTabWidth();
+	let tabCount = 0;
 	let isPureAscii = true;
 	for (let i = 0; i < str.length; i++) {
 		const code = str.charCodeAt(i);
 		if (code === 9) {
-			tabLength += tabWidth;
+			tabCount += 1;
 		} else if (code < 0x20 || code > 0x7e) {
 			isPureAscii = false;
 		}
 	}
 	if (isPureAscii) {
-		return str.length + tabLength;
+		return str.length + tabCount * (getDefaultTabWidth() - 1);
 	}
-	return Bun.stringWidth(normalizeForWidth(str)) + tabLength;
+
+	const normalized = normalizeForWidth(str);
+	if (tabCount === 0) return Bun.stringWidth(normalized);
+	return Bun.stringWidth(normalized.replaceAll("\t", " ".repeat(getDefaultTabWidth())));
 }
 
 /**
  * Calculate the visible width of a string in terminal columns.
  */
 export function visibleWidth(str: string): number {
-	if (!str) return 0;
-	return visibleWidthRaw(str);
+	if (!renderMetrics.enabled) return visibleWidthRaw(str);
+	return recordTextHelper("text.visibleWidth", () => visibleWidthRaw(str));
 }
 
 const THAI_LAO_AM_REGEX = /[\u0e33\u0eb3]/;