@luan.sh/pi-libtui 0.3.8

package/src/component-stack.ts

@@ -0,0 +1,247 @@
+import { type Component, type Focusable, isFocusable } from "@earendil-works/pi-tui";
+import type { TuiMouseEvent } from "./mouse.ts";
+
+/** Input-routing policy for a {@link ComponentStack}. */
+export type ComponentStackInputMode = "active" | "all";
+
+/** Construction options for a vertical component stack. */
+export interface ComponentStackOptions {
+	/** Send input to one selected child, or to every child in display order. */
+	inputMode?: ComponentStackInputMode;
+	/** Zero-based initial active child; invalid values select the first child. */
+	activeChild?: number;
+	/** Fill or clip the rendered stack to this many rows. */
+	height?: number | (() => number);
+	/** Clip after this many rows without padding shorter content. */
+	maxHeight?: number | (() => number);
+	/** Place the final child at the bottom when the configured height has spare rows. */
+	anchorLastChild?: boolean;
+}
+
+/** Geometry recorded for one visible child after the latest render. */
+export interface ComponentStackSpan {
+	/** Child component occupying this span. */
+	readonly component: Component;
+	/** Zero-based position of the child in the stack. */
+	readonly index: number;
+	/** Zero-based first row of the child within the stack. */
+	readonly row: number;
+	/** Number of visible rows retained after clipping. */
+	readonly height: number;
+	/** Width in columns supplied to the child during rendering. */
+	readonly width: number;
+}
+
+type MouseComponent = Component & { onMouse?(event: TuiMouseEvent): boolean };
+
+/**
+ * A vertical, semantic component host. Consumers compose and focus children;
+ * pointer discovery and coordinate translation remain structural details.
+ */
+export class ComponentStack implements Component, Focusable {
+	private stackChildren: Component[];
+	private activeChild: number | undefined;
+	private spans: ComponentStackSpan[] = [];
+	private renderedHeight = 0;
+	private renderedWidth = 0;
+	private hoveredSpan: ComponentStackSpan | undefined;
+	private capturedSpan: ComponentStackSpan | undefined;
+	private _focused = false;
+
+	constructor(
+		children: readonly Component[] = [],
+		private readonly options: ComponentStackOptions = {},
+	) {
+		this.stackChildren = [...children];
+		this.activeChild = options.activeChild ?? (children.length > 0 ? 0 : undefined);
+		this.clampActiveChild();
+	}
+
+	get focused(): boolean {
+		return this._focused;
+	}
+
+	set focused(value: boolean) {
+		this._focused = value;
+		const active = this.getActiveChild();
+		if (active && isFocusable(active)) active.focused = value;
+	}
+
+	setChildren(children: readonly Component[]): void {
+		if (
+			children.length === this.stackChildren.length &&
+			children.every((child, index) => child === this.stackChildren[index])
+		)
+			return;
+		const active = this.activeChild === undefined ? undefined : this.stackChildren[this.activeChild];
+		this.stackChildren = [...children];
+		this.activeChild = active ? this.stackChildren.indexOf(active) : this.activeChild;
+		this.clampActiveChild();
+		if (this._focused) {
+			if (active && active !== this.getActiveChild() && isFocusable(active)) active.focused = false;
+			const next = this.getActiveChild();
+			if (next && isFocusable(next)) next.focused = true;
+		}
+		this.spans = [];
+		this.hoveredSpan = undefined;
+		this.capturedSpan = undefined;
+	}
+
+	setActiveChild(child: number | Component | undefined): void {
+		const previous = this.getActiveChild();
+		this.activeChild = typeof child === "number" || child === undefined ? child : this.stackChildren.indexOf(child);
+		this.clampActiveChild();
+		if (this._focused) {
+			if (previous && previous !== this.getActiveChild() && isFocusable(previous)) previous.focused = false;
+			const next = this.getActiveChild();
+			if (next && isFocusable(next)) next.focused = true;
+		}
+	}
+
+	getActiveChild(): Component | undefined {
+		return this.activeChild === undefined ? undefined : this.stackChildren[this.activeChild];
+	}
+
+	getChildren(): readonly Component[] {
+		return [...this.stackChildren];
+	}
+
+	getSpans(): readonly ComponentStackSpan[] {
+		return this.spans.map((span) => ({ ...span }));
+	}
+
+	handleInput(data: string): void {
+		if ((this.options.inputMode ?? "active") === "all") {
+			for (const child of this.stackChildren) child.handleInput?.(data);
+			return;
+		}
+		this.getActiveChild()?.handleInput?.(data);
+	}
+
+	/** Route viewport input to the active child, preserving boolean handling. */
+	handleViewportInput(data: string): boolean {
+		const active = this.getActiveChild() as (Component & { handleViewportInput?(data: string): boolean }) | undefined;
+		return active?.handleViewportInput?.(data) ?? Boolean(active?.handleInput?.(data));
+	}
+
+	invalidate(): void {
+		this.spans = [];
+		this.hoveredSpan = undefined;
+		this.capturedSpan = undefined;
+		for (const child of this.stackChildren) child.invalidate();
+	}
+
+	render(width: number): string[] {
+		this.renderedWidth = Math.max(0, Math.floor(width));
+		const configuredHeight = typeof this.options.height === "function" ? this.options.height() : this.options.height;
+		const configuredMaxHeight =
+			typeof this.options.maxHeight === "function" ? this.options.maxHeight() : this.options.maxHeight;
+		const fixedHeight = configuredHeight !== undefined;
+		const requestedHeight = configuredHeight ?? configuredMaxHeight;
+		const boundedHeight = requestedHeight === undefined ? undefined : Math.max(0, Math.floor(requestedHeight));
+		const rendered: Array<string[] | undefined> = new Array(this.stackChildren.length);
+		if (boundedHeight === undefined) {
+			for (const [index, child] of this.stackChildren.entries()) rendered[index] = child.render(this.renderedWidth);
+		}
+		const footerIndex = this.options.anchorLastChild && rendered.length > 1 ? rendered.length - 1 : undefined;
+		if (boundedHeight !== undefined && boundedHeight > 0 && footerIndex !== undefined)
+			rendered[footerIndex] = this.stackChildren[footerIndex]!.render(this.renderedWidth);
+		const naturalHeight = rendered.reduce((height, lines) => height + (lines?.length ?? 0), 0);
+		const height = boundedHeight ?? naturalHeight;
+		const anchoredFooter = footerIndex === undefined ? undefined : rendered[footerIndex];
+		const footerRow = anchoredFooter ? Math.max(0, height - Math.min(height, anchoredFooter.length)) : height;
+		const lines: string[] = [];
+		const spans: ComponentStackSpan[] = [];
+
+		for (const [index, child] of this.stackChildren.entries()) {
+			const isFooter = anchoredFooter !== undefined && index === footerIndex;
+			if (isFooter && lines.length < footerRow)
+				lines.push(...Array.from({ length: footerRow - lines.length }, () => ""));
+			const row = lines.length;
+			const available = Math.max(0, (isFooter ? height : footerRow) - row);
+			if (available === 0 && !isFooter) {
+				if (footerIndex !== undefined) continue;
+				break;
+			}
+			const childLines = rendered[index] ?? child.render(this.renderedWidth);
+			const visibleLines = childLines.slice(0, available);
+			lines.push(...visibleLines);
+			if (visibleLines.length > 0) {
+				spans.push({
+					component: this.stackChildren[index]!,
+					index,
+					row,
+					height: visibleLines.length,
+					width: this.renderedWidth,
+				});
+			}
+			if (lines.length >= height) break;
+		}
+		if (fixedHeight) while (lines.length < height) lines.push("");
+
+		const remap = (previous: ComponentStackSpan | undefined): ComponentStackSpan | undefined =>
+			previous
+				? spans.find((span) => span.component === previous.component && span.index === previous.index)
+				: undefined;
+		this.hoveredSpan = remap(this.hoveredSpan);
+		this.capturedSpan = remap(this.capturedSpan);
+		this.spans = spans;
+		this.renderedHeight = lines.length;
+		return lines;
+	}
+
+	/** Dispatch a normalized pointer event to the child span under its coordinates. */
+	onMouse(event: TuiMouseEvent): boolean {
+		if (event.type === "leave") {
+			const handled = this.hoveredSpan ? this.dispatch(this.hoveredSpan, event) : false;
+			this.hoveredSpan = undefined;
+			return handled;
+		}
+
+		if ((event.type === "drag" || event.type === "release") && this.capturedSpan) {
+			const captured = this.capturedSpan;
+			const handled = this.dispatch(captured, event);
+			if (event.type === "release") this.capturedSpan = undefined;
+			return handled;
+		}
+
+		const inside =
+			event.col >= 0 && event.col < this.renderedWidth && event.row >= 0 && event.row < this.renderedHeight;
+		const span = inside
+			? this.spans.find((candidate) => event.row >= candidate.row && event.row < candidate.row + candidate.height)
+			: undefined;
+		const hoverHandled = this.updateHover(span, event);
+		if (!span) return hoverHandled;
+		const handled = this.dispatch(span, event);
+		if (event.type === "press" && handled) this.capturedSpan = span;
+		return hoverHandled || handled;
+	}
+
+	private updateHover(span: ComponentStackSpan | undefined, event: TuiMouseEvent): boolean {
+		if (this.hoveredSpan?.component === span?.component && this.hoveredSpan?.index === span?.index) return false;
+		if (this.hoveredSpan) this.dispatch(this.hoveredSpan, { ...event, type: "leave" });
+		this.hoveredSpan = span;
+		// A press must reach the child before any enter-triggered redraw clears
+		// nested stack geometry. All-motion terminals send the regular enter/move
+		// transition independently, so clicks do not need to synthesize one.
+		return span && (event.type === "enter" || event.type === "move")
+			? this.dispatch(span, { ...event, type: "enter" })
+			: false;
+	}
+
+	private dispatch(span: ComponentStackSpan, event: TuiMouseEvent): boolean {
+		const handler = (span.component as MouseComponent).onMouse;
+		if (!handler) return false;
+		return handler.call(span.component, { ...event, row: event.row - span.row });
+	}
+
+	private clampActiveChild(): void {
+		if (this.stackChildren.length === 0) {
+			this.activeChild = undefined;
+			return;
+		}
+		if (this.activeChild === undefined || this.activeChild < 0 || this.activeChild >= this.stackChildren.length) {
+			this.activeChild = 0;
+		}
+	}
+}

