pi-libtui 0.3.2

package/src/decoration/status.ts

@@ -0,0 +1,185 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { type TuiForegroundToken, type TuiTheme, tuiTheme } from "../color/theme.ts";
+import { sanitizeTuiText } from "../content/terminal-text.ts";
+import {
+	activityFrame,
+	animationSpeedMultiplier,
+	mountConfiguredAnimation,
+	type MotionMount,
+	type MotionScheduler,
+} from "../motion.ts";
+import type { TuiAnimationSpeed } from "../appearance.ts";
+import { RenderedLinesCache } from "../render-cache.ts";
+import { icon, type TuiIconName } from "./glyphs.ts";
+
+/** Options for the pure determinate or indeterminate progress renderer. */
+export interface ProgressFrameOptions {
+	width: number;
+	/** A finite value from zero to one. Omit for an indeterminate moving segment. */
+	value?: number;
+	elapsedMs?: number;
+	animationSpeed?: TuiAnimationSpeed;
+	reducedMotion?: boolean;
+	filled?: string;
+	empty?: string;
+	tone?: TuiForegroundToken;
+	trackTone?: TuiForegroundToken;
+}
+
+/** Render a fixed-width progress frame using semantic foreground colors. */
+export function progressFrame(colors: TuiTheme, options: ProgressFrameOptions): string {
+	const width = Math.max(0, Math.floor(options.width));
+	if (width === 0) return "";
+	const filled = cellGlyph(options.filled, "━");
+	const empty = cellGlyph(options.empty, "─");
+	const tone = options.tone ?? "accent";
+	const trackTone = options.trackTone ?? "text.muted";
+	if (options.value !== undefined && Number.isFinite(options.value)) {
+		const count = Math.round(Math.max(0, Math.min(1, options.value)) * width);
+		return `${colors.fg(tone, filled.repeat(count))}${colors.fg(trackTone, empty.repeat(width - count))}`;
+	}
+	if (options.reducedMotion) return colors.fg(trackTone, empty.repeat(width));
+	const segmentWidth = Math.max(1, Math.min(width, Math.ceil(width / 4)));
+	const travel = width + segmentWidth;
+	const elapsedMs = Math.max(0, options.elapsedMs ?? 0) * animationSpeedMultiplier(options.animationSpeed);
+	const offset = Math.floor(elapsedMs / 70) % travel;
+	const start = Math.max(0, offset - segmentWidth);
+	const end = Math.min(width, offset);
+	return `${colors.fg(trackTone, empty.repeat(start))}${colors.fg(tone, filled.repeat(Math.max(0, end - start)))}${colors.fg(trackTone, empty.repeat(width - end))}`;
+}
+
+/** Construction options for a stream-friendly activity row. */
+export interface ActivityIndicatorOptions {
+	theme: Theme;
+	label: string;
+	detail?: string;
+	requestRender(): void;
+	reducedMotion?: boolean;
+	spinnerFrames?: readonly string[];
+	scheduler?: MotionScheduler;
+	/** Optional repaint deadline for callers that cannot own component disposal. */
+	maxDurationMs?: number;
+	/** Initial-time seam for deterministic component tests. */
+	now?: () => number;
+}
+
+/** A compact animated activity row backed by the shared cadence scheduler. */
+export class ActivityIndicator implements Component {
+	private readonly cache = new RenderedLinesCache();
+	private readonly startedAtMs: number;
+	private nowMs: number;
+	private readonly mount: MotionMount;
+
+	constructor(private readonly options: ActivityIndicatorOptions) {
+		this.startedAtMs = options.now?.() ?? performance.now();
+		this.nowMs = this.startedAtMs;
+		this.mount = mountConfiguredAnimation(options, {
+			reducedMotion: options.reducedMotion,
+			maxDurationMs: options.maxDurationMs,
+			scheduler: options.scheduler,
+			onFrame: (nowMs) => {
+				this.nowMs = nowMs;
+			},
+		});
+	}
+
+	render(width: number): string[] {
+		const elapsedMs = Math.max(0, this.nowMs - this.startedAtMs);
+		const frame = activityFrame(tuiTheme(this.options.theme), rowText(this.options.label), elapsedMs, {
+			frames: this.options.spinnerFrames,
+			reducedMotion: this.options.reducedMotion,
+		});
+		const marker = frame.marker ? `${frame.marker} ` : "";
+		const detailText = this.options.detail === undefined ? undefined : rowText(this.options.detail);
+		const key = `${frame.marker}\0${frame.text}\0${detailText ?? ""}`;
+		return this.cache.get(width, key, () => {
+			if (width <= 0) return [];
+			const colors = tuiTheme(this.options.theme);
+			const separator = detailText ? colors.fg("text.muted", " · ") : "";
+			const detail = detailText ? colors.fg("text.secondary", detailText) : "";
+			const line = `${marker}${frame.text}${separator}${detail}`;
+			return [truncateToWidth(line, width, "…")];
+		});
+	}
+
+	invalidate(): void {
+		this.cache.clear();
+	}
+
+	/** Release the scheduler registration. Safe to call more than once. */
+	dispose(): void {
+		this.mount.dispose();
+	}
+}
+
+/** Construction options for a cached progress-bar component. */
+export interface ProgressBarOptions extends Omit<ProgressFrameOptions, "width"> {
+	theme: Theme;
+	label?: string;
+	showPercentage?: boolean;
+}
+
+/** A static, allocation-bounded determinate progress bar. */
+export class ProgressBar implements Component {
+	private readonly cache = new RenderedLinesCache();
+
+	constructor(private readonly options: ProgressBarOptions) {}
+
+	render(width: number): string[] {
+		const value = this.options.value;
+		const percentage = value === undefined ? "" : `${Math.round(Math.max(0, Math.min(1, value)) * 100)}%`;
+		const key = `${value ?? "indeterminate"}\0${this.options.elapsedMs ?? 0}\0${this.options.reducedMotion ?? false}`;
+		return this.cache.get(width, key, () => {
+			if (width <= 0) return [];
+			const colors = tuiTheme(this.options.theme);
+			const labelText = this.options.label === undefined ? "" : rowText(this.options.label);
+			const label = labelText ? colors.fg("text.secondary", labelText) : "";
+			const suffix = this.options.showPercentage && percentage ? colors.fg("text.muted", percentage) : "";
+			const fixed = visibleWidth(label) + visibleWidth(suffix) + (label ? 1 : 0) + (suffix ? 1 : 0);
+			const barWidth = Math.max(1, width - fixed);
+			const bar = progressFrame(colors, { ...this.options, width: barWidth });
+			return [truncateToWidth(`${label}${label ? " " : ""}${bar}${suffix ? ` ${suffix}` : ""}`, width, "")];
+		});
+	}
+
+	invalidate(): void {
+		this.cache.clear();
+	}
+}
+
+function cellGlyph(value: string | undefined, fallback: string): string {
+	if (value === undefined) return fallback;
+	const safe = sanitizeTuiText(value);
+	return safe === value && safe.trim().length > 0 && visibleWidth(safe) === 1 ? safe : fallback;
+}
+
+function rowText(value: string): string {
+	return sanitizeTuiText(value).replace(/[\n\r]+/gu, " ");
+}
+
+/** A title label with an optional icon resolved from the active semantic icon pack. */
+export interface TuiTitle {
+	/** Human-readable title text. */
+	label: string;
+	/** Semantic icon token rendered before the label. */
+	icon?: TuiIconName;
+}
+
+/** A plain title string or a structured semantic title. */
+export type TuiTitleValue = string | TuiTitle;
+
+/** A title value or callback resolved on every render for dynamic labels. */
+export type TuiTitleSource = TuiTitleValue | (() => TuiTitleValue);
+
+/**
+ * Resolve a static or dynamic semantic title into display text.
+ * @param source Title value or callback evaluated at call time.
+ * @returns The label, prefixed by the active icon-pack glyph when an icon exists.
+ */
+export function resolveTuiTitle(source: TuiTitleSource): string {
+	const title = typeof source === "function" ? source() : source;
+	if (typeof title === "string") return title;
+	return title.icon ? `${icon(title.icon)} ${title.label}` : title.label;
+}

