pi-libtui 0.3.2

package/src/tool/expanded-region-viewport.ts

@@ -0,0 +1,103 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { matchesKey } from "@earendil-works/pi-tui";
+import type { TuiMouseEvent } from "../mouse.ts";
+import { getTuiRenderEpoch } from "../render-epoch.ts";
+import { applyScrollbar } from "../scrollbar.ts";
+
+/** Shared bounded payload viewport for every expanded mode. */
+export class ExpandedRegionViewport implements Component {
+	private maxHeight: number;
+	private readonly allowGrowth: boolean;
+	private scrollTop = 0;
+	private renderedWidth = 0;
+	private renderedBodyHeight = 0;
+	private renderedContentHeight = 0;
+	private cachedWidth = -1;
+	private cachedEpoch = -1;
+	private cachedLines: string[] | undefined;
+
+	constructor(
+		private readonly renderSource: (width: number) => string[],
+		maxHeight: number,
+		allowGrowth: boolean,
+		private readonly theme: Theme,
+		private readonly requestRender: () => void,
+	) {
+		this.maxHeight = Number.isFinite(maxHeight) ? Math.max(1, Math.floor(maxHeight)) : 20;
+		this.allowGrowth = allowGrowth;
+	}
+
+	ensureMinimumHeight(rows: number): void {
+		if (!this.allowGrowth || !Number.isFinite(rows)) return;
+		this.maxHeight = Math.max(this.maxHeight, Math.max(1, Math.floor(rows)));
+	}
+
+	render(width: number): string[] {
+		this.renderedWidth = Math.max(0, Math.floor(width));
+		const epoch = getTuiRenderEpoch();
+		if (this.cachedWidth !== this.renderedWidth || this.cachedEpoch !== epoch || !this.cachedLines) {
+			this.cachedWidth = this.renderedWidth;
+			this.cachedEpoch = epoch;
+			this.cachedLines = this.renderSource(this.renderedWidth);
+		}
+		const lines = this.cachedLines;
+		this.renderedContentHeight = lines.length;
+		this.renderedBodyHeight = this.maxHeight;
+		const maxScrollTop = Math.max(0, lines.length - this.renderedBodyHeight);
+		this.scrollTop = Math.max(0, Math.min(this.scrollTop, maxScrollTop));
+		const visible = lines.slice(this.scrollTop, this.scrollTop + this.renderedBodyHeight);
+		return applyScrollbar(visible, {
+			theme: this.theme,
+			width: this.renderedWidth,
+			height: this.renderedBodyHeight,
+			offset: this.scrollTop,
+			total: lines.length,
+		});
+	}
+
+	get scrollOffset(): number {
+		return this.scrollTop;
+	}
+
+	handleViewportInput(data: string): boolean {
+		if (matchesKey(data, "up")) return this.scrollBy(-1);
+		if (matchesKey(data, "down")) return this.scrollBy(1);
+		if (matchesKey(data, "pageUp")) return this.scrollBy(-Math.max(1, this.renderedBodyHeight - 1));
+		if (matchesKey(data, "pageDown")) return this.scrollBy(Math.max(1, this.renderedBodyHeight - 1));
+		if (matchesKey(data, "home")) return this.scrollTo(0);
+		if (matchesKey(data, "end")) return this.scrollTo(Number.MAX_SAFE_INTEGER);
+		return false;
+	}
+
+	onMouse(event: TuiMouseEvent): boolean {
+		if (event.type !== "wheel" || event.wheel === undefined) return false;
+		return this.scrollBy(event.wheel === -1 ? -3 : 3);
+	}
+
+	invalidate(): void {
+		this.cachedLines = undefined;
+		this.cachedWidth = -1;
+		this.cachedEpoch = -1;
+	}
+
+	scrollToStart(): void {
+		this.scrollTop = 0;
+	}
+
+	private maxScrollTop(): number {
+		return Math.max(0, this.renderedContentHeight - this.renderedBodyHeight);
+	}
+
+	private scrollTo(next: number): boolean {
+		const clamped = Math.max(0, Math.min(this.maxScrollTop(), Math.floor(next)));
+		if (clamped === this.scrollTop) return false;
+		this.scrollTop = clamped;
+		this.requestRender();
+		return true;
+	}
+
+	private scrollBy(delta: number): boolean {
+		return this.scrollTo(this.scrollTop + delta);
+	}
+}

package/src/tool/index.ts