package/src/content/markdown-code.ts

@@ -0,0 +1,60 @@
+export interface TextRange {
+	readonly start: number;
+	readonly end: number;
+}
+
+interface Fence {
+	readonly marker: "`" | "~";
+	readonly length: number;
+}
+
+const FENCE = /^ {0,3}(`{3,}|~{3,})/u;
+
+/** Find fenced and inline Markdown code ranges without parsing unrelated Markdown syntax. */
+export function markdownCodeRanges(lines: readonly string[]): readonly (readonly TextRange[])[] {
+	let fence: Fence | undefined;
+	return lines.map((line) => {
+		const marker = FENCE.exec(line)?.[1];
+		if (fence) {
+			if (
+				marker?.[0] === fence.marker &&
+				marker.length >= fence.length &&
+				/^[ \t]*$/u.test(line.slice(line.indexOf(marker) + marker.length))
+			) {
+				fence = undefined;
+			}
+			return [{ start: 0, end: line.length }];
+		}
+		if (marker) {
+			fence = { marker: marker[0] as Fence["marker"], length: marker.length };
+			return [{ start: 0, end: line.length }];
+		}
+		return inlineCodeRanges(line);
+	});
+}
+
+function inlineCodeRanges(line: string): TextRange[] {
+	const ranges: TextRange[] = [];
+	for (let start = 0; start < line.length; start += 1) {
+		if (line[start] !== "`" || escaped(line, start)) continue;
+		const length = markerLength(line, start);
+		const marker = "`".repeat(length);
+		const end = line.indexOf(marker, start + length);
+		if (end < 0) continue;
+		ranges.push({ start, end: end + length });
+		start = end + length - 1;
+	}
+	return ranges;
+}
+
+function markerLength(line: string, start: number): number {
+	let end = start + 1;
+	while (line[end] === "`") end += 1;
+	return end - start;
+}
+
+function escaped(line: string, index: number): boolean {
+	let slashes = 0;
+	for (let cursor = index - 1; cursor >= 0 && line[cursor] === "\\"; cursor -= 1) slashes += 1;
+	return slashes % 2 === 1;
+}

