@oh-my-pi/pi-tui 18.2.4 → 18.2.6

package/src/chat/transcript-browser.ts

@@ -0,0 +1,268 @@
+import type { Component } from "../tui";
+import { type ScrollRangeAnchor, ScrollView } from "../components/scroll-view";
+import { DynamicBorder } from "../chrome/dynamic-border";
+import { truncateToWidth } from "../utils";
+import { theme } from "../theme/theme";
+import {
+	composeOutlineColumn,
+	type ComposedColumn,
+	OutlineRowCache,
+	type OutlineStyle,
+	type OutlineTarget,
+	outlineVisibility,
+} from "./transcript-outline";
+
+/** Logical body rows and optional selection supplied by a transcript browser controller. */
+export interface TranscriptBrowserBody {
+	lines: readonly string[];
+	anchor?: ScrollRangeAnchor;
+}
+
+/** One complete browser frame. Header and footer rows are inset by one column. */
+export interface TranscriptBrowserFrame {
+	header: readonly string[];
+	body: TranscriptBrowserBody;
+	footer: readonly string[];
+}
+
+/** Widths available while composing a transcript browser frame. */
+export interface TranscriptBrowserRenderContext {
+	/** Width passed to {@link TranscriptBrowser.render}. */
+	frameWidth: number;
+	/** Stable transcript width, reserving the final column for an automatic scrollbar. */
+	contentWidth: number;
+	/** Width for inset header/footer children such as an editor. */
+	chromeWidth: number;
+}
+
+/** Construction options for the shared transcript browser viewport and frame. */
+export interface TranscriptBrowserOptions {
+	/** Explicit height budget supplied by the fullscreen host. */
+	getHeight: () => number;
+	/** Domain controller which supplies header, body, footer, and optional selection. */
+	frame: (context: TranscriptBrowserRenderContext) => TranscriptBrowserFrame;
+	/** Preserve the historical three-row minimum used by transcript overlays. */
+	minimumBodyRows?: number;
+	/** Start in append-follow mode; manual scrolling updates the mode automatically. */
+	followBottom?: boolean;
+}
+
+/** Prepared transcript rows, visibility, and nearest valid selection. */
+export interface PreparedTranscriptOutline {
+	childRows: Array<readonly string[]>;
+	visible: boolean[];
+	selected: number;
+}
+
+/** Options for composing the standard single-column dotted transcript outline. */
+export interface TranscriptOutlineComposition {
+	children: readonly Component[];
+	targets: readonly OutlineTarget[];
+	selected: number;
+	columnWidth: number;
+	/** Reuse rows already prepared for custom branch/block composition in the same frame. */
+	prepared?: PreparedTranscriptOutline;
+	from?: number;
+	to?: number;
+	header?: string[];
+	style?: OutlineStyle;
+}
+
+interface BrowserLayout {
+	bodyTop: number;
+	bodyHeight: number;
+}
+
+function sameLines(left: readonly string[], right: readonly string[]): boolean {
+	if (left.length !== right.length) return false;
+	for (let index = 0; index < left.length; index++) {
+		if (left[index] !== right[index]) return false;
+	}
+	return true;
+}
+
+/** Nearest visible target, preferring the preceding item just like the legacy selectors. */
+export function nearestVisibleOutlineTarget(visible: readonly boolean[], selected: number): number {
+	if (selected < 0 || selected >= visible.length) return visible.findIndex(Boolean);
+	if (visible[selected] !== false) return selected;
+	for (let above = selected - 1; above >= 0; above--) {
+		if (visible[above] !== false) return above;
+	}
+	for (let below = selected + 1; below < visible.length; below++) {
+		if (visible[below] !== false) return below;
+	}
+	return selected;
+}
+
+/**
+ * Shared framed viewport for transcript browsers.
+ *
+ * Domain controllers retain loading, actions, and branch/block presentation;
+ * this component owns outline row caching, frame sizing, scroll state,
+ * selection anchoring, append-follow behavior, and frame-to-body coordinates.
+ */
+export class TranscriptBrowser implements Component {
+	readonly debugChildren: readonly Component[];
+
+	readonly #options: TranscriptBrowserOptions;
+	readonly #scrollView: ScrollView;
+	readonly #border = new DynamicBorder();
+	readonly #rowCache = new OutlineRowCache();
+	#followBottom: boolean;
+	#layout: BrowserLayout | undefined;
+	#cachedLines: readonly string[] | undefined;
+
+	constructor(options: TranscriptBrowserOptions) {
+		this.#options = options;
+		this.#followBottom = options.followBottom ?? false;
+		this.#scrollView = new ScrollView([], {
+			height: 0,
+			scrollbar: "auto",
+			followTail: this.#followBottom,
+			theme: { track: text => theme.fg("dim", text), thumb: text => theme.fg("accent", text) },
+		});
+		this.debugChildren = [this.#scrollView, this.#border];
+	}
+
+	invalidate(): void {
+		this.#cachedLines = undefined;
+		this.#border.invalidate();
+		this.#scrollView.invalidate();
+	}
+
+	/** Prompt-zone-safe rendered rows for outline composition at `columnWidth`. */
+	renderOutlineRows(children: readonly Component[], columnWidth: number): Array<readonly string[]> {
+		return this.#rowCache.rows(children, Math.max(10, columnWidth - 4));
+	}
+
+	/** Compute target visibility and snap a collapsed selection to the nearest rendered item. */
+	prepareOutline(
+		children: readonly Component[],
+		targets: readonly OutlineTarget[],
+		selected: number,
+		columnWidth: number,
+	): PreparedTranscriptOutline {
+		const childRows = this.renderOutlineRows(children, columnWidth);
+		const visible = outlineVisibility(childRows, targets);
+		return {
+			childRows,
+			visible,
+			selected: nearestVisibleOutlineTarget(visible, selected),
+		};
+	}
+
+	/** Compose the standard single-column outline using the browser-owned row cache. */
+	composeOutline(options: TranscriptOutlineComposition): PreparedTranscriptOutline & { column: ComposedColumn } {
+		const prepared =
+			options.prepared ??
+			this.prepareOutline(options.children, options.targets, options.selected, options.columnWidth);
+		return {
+			...prepared,
+			column: composeOutlineColumn(
+				prepared.childRows,
+				options.from ?? 0,
+				options.to ?? options.children.length,
+				options.targets,
+				prepared.selected,
+				options.columnWidth,
+				options.header,
+				options.style,
+			),
+		};
+	}
+
+	/** Scroll logical body rows. Returns whether the offset changed. */
+	scroll(delta: number): boolean {
+		const before = this.#scrollView.getScrollOffset();
+		this.#scrollView.scroll(delta);
+		this.#syncFollowBottom();
+		return this.#scrollView.getScrollOffset() !== before;
+	}
+
+	/** Apply the ScrollView navigation key set. */
+	handleScrollKey(data: string): boolean {
+		if (!this.#scrollView.handleScrollKey(data)) return false;
+		this.#syncFollowBottom();
+		return true;
+	}
+
+	scrollToTop(): void {
+		this.#scrollView.scrollToTop();
+		this.#syncFollowBottom();
+	}
+
+	scrollToBottom(): void {
+		this.#scrollView.scrollToBottom();
+		this.#syncFollowBottom();
+	}
+
+	/** Whether an anchor identity has successfully been applied to the viewport. */
+	hasAnchored(id: string): boolean {
+		return this.#scrollView.hasRevealedRange(id);
+	}
+
+	/**
+	 * Translate a 0-based frame mouse point into the logical, scrolled body.
+	 * Returns undefined for borders, header/footer rows, and unpainted body rows.
+	 */
+	toContentPoint(frameRow: number, frameCol: number): { row: number; col: number } | undefined {
+		const layout = this.#layout;
+		if (!layout) return undefined;
+		const localRow = Math.trunc(frameRow) - layout.bodyTop;
+		if (localRow < 0 || localRow >= layout.bodyHeight) return undefined;
+		const row = this.#scrollView.logicalRowAt(localRow);
+		if (row === undefined) return undefined;
+		return {
+			row,
+			col: Math.max(0, Math.trunc(frameCol)),
+		};
+	}
+
+	render(width: number): readonly string[] {
+		const frameWidth = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
+		const context: TranscriptBrowserRenderContext = {
+			frameWidth,
+			contentWidth: Math.max(1, frameWidth - 1),
+			chromeWidth: Math.max(1, frameWidth - 2),
+		};
+		const frame = this.#options.frame(context);
+		const heightValue = this.#options.getHeight();
+		const height = Number.isFinite(heightValue) ? Math.max(0, Math.trunc(heightValue)) : 0;
+		const borderRows = frameWidth > 0 ? 3 : 0;
+		const chromeRows = frame.header.length + frame.footer.length + borderRows;
+		const minimumBodyRows = Math.max(0, Math.trunc(this.#options.minimumBodyRows ?? 3));
+		const bodyHeight = Math.max(minimumBodyRows, height - chromeRows);
+		this.#layout = { bodyTop: frame.header.length + (frameWidth > 0 ? 2 : 0), bodyHeight };
+
+		this.#scrollView.setLines(frame.body.lines);
+		this.#scrollView.setHeight(bodyHeight);
+		if (frame.body.anchor && this.#scrollView.revealRange(frame.body.anchor, context.contentWidth)) {
+			this.#followBottom = false;
+			this.#scrollView.setFollowTail(false);
+		}
+
+		const border = frameWidth > 0 ? this.#border.render(frameWidth) : [];
+		const output: string[] = [];
+		output.push(...border);
+		for (const line of frame.header) output.push(this.#chromeLine(line, frameWidth));
+		output.push(...border);
+		output.push(...this.#scrollView.render(frameWidth));
+		for (const line of frame.footer) output.push(this.#chromeLine(line, frameWidth));
+		output.push(...border);
+		const cached = this.#cachedLines;
+		if (cached && sameLines(cached, output)) return cached;
+		this.#cachedLines = output;
+		return output;
+	}
+
+	#syncFollowBottom(): void {
+		if (!this.#options.followBottom) return;
+		this.#followBottom = this.#scrollView.getScrollOffset() >= this.#scrollView.getMaxScrollOffset();
+		this.#scrollView.setFollowTail(this.#followBottom);
+	}
+
+	#chromeLine(line: string, width: number): string {
+		if (width <= 0) return "";
+		return ` ${truncateToWidth(line, Math.max(0, width - 1))}`;
+	}
+}

package/src/chat/transcript-entry.ts

@@ -0,0 +1,96 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import { createCustomMessage } from "@oh-my-pi/pi-agent-core/compaction/messages";
+import type { MessageAttribution } from "@oh-my-pi/pi-ai";
+import {
+	type CustomMessage,
+	type CustomMessageContent,
+	isCustomMessageContent,
+	isUserTurnInitiator,
+	normalizeCustomMessagePayload,
+} from "./messages";
+import { titleTextFromSkillPrompt } from "./skill-title-input";
+
+/** Persisted message fields consumed by transcript rendering. */
+export interface SessionMessageEntryLike {
+	type: "message";
+	id: string;
+	parentId: string | null;
+	timestamp: string;
+	message: AgentMessage;
+}
+
+/** Persisted custom-message fields consumed by transcript rendering. */
+export interface CustomMessageEntryLike {
+	type: "custom_message";
+	id: string;
+	parentId: string | null;
+	timestamp: string;
+	customType: string;
+	content: CustomMessageContent;
+	details?: unknown;
+	display: boolean;
+	attribution?: MessageAttribution;
+}
+
+/** Entries that replay as visible or hidden transcript messages. */
+export type TranscriptEntryLike = SessionMessageEntryLike | CustomMessageEntryLike;
+
+/** Restore a persisted custom message, rejecting unsendable content. */
+export function customMessageEntryMessage(entry: CustomMessageEntryLike): CustomMessage | undefined {
+	if (!isCustomMessageContent(entry.content)) return undefined;
+	const normalized = normalizeCustomMessagePayload(entry);
+	const attribution = entry.attribution === undefined ? undefined : normalized.attribution;
+	return createCustomMessage(
+		normalized.customType,
+		normalized.content,
+		normalized.display,
+		normalized.details,
+		entry.timestamp,
+		attribution,
+	);
+}
+
+/** Restore the message represented by a transcript entry. */
+export function transcriptEntryMessage(entry: TranscriptEntryLike): AgentMessage | undefined {
+	return entry.type === "message" ? entry.message : customMessageEntryMessage(entry);
+}
+
+/** Identify user-authored requests among transcript and metadata entries. */
+export function isUserRequestEntry(entry: TranscriptEntryLike | { type: string }): boolean {
+	if (entry.type === "message" && "message" in entry) {
+		if (entry.message.role === "user") return true;
+		return entry.message.role === "custom" && isUserTurnInitiator(entry.message);
+	}
+	if (entry.type === "custom_message" && "content" in entry) {
+		const message = customMessageEntryMessage(entry);
+		return message !== undefined && isUserTurnInitiator(message);
+	}
+	return false;
+}
+
+/** Editable user request text, preserving skill invocation syntax. */
+export function userTurnDraft(entry: TranscriptEntryLike): string | undefined {
+	const message = transcriptEntryMessage(entry);
+	if (!message) return undefined;
+	if (message.role === "user") return textContent(message.content);
+	if (message.role !== "custom" || !isUserTurnInitiator(message)) return undefined;
+	return titleTextFromSkillPrompt(message) ?? textContent(message.content);
+}
+
+/** Extract text blocks verbatim, optionally separating block boundaries. */
+export function textContent(content: string | ReadonlyArray<{ type: string; text?: string }>, separator = ""): string {
+	if (typeof content === "string") return content;
+	let text = "";
+	let boundary = "";
+	for (const block of content) {
+		if (block.type !== "text") continue;
+		text += boundary + (block.text ?? "");
+		boundary = separator;
+	}
+	return text;
+}
+
+/** Join text blocks with spaces and collapse whitespace into a single-line label. */
+export function userMessageLabel(content: string | ReadonlyArray<{ type: string; text?: string }>): string {
+	return textContent(content, " ").replace(/\s+/g, " ").trim();
+}

package/src/chat/transcript-outline.ts

@@ -0,0 +1,260 @@
+/**
+ * Shared engine for the ephemeral fullscreen transcript selectors (esc-esc
+ * rewind, `/copy`): replay session entries through {@link ChatTranscriptBuilder},
+ * map each rendered turn to a selectable target, and compose gutter-prefixed
+ * columns with a dotted outline around the selected target.
+ */
+import { type Component } from "../tui";
+import { visibleWidth } from "../utils";
+import {
+	isUserRequestEntry,
+	type TranscriptEntryLike as TranscriptEntry,
+	userMessageLabel,
+	userTurnDraft,
+} from "./transcript-entry";
+import type { SessionMessageEntryLike as SessionMessageEntry } from "./transcript-entry";
+import { type ThemeColor, theme } from "../theme";
+import type { ChatTranscriptBuilder } from "./chat-transcript-builder";
+import { padToWidth } from "../render/utils";
+import { isUsageRowBlock } from "../overlays/usage-row";
+
+/** One selectable transcript item: a message entry plus its rendered block range. */
+export interface OutlineTarget {
+	/** Entry the selection resolves to; extended over trailing componentless tool results. */
+	entryId: string;
+	/** Entry that opened this turn (pre-fold) — anchor for tree lookups. */
+	turnId: string;
+	/** Real user prompt — drives user-turn jumps and role-specific actions. */
+	isUserTurn: boolean;
+	/** First transcript-container child rendered by this entry. */
+	start: number;
+	/** One past the last child rendered by this entry. */
+	end: number;
+	/** Entries this target spans: the turn plus any folded tool results. */
+	entries: TranscriptEntry[];
+}
+
+/** Composed rows of one column plus the outline's line range within them. */
+export interface ComposedColumn {
+	lines: string[];
+	selStart: number;
+	selEnd: number;
+}
+/** Presentation of the dotted outline: stroke color and an optional caption inset into the top rule. */
+export interface OutlineStyle {
+	color?: ThemeColor;
+	/** Short affordance label (e.g. "3 blocks →") drawn into the top rule's right end. */
+	caption?: string;
+}
+
+// User bubbles wrap their rows in OSC 133 prompt-zone marks (see
+// user-message.ts). Re-emitting those inside the alternate-screen overlay
+// latches the terminal's prompt semantics onto overlay rows and garbles the
+// frame, so embedded rows shed them; the transcript proper keeps its zones.
+const OSC133_SPAN_REGEX = /\x1b\]133;[^\x07\x1b]*(?:\x07|\x1b\\)/g;
+
+/** Copy-on-write removal of OSC 133 spans from a rendered row array. */
+export function stripPromptZones(rows: readonly string[]): readonly string[] {
+	let sanitized: string[] | undefined;
+	for (let index = 0; index < rows.length; index++) {
+		if (!rows[index]!.includes("\x1b]133;")) continue;
+		sanitized ??= rows.slice();
+		sanitized[index] = rows[index]!.replace(OSC133_SPAN_REGEX, "");
+	}
+	return sanitized ?? rows;
+}
+
+/**
+ * Prompt-zone-stripped rows for one selector column.
+ *
+ * The selectors recompose their whole column on every keystroke, and stripping
+ * every child's rows again per frame is pure waste on a long session. Per the
+ * {@link Component} render contract a child returns the same array while its
+ * rows are unchanged, so the stripped copy is keyed on that array: a child that
+ * repaints itself asynchronously (Kitty image conversion, todo strike frames)
+ * hands back a new array and is stripped again.
+ */
+export class OutlineRowCache {
+	#stripped = new WeakMap<Component, { rows: readonly string[]; stripped: readonly string[] }>();
+
+	rows(children: readonly Component[], width: number): Array<readonly string[]> {
+		const columns: Array<readonly string[]> = [];
+		for (const child of children) {
+			const rows = child.render(width);
+			const cached = this.#stripped.get(child);
+			if (cached && cached.rows === rows) {
+				columns.push(cached.stripped);
+				continue;
+			}
+			const stripped = stripPromptZones(rows);
+			this.#stripped.set(child, { rows, stripped });
+			columns.push(stripped);
+		}
+		return columns;
+	}
+}
+
+/**
+ * Append `entries` to `builder`, returning the selectable targets they
+ * produce. Tool results fold into the previous target (so a turn's rewind
+ * and `/copy` keep its output, including lazily created children such as
+ * the grouped-read card); notices and hidden messages that render nothing
+ * are skipped. Usage rows flushed at the head of an append are attributed
+ * to the turn above.
+ */
+export function appendOutlineEntries(builder: ChatTranscriptBuilder, entries: TranscriptEntry[]): OutlineTarget[] {
+	const targets: OutlineTarget[] = [];
+	for (const entry of entries) {
+		const children = builder.container.children;
+		const before = children.length;
+		builder.append([entry]);
+		const after = children.length;
+		let start = before;
+		while (start < after && isUsageRowBlock(children[start]!)) {
+			const previous = targets.at(-1);
+			if (previous && previous.end === start) previous.end = start + 1;
+			start++;
+		}
+		const previous = targets.at(-1);
+		if (entry.type === "message" && entry.message.role === "toolResult" && previous) {
+			previous.entryId = entry.id;
+			previous.entries.push(entry);
+			if (after > previous.end) previous.end = after;
+			continue;
+		}
+		if (start >= after) continue;
+		targets.push({
+			entryId: entry.id,
+			turnId: entry.id,
+			isUserTurn: isUserTurnEntry(entry),
+			start,
+			end: after,
+			entries: [entry],
+		});
+	}
+	return targets;
+}
+
+/** Per-target "renders at least one non-blank row" flags at the given rows. */
+export function outlineVisibility(
+	childRows: readonly (readonly string[])[],
+	targets: readonly OutlineTarget[],
+): boolean[] {
+	return targets.map(target => {
+		for (let index = target.start; index < target.end; index++) {
+			if (childRows[index]!.some(row => /\S/.test(row))) return true;
+		}
+		return false;
+	});
+}
+
+/** Dotted horizontal rule with rounded corners, spanning the outline width. */
+export function outlineRule(
+	left: string,
+	right: string,
+	innerWidth: number,
+	color: ThemeColor = "accent",
+	caption?: string,
+): string {
+	const label = caption ? ` ${caption} ` : "";
+	const fill = Math.max(0, innerWidth + 2 - visibleWidth(label));
+	return (
+		theme.fg(color, left + theme.boxDotted.horizontal.repeat(fill)) +
+		theme.bold(theme.fg(color, label)) +
+		theme.fg(color, right)
+	);
+}
+
+/** Wrap pre-rendered rows in the dotted outline (rules above/below, `┆` sides). */
+export function outlineRows(rows: readonly string[], innerWidth: number, style: OutlineStyle = {}): string[] {
+	const color = style.color ?? "accent";
+	const vertical = theme.fg(color, theme.boxDotted.vertical);
+	const lines: string[] = [
+		outlineRule(theme.boxRound.topLeft, theme.boxRound.topRight, innerWidth, color, style.caption),
+	];
+	for (const row of rows) lines.push(`${vertical} ${innerWidth > 0 ? padToWidth(row, innerWidth) : ""} ${vertical}`);
+	lines.push(outlineRule(theme.boxRound.bottomLeft, theme.boxRound.bottomRight, innerWidth, color));
+	return lines;
+}
+
+/**
+ * Compose one column: gutter-prefixed rows for `childRows[from, to)` with a
+ * dotted outline around `targets[selected]`. `header` rows, when given, lead
+ * the column.
+ */
+export function composeOutlineColumn(
+	childRows: readonly (readonly string[])[],
+	from: number,
+	to: number,
+	targets: readonly OutlineTarget[],
+	selected: number,
+	columnWidth: number,
+	header: string[] | undefined,
+	style: OutlineStyle = {},
+): ComposedColumn {
+	const inner = Math.max(10, columnWidth - 4);
+	const lines: string[] = header ? [...header] : [];
+	let selStart = -1;
+	let selEnd = -1;
+	const target = selected >= 0 ? targets[selected] : undefined;
+	for (let index = from; index < to; index++) {
+		if (target && index === target.start && target.end <= to) {
+			const segment: string[] = [];
+			for (let child = target.start; child < target.end; child++) segment.push(...childRows[child]!);
+			// Outline only the non-blank core; edge spacers stay outside.
+			let head = 0;
+			let tail = segment.length;
+			while (head < tail && !/\S/.test(segment[head]!)) head++;
+			while (tail > head && !/\S/.test(segment[tail - 1]!)) tail--;
+			for (let row = 0; row < head; row++) lines.push("");
+			selStart = lines.length;
+			lines.push(...outlineRows(segment.slice(head, tail), inner, style));
+			selEnd = lines.length;
+			for (let row = tail; row < segment.length; row++) lines.push("");
+			index = target.end - 1;
+			continue;
+		}
+		for (const row of childRows[index]!) lines.push(row ? `  ${row}` : row);
+	}
+	return { lines, selStart, selEnd };
+}
+
+/** Centered position rail for horizontally windowed content: `… ○ ◉ ○ …`. */
+export function positionRail(
+	count: number,
+	active: number,
+	moreLeft: boolean,
+	moreRight: boolean,
+	width: number,
+): string {
+	const dots: string[] = [];
+	for (let index = 0; index < count; index++) {
+		dots.push(index === active ? theme.fg("accent", theme.radio.selected) : theme.fg("dim", theme.radio.unselected));
+	}
+	const rail = `${moreLeft ? theme.fg("dim", "… ") : "  "}${dots.join(" ")}${moreRight ? theme.fg("dim", " …") : ""}`;
+	const pad = Math.max(0, Math.floor((width - visibleWidth(rail)) / 2));
+	return " ".repeat(pad) + rail;
+}
+
+/**
+ * A turn the user can rewind past and re-edit: a user message with prompt
+ * text, or a user-initiated custom message (skill / collab prompt).
+ */
+export function isUserTurnEntry(entry: TranscriptEntry): boolean {
+	if (entry.type === "message" && entry.message.role === "user") return userMessageHasText(entry.message);
+	return isUserRequestEntry(entry);
+}
+
+/** Single-line label for a user turn: its prompt text, or the custom message's draft. */
+export function userTurnLabel(entry: TranscriptEntry): string | undefined {
+	if (entry.type === "message" && entry.message.role === "user") return userMessageLabel(entry.message.content);
+	const draft = userTurnDraft(entry);
+	return draft === undefined ? undefined : userMessageLabel(draft);
+}
+
+/** Whether a user message carries prompt text (string or text blocks). */
+export function userMessageHasText(message: SessionMessageEntry["message"]): boolean {
+	if (message.role !== "user") return false;
+	if (typeof message.content === "string") return message.content.trim().length > 0;
+	return message.content.some(block => block.type === "text" && block.text.trim().length > 0);
+}