@@ -0,0 +1,26 @@
+export type {
+	LiveToolActionOptions,
+	ToolActionOptions,
+	ToolActionView,
+	ToolTranscriptStatus,
+} from "./action.ts";
+export { LiveToolAction, ToolAction } from "./action.ts";
+export type {
+	TerminalOutputUpdate,
+	ToolActivityAction,
+	ToolActivityOptions,
+	ToolActivityPayload,
+	ToolActivityView,
+	ToolOutputUpdate,
+} from "./activity.ts";
+export { ToolActivity } from "./activity.ts";
+export { settleToolCallPreview, toolCallPreview } from "./call-preview.ts";
+export { ToolDisclosureAction } from "./disclosure-action.ts";
+export type { ToolOutputOptions, ToolOutputView, ToolOutputViewport } from "./output.ts";
+export { ToolOutput } from "./output.ts";
+export type { ToolTranscriptOptions } from "./transcript.ts";
+export { ToolTranscript } from "./transcript.ts";
+export { mountTranscriptProjection } from "../host/transcript-bridge.ts";
+export type { TranscriptEntry, TranscriptProjection } from "../host/transcript-bridge.ts";
+export type { OmissionRowProvider, ToolViewMode, ToolViewRegionOptions } from "./view-region.ts";
+export { ToolViewRegion } from "./view-region.ts";

package/src/tool/output.ts