package/src/content/terminal-text.ts

@@ -0,0 +1,135 @@
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
+
+/** Remove terminal controls from text that is not explicitly a terminal projection. */
+export function sanitizeTuiText(text: string): string {
+	return stripTerminalSequences(sanitizeTuiAnsi(text).replace(/\u009b[0-?]*[ -/]*[@-~]/gu, ""))
+		.replaceAll("\r", "")
+		.replace(/[\u0000-\u0008\u000b-\u001f\u007f]/gu, "�");
+}
+
+/** Sanitize a bounded display prefix without splitting a UTF-16 surrogate pair. */
+export function sanitizeTuiTextPreview(text: string, maximumCharacters: number): string {
+	if (maximumCharacters === Number.POSITIVE_INFINITY) return sanitizeTuiText(text);
+	const limit = Math.max(1, Math.floor(Number.isFinite(maximumCharacters) ? maximumCharacters : 1));
+	if (text.length <= limit) return sanitizeTuiText(text);
+	let end = limit;
+	const last = text.charCodeAt(end - 1);
+	const next = text.charCodeAt(end);
+	if (last >= 0xd800 && last <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) end -= 1;
+	return `${sanitizeTuiText(text.slice(0, end))}…`;
+}
+
+/** Preserve SGR styling while removing terminal controls with side effects. */
+export function sanitizeTuiAnsi(text: string): string {
+	return sanitizeTuiAnsiChunk(text).text;
+}
+
+interface SanitizedAnsiChunk {
+	text: string;
+	pending: string;
+}
+
+/** Sanitize one stream chunk while retaining a split terminal sequence for the next chunk. */
+export function sanitizeTuiAnsiChunk(text: string, maxPending = 4_096): SanitizedAnsiChunk {
+	let safe = "";
+	let plainStart = 0;
+	for (let index = terminalSequenceStart(text); index !== undefined; ) {
+		safe += sanitizePlainSegment(text.slice(plainStart, index));
+		const sequence = terminalSequenceEnd(text, index);
+		if (sequence === undefined) return { text: safe, pending: boundPending(text.slice(index), maxPending) };
+		if (sequence.kind === "sgr") safe += text.slice(index, sequence.end);
+		plainStart = sequence.end;
+		index = terminalSequenceStart(text, sequence.end);
+	}
+	return { text: safe + sanitizePlainSegment(text.slice(plainStart)), pending: "" };
+}
+
+function boundPending(pending: string, maximum: number): string {
+	const limit = Math.max(4, Math.floor(Number.isFinite(maximum) ? maximum : 4_096));
+	if (pending.length <= limit) return pending;
+	const csiPrefix = pending.charCodeAt(0) === 0x9b ? "\u009b" : pending.startsWith("\u001b[") ? "\u001b[" : undefined;
+	if (csiPrefix) {
+		const tail = pending.slice(-(limit - csiPrefix.length - 1));
+		return `${csiPrefix}!${tail}`;
+	}
+	const prefixLength = pending.charCodeAt(0) === 0x1b ? 2 : 1;
+	const prefix = pending.slice(0, prefixLength);
+	return prefix + pending.slice(-(limit - prefix.length));
+}
+
+/** Sanitize and flatten one action-row field. */
+export function sanitizeTuiField(text: string): string {
+	return sanitizeTuiText(text).replace(/[\n\t]+/gu, " ");
+}
+
+/** Sanitize and flatten a bounded action-row prefix. */
+export function sanitizeTuiFieldPreview(text: string, maximumCharacters: number): string {
+	return sanitizeTuiTextPreview(text, maximumCharacters).replace(/[\n\t]+/gu, " ");
+}
+
+function sanitizePlainSegment(text: string): string {
+	return text.replaceAll("\r", "").replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu, "�");
+}
+
+export function terminalSequenceStart(text: string, start = 0): number | undefined {
+	for (let index = start; index < text.length; index += 1) {
+		const code = text.charCodeAt(index);
+		if (
+			code === 0x1b ||
+			code === 0x90 ||
+			code === 0x98 ||
+			code === 0x9b ||
+			code === 0x9d ||
+			code === 0x9e ||
+			code === 0x9f
+		)
+			return index;
+	}
+	return undefined;
+}
+
+export function terminalSequenceEnd(text: string, start: number): { end: number; kind: "sgr" | "control" } | undefined {
+	const control = text.charCodeAt(start);
+	const csiStart = control === 0x9b ? start + 1 : text[start + 1] === "[" ? start + 2 : -1;
+	if (csiStart >= 0) {
+		for (let index = csiStart; index < text.length; index += 1) {
+			const code = text.charCodeAt(index);
+			if (code < 0x40 || code > 0x7e) continue;
+			const parameters = text.slice(csiStart, index);
+			return {
+				end: index + 1,
+				kind: text[index] === "m" && /^[0-9:;?]*$/u.test(parameters) ? "sgr" : "control",
+			};
+		}
+		return undefined;
+	}
+	if (control === 0x9d) {
+		const end = stringControlEnd(text, start + 1, true);
+		return end === undefined ? undefined : { end, kind: "control" };
+	}
+	if (control === 0x90 || control === 0x98 || control === 0x9e || control === 0x9f) {
+		const end = stringControlEnd(text, start + 1, false);
+		return end === undefined ? undefined : { end, kind: "control" };
+	}
+
+	const introducer = text[start + 1];
+	if (introducer === undefined) return undefined;
+	if (introducer === "]") {
+		const end = stringControlEnd(text, start + 2, true);
+		return end === undefined ? undefined : { end, kind: "control" };
+	}
+	if (introducer === "P" || introducer === "^" || introducer === "_") {
+		const end = stringControlEnd(text, start + 2, false);
+		return end === undefined ? undefined : { end, kind: "control" };
+	}
+	return { end: Math.min(text.length, start + 2), kind: "control" };
+}
+
+function stringControlEnd(text: string, start: number, bellTerminates: boolean): number | undefined {
+	for (let index = start; index < text.length; index += 1) {
+		if (bellTerminates && text.charCodeAt(index) === 0x07) return index + 1;
+		if (text.charCodeAt(index) === 0x9c) return index + 1;
+		if (text.charCodeAt(index) === 0x1b && text[index + 1] === "\\") return index + 2;
+	}
+	return undefined;
+}