package/src/decoration/transient-pill.ts

@@ -0,0 +1,176 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { compositeTuiLine, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { type TuiForegroundToken, tuiTheme } from "../color/theme.ts";
+import type { ViewportRect } from "../mouse.ts";
+import type { SelectionPoint } from "../selection.ts";
+import { getTuiPillSeparators, icon, type TuiIconName } from "./glyphs.ts";
+import { backgroundAnsiAtColumn, renderPill } from "./powerline-pill.ts";
+
+/** Content displayed by a short-lived cursor-local pill. */
+export interface TransientPillMessage {
+	/** Short status text. */
+	label: string;
+	/** Semantic icon displayed before the label. */
+	icon: TuiIconName;
+	/** Semantic foreground applied to the icon. */
+	tone: TuiForegroundToken;
+}
+
+/** Bounds used to place a transient pill around a terminal cell. */
+export interface TransientPillPlacementRequest {
+	/** Absolute cell around which the pill is centered. */
+	anchor: SelectionPoint;
+	/** Natural pill width before visible-bounds clamping. */
+	width: number;
+	/** Complete terminal width. */
+	screenWidth: number;
+	/** Complete terminal height. */
+	screenHeight: number;
+	/** Optional transcript viewport used as tighter visible bounds. */
+	viewport?: ViewportRect;
+}
+
+/** Construction options for {@link TransientPill}. */
+export interface TransientPillOptions {
+	/** Active Pi theme used for semantic colors. */
+	theme: Theme;
+	/** Request a host render after feedback appears or expires. */
+	requestRender(): void;
+	/** Visibility duration in milliseconds; defaults to 1500. */
+	durationMs?: number;
+}
+
+function clamp(value: number, minimum: number, maximum: number): number {
+	return Math.max(minimum, Math.min(value, maximum));
+}
+
+/**
+ * Center a one-row pill above its anchor, flipping below and clamping to visible bounds.
+ * @param request Anchor, terminal bounds, and natural pill width.
+ * @returns A visible one-row rectangle, or undefined when no adjacent row exists.
+ */
+export function placeTransientPill(request: TransientPillPlacementRequest):
+	| {
+			x: number;
+			y: number;
+			width: number;
+			height: 1;
+	  }
+	| undefined {
+	const left = request.viewport?.x ?? 0;
+	const top = request.viewport?.y ?? 0;
+	const right = request.viewport
+		? Math.min(request.screenWidth, request.viewport.x + request.viewport.width)
+		: request.screenWidth;
+	const bottom = request.viewport
+		? Math.min(request.screenHeight, request.viewport.y + request.viewport.height)
+		: request.screenHeight;
+	const width = Math.min(Math.max(0, Math.floor(request.width)), Math.max(0, right - left));
+	if (width === 0 || bottom <= top) return undefined;
+	const anchorRow = clamp(Math.floor(request.anchor.row), top, bottom - 1);
+	const y = anchorRow - 1 >= top ? anchorRow - 1 : anchorRow + 1 < bottom ? anchorRow + 1 : undefined;
+	if (y === undefined) return undefined;
+	const center = Math.floor(request.anchor.col) + 0.5;
+	const x = clamp(Math.round(center - width / 2), left, right - width);
+	return { x, y, width, height: 1 };
+}
+
+/** A reusable, timed pill composited near a terminal cursor or selection anchor. */
+export class TransientPill {
+	private current: { message: TransientPillMessage; anchor: SelectionPoint } | undefined;
+	private timer: ReturnType<typeof setTimeout> | undefined;
+
+	/** @param options Theme, render callback, and optional display duration. */
+	constructor(private readonly options: TransientPillOptions) {}
+
+	/**
+	 * Display feedback and restart its expiry timer.
+	 * @param message Semantic icon, tone, and short label.
+	 * @param anchor Absolute cursor or selection cell around which to place the pill.
+	 */
+	show(message: TransientPillMessage, anchor: SelectionPoint): void {
+		this.current = { message, anchor };
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = setTimeout(() => {
+			this.current = undefined;
+			this.timer = undefined;
+			this.options.requestRender();
+		}, this.options.durationMs ?? 1_500);
+		this.options.requestRender();
+	}
+
+	/** Hide current feedback and request a render. */
+	clear(): void {
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = undefined;
+		if (!this.current) return;
+		this.current = undefined;
+		this.options.requestRender();
+	}
+
+	/** Cancel expiry and release the current message without requesting another render. */
+	dispose(): void {
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = undefined;
+		this.current = undefined;
+	}
+
+	/**
+	 * Composite current feedback over a styled terminal screen.
+	 * @param screen Complete styled terminal rows.
+	 * @param bounds Terminal dimensions and optional transcript viewport.
+	 * @returns A decorated screen copy, or an unchanged copy when no pill is visible.
+	 */
+	composite(screen: readonly string[], bounds: { width: number; height: number; viewport?: ViewportRect }): string[] {
+		if (!this.current) return [...screen];
+		const [leftCap, rightCap] = getTuiPillSeparators();
+		const naturalWidth =
+			visibleWidth(leftCap) +
+			visibleWidth(icon(this.current.message.icon)) +
+			1 +
+			visibleWidth(this.current.message.label) +
+			visibleWidth(rightCap);
+		const placement = placeTransientPill({
+			anchor: this.current.anchor,
+			width: naturalWidth,
+			screenWidth: bounds.width,
+			screenHeight: bounds.height,
+			viewport: bounds.viewport,
+		});
+		if (!placement) return [...screen];
+		const result = [...screen];
+		const base = result[placement.y];
+		if (base === undefined) return result;
+		const destination = backgroundAnsiAtColumn(base, placement.x);
+		const colors = tuiTheme(this.options.theme);
+		const iconGlyph = icon(this.current.message.icon);
+		const labelWidth = Math.max(
+			0,
+			placement.width - visibleWidth(leftCap) - visibleWidth(iconGlyph) - 1 - visibleWidth(rightCap),
+		);
+		const label = truncateToWidth(this.current.message.label, labelWidth, "…");
+		const blue = colors.color({ hue: "blue", shade: 2 });
+		const background =
+			this.current.message.tone === "warning"
+				? "badge.warning"
+				: this.current.message.tone === "negative"
+					? "badge.negative"
+					: blue;
+		const pill = renderPill(
+			this.options.theme,
+			{ icon: this.current.message.icon, iconTone: this.current.message.tone, label },
+			background,
+			"text.primary",
+			undefined,
+			destination,
+		);
+		result[placement.y] = compositeTuiLine(
+			base,
+			pill,
+			placement.x,
+			placement.width,
+			Math.max(visibleWidth(base), placement.x + placement.width),
+		);
+		return result;
+	}
+}

package/src/diff/index.ts

@@ -0,0 +1,21 @@
+export type {
+	CreateUnifiedDiffModelOptions,
+	ParseUnifiedDiffOptions,
+	UnifiedDiffFile,
+	UnifiedDiffFileInput,
+	UnifiedDiffHunk,
+	UnifiedDiffHunkInput,
+	UnifiedDiffLine,
+	UnifiedDiffLineKind,
+	UnifiedDiffModel,
+	UnifiedDiffRowInput,
+} from "./model.ts";
+export { createUnifiedDiffModel, parseUnifiedDiff } from "./parse.ts";
+export type {
+	RenderUnifiedDiffOptions,
+	UnifiedDiffRenderResult,
+	UnifiedDiffViewport,
+} from "./render.ts";
+export { renderUnifiedDiff } from "./render.ts";
+export type { UnifiedDiffViewOptions } from "./view.ts";
+export { UnifiedDiffView } from "./view.ts";

package/src/diff/model.ts

@@ -0,0 +1,76 @@
+export type UnifiedDiffLineKind = "context" | "added" | "removed" | "metadata" | "malformed";
+
+export interface UnifiedDiffLine {
+	/** Stable within a parsed model and suitable for renderer/highlighter caches. */
+	readonly ref: string;
+	readonly kind: UnifiedDiffLineKind;
+	readonly text: string;
+	readonly oldLine?: number;
+	readonly newLine?: number;
+}
+
+export interface UnifiedDiffHunk {
+	readonly ref: string;
+	readonly header: string;
+	readonly oldStart?: number;
+	readonly oldCount?: number;
+	readonly newStart?: number;
+	readonly newCount?: number;
+	readonly lines: readonly UnifiedDiffLine[];
+}
+
+export interface UnifiedDiffFile {
+	readonly ref: string;
+	readonly oldPath?: string;
+	readonly newPath?: string;
+	readonly headerLines: readonly string[];
+	readonly hunks: readonly UnifiedDiffHunk[];
+	readonly additions: number;
+	readonly removals: number;
+}
+
+export interface UnifiedDiffModel {
+	readonly revision: string;
+	readonly files: readonly UnifiedDiffFile[];
+	readonly preamble: readonly string[];
+	readonly additions: number;
+	readonly removals: number;
+	readonly sourceRows: number;
+	readonly truncated: boolean;
+}
+
+export interface ParseUnifiedDiffOptions {
+	/** Hard input limit. Parsing stops before allocating rows beyond this boundary. */
+	readonly maxCharacters?: number;
+	/** Hard logical-row limit, including file headers. */
+	readonly maxRows?: number;
+}
+
+export interface UnifiedDiffRowInput {
+	readonly kind: UnifiedDiffLineKind;
+	readonly text: string;
+	readonly oldLine?: number;
+	readonly newLine?: number;
+}
+
+export interface UnifiedDiffHunkInput {
+	readonly header?: string;
+	readonly oldStart?: number;
+	readonly oldCount?: number;
+	readonly newStart?: number;
+	readonly newCount?: number;
+	readonly rows: readonly UnifiedDiffRowInput[];
+}
+
+export interface UnifiedDiffFileInput {
+	readonly oldPath?: string;
+	readonly newPath?: string;
+	readonly headerLines?: readonly string[];
+	readonly hunks: readonly UnifiedDiffHunkInput[];
+}
+
+export interface CreateUnifiedDiffModelOptions extends ParseUnifiedDiffOptions {
+	readonly revision?: string;
+	/** Caller-owned truncation performed before the structured model was built. */
+	readonly truncated?: boolean;
+}