@@ -0,0 +1,271 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { tuiTheme } from "../color/theme.ts";
+import { sanitizeTuiAnsiChunk } from "../content/terminal-text.ts";
+import { RenderedLinesCache } from "../render-cache.ts";
+import { BoundedStreamBuffer, type BoundedStreamSnapshot } from "../stream.ts";
+
+/** Complete replace-style state for a streaming tool output surface. */
+export interface ToolOutputView {
+	text: string;
+	/** Monotonic caller-owned content revision used for exact render caching. */
+	revision: number;
+}
+
+/** Explicit bounded row policy selected by a tool-owned view mode. */
+export interface ToolOutputViewport {
+	maxRows: number;
+	selection?: "head" | "tail" | "head-tail";
+}
+
+/** Bounds and appearance for a streaming tool output surface. */
+export interface ToolOutputOptions {
+	theme: Theme;
+	initial?: ToolOutputView;
+	viewport?: ToolOutputViewport;
+	/** Maximum retained output budget, measured as UTF-8 bytes by the stream buffer. */
+	maxCharacters?: number;
+}
+
+/**
+ * A bounded, ANSI-safe output component with explicit append and replace paths.
+ *
+ * Callers own stream semantics, revisions, and named view modes; the component
+ * owns retention, bounded row selection, wrapping, and stable output references.
+ */
+export class ToolOutput implements Component {
+	private readonly cache = new RenderedLinesCache();
+	private readonly stream: BoundedStreamBuffer;
+	private readonly renderStreams = new Map<string, BoundedStreamBuffer>();
+	private streamSnapshot: BoundedStreamSnapshot;
+	private ansiPending = "";
+	private plainAscii: boolean;
+	private currentRevision: number;
+	private hasRevision: boolean;
+	private cumulativeSourceLength: number;
+	private viewport: Required<ToolOutputViewport>;
+	private readonly maxCharacters: number;
+	private omissionRow: number | undefined;
+
+	constructor(private readonly options: ToolOutputOptions) {
+		this.maxCharacters = finitePositive(options.maxCharacters, 1_000_000);
+		this.viewport = normalizeViewport(options.viewport);
+		this.stream = new BoundedStreamBuffer({ maxBytes: this.maxCharacters, omissionMarker: () => "" });
+		this.streamSnapshot = this.stream.snapshot();
+		this.plainAscii = true;
+		this.currentRevision = 0;
+		this.hasRevision = false;
+		this.cumulativeSourceLength = 0;
+		this.omissionRow = undefined;
+		this.reset(options.initial);
+	}
+
+	getOmissionRow(): number | undefined {
+		return this.omissionRow;
+	}
+
+	/** Replace the complete visible stream state. */
+	replace(view: ToolOutputView): void {
+		if (this.hasRevision && view.revision === this.currentRevision) return;
+		this.reset(view);
+	}
+
+	/** Start a new stream, even when its first revision matches the previous stream. */
+	reset(view?: ToolOutputView): void {
+		const source = view?.text ?? "";
+		const sanitized = sanitizeTuiAnsiChunk(source, Math.min(this.maxCharacters, 4_096));
+		const safeText = sanitized.text;
+		this.streamSnapshot = this.stream.replaceFinal(safeText);
+		this.plainAscii = isPlainAscii(safeText);
+		this.ansiPending = "";
+		this.currentRevision = view?.revision ?? 0;
+		this.hasRevision = view !== undefined;
+		this.cumulativeSourceLength = source.length;
+		this.omissionRow = undefined;
+		this.renderStreams.clear();
+		this.cache.clear();
+	}
+
+	/** Consume a cumulative append-only snapshot without copying its retained prefix. */
+	appendCumulative(text: string, revision: number): void {
+		if (text.length < this.cumulativeSourceLength) {
+			this.replace({ text, revision });
+			return;
+		}
+		const chunk = text.slice(this.cumulativeSourceLength);
+		this.append(chunk, revision);
+	}
+
+	/** Append one stream chunk and advance to the caller-owned revision. */
+	append(chunk: string, revision: number): void {
+		this.cumulativeSourceLength += chunk.length;
+		const sanitized = sanitizeTuiAnsiChunk(this.ansiPending + chunk, Math.min(this.maxCharacters, 4_096));
+		this.ansiPending = sanitized.pending;
+		const safeChunk = sanitized.text;
+		if (safeChunk.length > 0) {
+			this.plainAscii &&= isPlainAscii(safeChunk);
+			this.streamSnapshot = this.stream.append(safeChunk);
+			for (const stream of this.renderStreams.values()) stream.append(safeChunk);
+		} else {
+			this.streamSnapshot = this.stream.snapshot();
+		}
+		this.currentRevision = revision;
+		this.hasRevision = true;
+		this.omissionRow = undefined;
+		this.cache.clear();
+	}
+
+	/** Apply an explicit bounded row policy chosen by the owning tool mode. */
+	setViewport(viewport: ToolOutputViewport): void {
+		const next = normalizeViewport(viewport);
+		if (this.viewport.maxRows === next.maxRows && this.viewport.selection === next.selection) return;
+		this.viewport = next;
+		this.omissionRow = undefined;
+		this.renderStreams.clear();
+		this.cache.clear();
+	}
+
+	render(width: number): string[] {
+		const key = `${this.currentRevision}\0${this.viewport.maxRows}\0${this.viewport.selection}\0${this.streamSnapshot.totalBytes}\0${this.streamSnapshot.omittedBytes}\0${this.streamSnapshot.truncated}\0${this.plainAscii}`;
+		return this.cache.get(width, key, () => this.renderFresh(width));
+	}
+
+	private renderFresh(width: number): string[] {
+		this.omissionRow = undefined;
+		if (width <= 0) return [];
+		const maximum = this.viewport.maxRows;
+		const boundedText = this.renderText(maximum, width);
+		const visibleText = boundedText.replace(/\n$/, "");
+		const wrapped =
+			boundedText.length === 0
+				? []
+				: this.plainAscii
+					? wrapPlainAscii(visibleText, width)
+					: wrapTextWithAnsi(visibleText, width);
+		const prefix = this.streamSnapshot.truncated ? 1 : 0;
+		const available = maximum - prefix;
+		if (available === 0) {
+			const colors = tuiTheme(this.options.theme);
+			this.omissionRow = 0;
+			return [
+				truncateToWidth(
+					colors.fg("text.muted", `… ${this.streamSnapshot.omittedBytes} earlier characters discarded`),
+					width,
+					"…",
+				),
+			];
+		}
+		const bounded = boundRows(wrapped, available, width, this.options.theme, this.viewport.selection);
+		if (!this.streamSnapshot.truncated) {
+			this.omissionRow = bounded.omissionRow;
+			return bounded.lines;
+		}
+		const colors = tuiTheme(this.options.theme);
+		this.omissionRow = 0;
+		return [
+			truncateToWidth(
+				colors.fg("text.muted", `… ${this.streamSnapshot.omittedBytes} earlier characters discarded`),
+				width,
+				"…",
+			),
+			...bounded.lines,
+		];
+	}
+
+	private renderText(rows: number, width: number): string {
+		// Two source code units per visible cell leaves room for ANSI and wide
+		// glyphs without rescanning retained history on every streamed frame.
+		const budget = Math.max(256, rows * Math.max(1, width) * 2);
+		const key = `${this.viewport.maxRows}\0${width}`;
+		let stream = this.renderStreams.get(key);
+		if (stream === undefined) {
+			if (this.renderStreams.size >= 4) this.renderStreams.clear();
+			stream = new BoundedStreamBuffer({
+				maxBytes: budget,
+				omissionMarker: () => "\n… output clipped before wrapping …\n",
+			});
+			stream.replaceFinal(this.streamSnapshot.text);
+			this.renderStreams.set(key, stream);
+		}
+		return stream.snapshot().text;
+	}
+
+	invalidate(): void {
+		this.cache.clear();
+	}
+}
+
+function finitePositive(value: number | undefined, fallback: number): number {
+	return typeof value === "number" && Number.isFinite(value) ? Math.max(1, Math.floor(value)) : fallback;
+}
+
+function isPlainAscii(text: string): boolean {
+	return /^[\x20-\x7e\n]*$/u.test(text);
+}
+
+function wrapPlainAscii(text: string, width: number): string[] {
+	const rows: string[] = [];
+	for (const line of text.split("\n")) {
+		if (line.length === 0) rows.push("");
+		else for (let index = 0; index < line.length; index += width) rows.push(line.slice(index, index + width));
+	}
+	return rows;
+}
+
+interface BoundedRows {
+	readonly lines: string[];
+	readonly omissionRow?: number;
+}
+
+function boundRows(
+	lines: readonly string[],
+	maximum: number,
+	width: number,
+	theme: Theme,
+	selection: Required<ToolOutputViewport>["selection"],
+): BoundedRows {
+	if (lines.length <= maximum) return { lines: [...lines] };
+	const colors = tuiTheme(theme);
+	if (maximum === 1)
+		return {
+			lines: [truncateToWidth(colors.fg("text.muted", `… ${lines.length} rows`), width, "…")],
+			omissionRow: 0,
+		};
+	const visibleRows = maximum - 1;
+	if (selection === "head") {
+		return {
+			lines: [
+				...lines.slice(0, visibleRows),
+				truncateToWidth(colors.fg("text.muted", `… ${lines.length - visibleRows} rows omitted …`), width, "…"),
+			],
+			omissionRow: visibleRows,
+		};
+	}
+	if (selection === "tail") {
+		return {
+			lines: [
+				truncateToWidth(colors.fg("text.muted", `… ${lines.length - visibleRows} rows omitted …`), width, "…"),
+				...lines.slice(-visibleRows),
+			],
+			omissionRow: 0,
+		};
+	}
+	const head = Math.floor(visibleRows / 2);
+	const tail = visibleRows - head;
+	const omitted = lines.length - head - tail;
+	return {
+		lines: [
+			...lines.slice(0, head),
+			truncateToWidth(colors.fg("text.muted", `… ${omitted} rows omitted …`), width, "…"),
+			...lines.slice(lines.length - tail),
+		],
+		omissionRow: head,
+	};
+}
+
+function normalizeViewport(viewport: ToolOutputViewport | undefined): Required<ToolOutputViewport> {
+	const requested = viewport?.maxRows ?? 6;
+	const maxRows = Number.isFinite(requested) ? Math.min(10_000, Math.max(1, Math.floor(requested))) : 6;
+	return { maxRows, selection: viewport?.selection ?? "head-tail" };
+}