package/src/content/text.ts

@@ -0,0 +1,105 @@
+import { highlightCode, type Theme } from "@earendil-works/pi-coding-agent";
+import type { MarkdownTheme } from "@earendil-works/pi-tui";
+import { type Component, Markdown, truncateToWidth } from "@earendil-works/pi-tui";
+import { tuiTheme } from "../color/theme.ts";
+import { RenderedLinesCache } from "../render-cache.ts";
+import { getTuiRenderEpoch } from "../render-epoch.ts";
+import { sanitizeTuiText } from "./terminal-text.ts";
+
+/**
+ * Builds the complete theme contract required by Pi's native Markdown renderer.
+ * Markdown element colors resolve through pi-libtui semantic tokens. Syntax
+ * parsing and language coverage remain delegated to Pi's native highlighter;
+ * this function is the sole alias boundary that exposes those native syntax
+ * colors to consumers.
+ *
+ * @param theme The active Pi theme used to derive pi-libtui colors and preserve
+ * non-color text attributes such as bold, italic, and underline.
+ * @returns A Markdown renderer theme whose color ownership stays behind
+ * pi-libtui, including the native syntax-highlighting alias.
+ */
+export function semanticMarkdownTheme(theme: Theme): MarkdownTheme {
+	const colors = tuiTheme(theme);
+	return {
+		heading: (text) => colors.fg("heading", text),
+		link: (text) => colors.fg("accent", text),
+		linkUrl: (text) => colors.fg("text.secondary", text),
+		code: (text) => colors.fg("warning", text),
+		codeBlock: (text) => colors.fg("text.primary", text),
+		codeBlockBorder: (text) => colors.fg("border", text),
+		quote: (text) => colors.fg("text.secondary", text),
+		quoteBorder: (text) => colors.fg("border", text),
+		hr: (text) => colors.fg("border", text),
+		listBullet: (text) => colors.fg("accent", text),
+		bold: (text) => theme.bold?.(text) ?? text,
+		italic: (text) => theme.italic?.(text) ?? text,
+		strikethrough: (text) => `\x1b[9m${text}\x1b[29m`,
+		underline: (text) => theme.underline?.(text) ?? text,
+		// Pi owns parsing and language coverage; pi-libtui owns this native-color alias.
+		highlightCode,
+	};
+}
+
+export interface MarkdownTextOptions {
+	readonly theme: Theme;
+	readonly text: string;
+	readonly maxRows?: number;
+	readonly maxCharacters?: number;
+}
+
+/** Bounded native Markdown rendering without a card, gutter, or padding. */
+export class MarkdownText implements Component {
+	private readonly markdown: Markdown;
+	private readonly cache = new RenderedLinesCache();
+	private renderEpoch = getTuiRenderEpoch();
+	private text: string;
+
+	constructor(private readonly options: MarkdownTextOptions) {
+		this.text = typeof options.text === "string" ? sanitizeTuiText(options.text) : "";
+		this.markdown = new Markdown(this.clippedText(), 0, 0, semanticMarkdownTheme(options.theme));
+	}
+
+	setText(text: string): void {
+		const normalized = typeof text === "string" ? sanitizeTuiText(text) : "";
+		if (normalized === this.text) return;
+		this.text = normalized;
+		this.markdown.setText(this.clippedText());
+		this.cache.clear();
+	}
+
+	render(width: number): string[] {
+		const epoch = getTuiRenderEpoch();
+		if (epoch !== this.renderEpoch) {
+			this.renderEpoch = epoch;
+			this.markdown.invalidate();
+		}
+		const boundedWidth = Math.max(0, Math.floor(width));
+		if (boundedWidth === 0) return [];
+		return this.cache.get(boundedWidth, "current", () => {
+			const rows = this.markdown.render(boundedWidth);
+			const limit = finiteBound(this.options.maxRows, 500, 1);
+			if (rows.length <= limit) return rows;
+			return [...rows.slice(0, limit - 1), truncateToWidth("… content omitted …", boundedWidth, "…")];
+		});
+	}
+
+	invalidate(): void {
+		this.markdown.invalidate();
+		this.cache.clear();
+	}
+
+	private clippedText(): string {
+		const maximum = finiteBound(this.options.maxCharacters, 20_000, 0);
+		const clipped = this.text.length > maximum ? `${this.text.slice(0, Math.max(0, maximum - 1))}…` : this.text;
+		if (clipped.length <= 4_000) return clipped;
+		let delimiters = 0;
+		for (let index = 0; index < clipped.length; index += 1) {
+			if ("*_~`#[](){}|>".includes(clipped[index]!)) delimiters += 1;
+		}
+		return delimiters > clipped.length / 2 ? `${clipped.slice(0, 1_999)}\n\n… content omitted …` : clipped;
+	}
+}
+
+function finiteBound(value: number | undefined, fallback: number, minimum: number): number {
+	return typeof value === "number" && Number.isFinite(value) ? Math.max(minimum, Math.floor(value)) : fallback;
+}