package/src/tool/transcript.ts

@@ -0,0 +1,150 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { ComponentStack, type ComponentStackSpan } from "../component-stack.ts";
+import { FOLD_TARGET_AT_ROW, type FoldTarget, type FoldTargetAtRow, foldTargetAt } from "../folding.ts";
+import { TEXT_INTERACTION_TARGET, type TextInteractionTarget, type TuiMouseEvent } from "../mouse.ts";
+import { ToolAction, type ToolActionView } from "./action.ts";
+
+export interface ToolTranscriptOptions {
+	theme: Theme;
+	view?: ToolActionView;
+	action?: Component;
+	body?: readonly Component[];
+	maxRows?: number;
+	/** Columns of leading whitespace added to every payload row. */
+	bodyIndent?: number;
+}
+
+/**
+ * A copy-friendly tool transcript: one action sentence followed by its payload.
+ * Payload components render at the caller's width minus `bodyIndent`; the
+ * transcript does not impose a background.
+ */
+export class ToolTranscript implements Component {
+	private readonly stack: ComponentStack;
+	private readonly maxRows: number | undefined;
+	private readonly bodyIndent: number;
+	private bodies: TranscriptBody[];
+
+	constructor(options: ToolTranscriptOptions) {
+		const action =
+			options.action ?? (options.view ? new ToolAction({ theme: options.theme, view: options.view }) : undefined);
+		if (!action) throw new Error("ToolTranscript requires an action or view");
+		this.bodyIndent = Math.max(0, Math.floor(options.bodyIndent ?? 0));
+		this.bodies = (options.body ?? []).map((component) => new TranscriptBody(component, this.bodyIndent));
+		this.maxRows = normalizedRows(options.maxRows);
+		this.stack = new ComponentStack([action, ...this.bodies], { maxHeight: this.maxRows });
+	}
+
+	/** Replace payload components while retaining wrappers for stable component identities. */
+	setBody(components: readonly Component[]): void {
+		const available = [...this.bodies];
+		this.bodies = components.map((component) => {
+			const existingIndex = available.findIndex((body) => body.wraps(component));
+			return existingIndex < 0
+				? new TranscriptBody(component, this.bodyIndent)
+				: available.splice(existingIndex, 1)[0]!;
+		});
+		for (const body of available) body.dispose();
+		this.stack.setChildren([this.stack.getChildren()[0]!, ...this.bodies]);
+	}
+
+	render(width: number): string[] {
+		return this.stack.render(width);
+	}
+
+	handleViewportInput(data: string): boolean {
+		return this.stack.handleViewportInput(data);
+	}
+
+	onMouse(event: TuiMouseEvent): boolean {
+		return this.stack.onMouse(event);
+	}
+
+	get children(): readonly Component[] {
+		return this.stack.getChildren();
+	}
+
+	getSpans(): readonly ComponentStackSpan[] {
+		const spans = this.stack.getSpans();
+		if (this.maxRows === undefined) return spans;
+		return spans
+			.filter((span) => span.row < this.maxRows!)
+			.map((span) => ({ ...span, height: Math.min(span.height, this.maxRows! - span.row) }));
+	}
+
+	invalidate(): void {
+		this.stack.invalidate();
+	}
+
+	dispose(): void {
+		for (const component of new Set(this.stack.getChildren()))
+			(component as Component & { dispose?(): void }).dispose?.();
+	}
+}
+
+/** Structural payload wrapper that indents rows and preserves nested viewport and fold contracts. */
+class TranscriptBody implements Component, TextInteractionTarget, FoldTargetAtRow {
+	readonly [TEXT_INTERACTION_TARGET] = true as const;
+	private readonly gutter: string;
+
+	constructor(
+		private component: Component,
+		private readonly indent: number,
+	) {
+		this.gutter = " ".repeat(indent);
+	}
+
+	wraps(component: Component): boolean {
+		return this.component === component;
+	}
+
+	render(width: number): string[] {
+		const inner = Math.max(0, Math.floor(width) - this.indent);
+		if (this.indent === 0) return this.component.render(inner);
+		if (inner === 0) return [];
+		return this.component.render(inner).map((line) => `${this.gutter}${line}`);
+	}
+
+	invalidate(): void {
+		this.component.invalidate();
+	}
+
+	dispose(): void {
+		(this.component as Component & { dispose?(): void }).dispose?.();
+	}
+
+	setViewportFocus(focused: boolean): void {
+		this.interactive()?.setViewportFocus?.(focused);
+	}
+
+	isViewportFocused(): boolean {
+		return this.interactive()?.isViewportFocused?.() ?? false;
+	}
+
+	handleViewportInput(data: string): boolean {
+		return this.interactive()?.handleViewportInput?.(data) ?? false;
+	}
+
+	onMouse(event: TuiMouseEvent): boolean {
+		return this.interactive()?.onMouse?.({ ...event, col: event.col - this.indent }) ?? false;
+	}
+
+	[FOLD_TARGET_AT_ROW](row: number): FoldTarget | undefined {
+		return foldTargetAt(this.component, row);
+	}
+
+	private interactive() {
+		return this.component as Component & {
+			setViewportFocus?(focused: boolean): void;
+			isViewportFocused?(): boolean;
+			handleViewportInput?(data: string): boolean;
+			onMouse?(event: TuiMouseEvent): boolean;
+		};
+	}
+}
+
+function normalizedRows(rows: number | undefined): number | undefined {
+	if (rows === undefined || !Number.isFinite(rows)) return undefined;
+	return Math.max(0, Math.floor(rows));
+}