pi-compact-tools 0.9.2 → 0.10.0

package/extensions/compact-tools-silent.ts

@@ -0,0 +1,334 @@
+import {
+	AssistantMessageComponent,
+	CustomMessageComponent,
+	DynamicBorder,
+	ToolExecutionComponent,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Markdown, MouseRegion, Spacer, Text } from "@earendil-works/pi-tui";
+import { hookMethod } from "./compact-tools-hook.ts";
+import type { DisplayMode } from "./compact-tools-types.ts";
+import { captureViewport } from "./compact-tools-viewport.ts";
+import { SilentActivityAnimator } from "./compact-tools-activity.ts";
+
+const STATUS_KEY = "compact-tools";
+const WIDGET_KEY = "compact-tools-silent";
+const COMMAND_ARGUMENTS = ["on", "off"] as const;
+export const SILENT_SHORTCUT = "ctrl+'";
+// Symbol.for keys resolve to the same symbol in every evaluation of this module.
+// /reload re-evaluates the module, but the patched prototypes belong to Pi and
+// outlive it, so the flag they read and the patch marker must be shared.
+const STATE_KEY = Symbol.for("pi-compact-tools.silent.state");
+// Versioned: an instance loaded before thinking was hidden may already have
+// wrapped these prototypes in the running process. A new key wraps once more
+// rather than silently keeping the older behavior until Pi restarts.
+const ORIGINAL_RENDER = Symbol.for("pi-compact-tools.silent.originalRender.v2");
+const OVERRIDES_KEY = Symbol.for("pi-compact-tools.silent.overrides.v2");
+
+interface SilentState {
+	active: boolean;
+	enabled: boolean;
+	/** Set by /silent so that a /reload keeps the user's choice over the configured mode. */
+	overridden: boolean;
+}
+
+type Renderable = { render(width: number): string[] };
+type Render = (width: number) => string[];
+export type RenderOverride = (component: any, width: number, render: Render) => string[];
+
+type AssistantLike = {
+	hasToolCalls?: unknown;
+	contentContainer?: { children?: unknown[] };
+};
+
+interface RenderOverrides {
+	tool: RenderOverride;
+	assistant: RenderOverride;
+	notice: RenderOverride;
+}
+
+function sharedState(): SilentState {
+	const holder = globalThis as typeof globalThis & { [STATE_KEY]?: SilentState };
+	holder[STATE_KEY] ??= { active: false, enabled: false, overridden: false };
+	return holder[STATE_KEY];
+}
+
+/**
+ * Pi's own pi-tui classes. Inside Pi an extension imports the same copy Pi uses;
+ * an install with a second copy (a development checkout, for one) still builds
+ * the same classes, so a matching name identifies them there.
+ */
+function isKind(child: unknown, kind: abstract new (...args: any[]) => unknown): boolean {
+	return child instanceof kind
+		|| (typeof child === "object" && child !== null && child.constructor?.name === kind.name);
+}
+
+/** Whether silent mode is currently hiding the transcript's tool rows. */
+export function isSilent(): boolean {
+	const state = sharedState();
+	return state.active && state.enabled;
+}
+
+/** A turn that hands off to tools is progress, not an answer, however it ended. */
+export function isIntermediateAssistant(component: AssistantLike): boolean {
+	return component.hasToolCalls === true;
+}
+
+/**
+ * Render only an assistant turn's answer text. Pi builds a turn from three kinds
+ * of children: each thinking run, shown or collapsed to its label, is a
+ * MouseRegion followed by a spacer; the answer is Markdown; and an error, abort,
+ * or truncation notice is a spacer followed by a plain Text. The children are
+ * swapped only for this one render, so the component and its message stay
+ * untouched and reappear in full once silent mode is off.
+ */
+export function renderAnswerOnly(component: AssistantLike, width: number, render: Render): string[] {
+	const container = component.contentContainer;
+	const children = container?.children;
+	if (!container || !Array.isArray(children)) return render(width);
+	// Most renders have nothing to drop; skip building a filtered copy for them.
+	if (!children.some((child) => isKind(child, MouseRegion) || isKind(child, Text))) return render(width);
+	const kept: unknown[] = [];
+	let afterThinking = false;
+	for (const child of children) {
+		if (isKind(child, MouseRegion)) {
+			afterThinking = true;
+			continue;
+		}
+		if (afterThinking && isKind(child, Spacer)) {
+			afterThinking = false;
+			continue;
+		}
+		afterThinking = false;
+		if (isKind(child, Text)) {
+			if (isKind(kept.at(-1), Spacer)) kept.pop();
+			continue;
+		}
+		kept.push(child);
+	}
+	if (kept.length === children.length) return render(width);
+	// A turn that was only thinking would otherwise leave its leading blank line.
+	if (kept.every((child) => isKind(child, Spacer))) return [];
+	container.children = kept;
+	try {
+		return render(width);
+	} finally {
+		container.children = children;
+	}
+}
+
+/**
+ * A row Pi (or this extension) adds to the chat directly rather than as a message:
+ * status lines are Text, and "What's New" blocks add borders and Markdown too.
+ */
+function isNotice(child: unknown): boolean {
+	return isKind(child, Text) || isKind(child, DynamicBorder) || isKind(child, Markdown);
+}
+
+/**
+ * Render a transcript container without Pi's own notices. Pi writes warnings,
+ * errors, and status lines ("Reloaded …", "Wait for the current response …")
+ * straight into the chat as a spacer followed by a plain Text, while every
+ * message has a component of its own. Dropping top-level Text rows and the
+ * spacer before each leaves the conversation itself untouched.
+ */
+export function renderWithoutNotices(container: { children?: unknown[] }, width: number, render: Render): string[] {
+	const children = container.children;
+	if (!Array.isArray(children) || !children.some(isNotice)) return render(width);
+	const kept: unknown[] = [];
+	for (const child of children) {
+		if (isNotice(child)) {
+			if (isKind(kept.at(-1), Spacer)) kept.pop();
+			continue;
+		}
+		kept.push(child);
+	}
+	if (kept.length === children.length) return render(width);
+	container.children = kept;
+	try {
+		return render(width);
+	} finally {
+		container.children = children;
+	}
+}
+
+type TuiLike = { children?: Array<{ children?: unknown[] }> };
+
+/**
+ * Pi mounts the transcript document first in both regular and fullscreen mode, and
+ * its chat is the document's last child, after the header and resource list.
+ */
+function hookChatNotices(tui: unknown): void {
+	const documentChildren = (tui as TuiLike).children?.[0]?.children;
+	const chat = Array.isArray(documentChildren) ? documentChildren.at(-1) : undefined;
+	if (typeof chat !== "object" || chat === null || !Array.isArray((chat as { children?: unknown }).children)) return;
+	hookMethod(chat, "render", "silent.chatNotices", (self, args, original) => {
+		const state = sharedState();
+		if (!state.active || !state.enabled) return original.apply(self, args);
+		return renderWithoutNotices(self, args[0], (width) => original.call(self, width));
+	});
+}
+
+/**
+ * Pi exposes no API to hide another extension's tool rows, so silent mode wraps
+ * the shared component prototypes. Returns false when the host no longer has the
+ * expected shape, which leaves the transcript untouched.
+ */
+export function patchRender(
+	prototype: Renderable | undefined,
+	override: RenderOverride,
+	/** When this returns false the original render runs directly, with no override and no allocation. */
+	engaged: () => boolean = () => true,
+): boolean {
+	if (!prototype || typeof prototype.render !== "function") return false;
+	// Checked as an own property: a component that inherits render() from a shared
+	// base (CustomMessageComponent uses Container's) must still get its own wrapper.
+	if (Object.hasOwn(prototype, ORIGINAL_RENDER)) return true;
+	const original = prototype.render;
+	prototype.render = function (this: unknown, width: number): string[] {
+		if (!engaged()) return original.call(this, width);
+		return override(this, width, (nextWidth) => original.call(this, nextWidth));
+	};
+	Object.defineProperty(prototype, ORIGINAL_RENDER, { value: original });
+	return true;
+}
+
+function sharedOverrides(): RenderOverrides | undefined {
+	return (globalThis as typeof globalThis & { [OVERRIDES_KEY]?: RenderOverrides })[OVERRIDES_KEY];
+}
+
+function publishOverrides(): void {
+	const state = sharedState();
+	const silent = () => state.active && state.enabled;
+	(globalThis as typeof globalThis & { [OVERRIDES_KEY]?: RenderOverrides })[OVERRIDES_KEY] = {
+		tool: (_component, width, render) => silent() ? [] : render(width),
+		// Only the prompt and the answer remain: intermediate turns go entirely, and
+		// the final turn keeps its text but not its thinking or any stop notice.
+		assistant: (component: AssistantLike, width, render) => {
+			if (!silent()) return render(width);
+			return isIntermediateAssistant(component) ? [] : renderAnswerOnly(component, width, render);
+		},
+		// Extension notices such as pi-web-access's "content ready" arrive between
+		// tool calls; they are progress, not answers.
+		notice: (_component, width, render) => silent() ? [] : render(width),
+	};
+}
+
+// The patched prototypes look behavior up here on every render, so after a
+// /reload they follow the newly loaded module instead of the one that patched them.
+function delegate(key: keyof RenderOverrides): RenderOverride {
+	return (component, width, render) => {
+		const override = sharedOverrides()?.[key];
+		return override ? override(component, width, render) : render(width);
+	};
+}
+
+export function parseSilentArgument(args: string, current: boolean): boolean | undefined {
+	const argument = args.trim().toLowerCase();
+	if (argument === "") return !current;
+	if (argument === "on") return true;
+	if (argument === "off") return false;
+	return undefined;
+}
+
+function installPatches(): boolean {
+	publishOverrides();
+	// Every patch is checked before any is relied on, so a partial host change
+	// cannot leave tool rows hidden while their surrounding turns remain visible.
+	// Normal mode pays one flag check per render and nothing else.
+	const tools = patchRender(ToolExecutionComponent?.prototype, delegate("tool"), isSilent);
+	const assistant = patchRender(AssistantMessageComponent?.prototype, delegate("assistant"), isSilent);
+	const notices = patchRender(CustomMessageComponent?.prototype, delegate("notice"), isSilent);
+	return tools && assistant && notices;
+}
+
+/** Hides tool rows, intermediate assistant turns, thinking, and extension notices; the working label carries progress instead. */
+export class SilentModeController {
+	private context: ExtensionContext | undefined;
+	private readonly activity: SilentActivityAnimator;
+
+	constructor(pi: ExtensionAPI, private readonly onVisible?: (ctx: ExtensionContext) => void) {
+		this.activity = new SilentActivityAnimator(pi);
+		pi.registerCommand("silent", {
+			description: `(${SILENT_SHORTCUT}) Show only prompts and final answers`,
+			getArgumentCompletions: (prefix) => {
+				const items = COMMAND_ARGUMENTS
+					.filter((value) => value.startsWith(prefix.trim().toLowerCase()))
+					.map((value) => ({ value, label: value }));
+				return items.length > 0 ? items : null;
+			},
+			handler: async (args, ctx) => {
+				const state = sharedState();
+				const enabled = parseSilentArgument(args, state.enabled);
+				if (enabled === undefined) {
+					ctx.ui.notify("Usage: /silent [on|off]", "warning");
+					return;
+				}
+				this.choose(enabled);
+			},
+		});
+		pi.registerShortcut(SILENT_SHORTCUT, {
+			description: "Toggle silent mode",
+			handler: () => this.choose(!sharedState().enabled),
+		});
+	}
+
+	/** A choice made in the session, which a /reload keeps over the configured mode. */
+	private choose(enabled: boolean): void {
+		sharedState().overridden = true;
+		// No notification: Pi writes notices into the transcript, which is exactly
+		// what silent mode keeps clean.
+		this.apply(enabled);
+		if (!sharedState().enabled && this.context) this.onVisible?.(this.context);
+	}
+
+	isEnabled(): boolean {
+		return sharedState().enabled;
+	}
+
+	bind(ctx: ExtensionContext, mode: DisplayMode, reload: boolean): void {
+		this.context = ctx;
+		this.activity.bind(ctx);
+		// An invisible widget is the extension API's way to reach Pi's TUI, and
+		// through it the chat container whose notices silent mode hides.
+		ctx.ui.setWidget(WIDGET_KEY, (tui) => {
+			hookChatNotices(tui);
+			return { render: () => [], invalidate() {} };
+		}, { placement: "belowEditor" });
+		const state = sharedState();
+		if (!reload) state.overridden = false;
+		this.apply(state.overridden ? state.enabled : mode === "silent");
+	}
+
+	dispose(): void {
+		this.activity.dispose();
+		// A patched Pi prototype outlives this extension instance. Disable hiding
+		// while no instance is bound, but keep the choice for a subsequent /reload.
+		sharedState().active = false;
+		this.context?.ui.setStatus(STATUS_KEY, undefined);
+		this.context?.ui.setWidget(WIDGET_KEY, undefined, { placement: "belowEditor" });
+		this.context = undefined;
+	}
+
+	private apply(enabled: boolean): boolean {
+		const state = sharedState();
+		if (enabled && !installPatches()) {
+			state.active = false;
+			state.enabled = false;
+			this.activity.setEnabled(false);
+			this.context?.ui.notify("Silent mode is unavailable in this version of Pi", "warning");
+			return false;
+		}
+		// Hiding or revealing rows above the reader would otherwise move the view.
+		if (enabled !== state.enabled) captureViewport();
+		state.enabled = enabled;
+		this.activity.setEnabled(enabled);
+		state.active = this.context !== undefined;
+		// Silent mode shows no indicator of its own; the transcript itself is the cue.
+		// Clearing the status still requests a render, which is what reveals or hides
+		// rows already in the transcript, and removes the label older versions left.
+		this.context?.ui.setStatus(STATUS_KEY, undefined);
+		return true;
+	}
+}

package/extensions/compact-tools-thinking.ts

@@ -7,7 +7,6 @@ import {
 	Key,
 	matchesKey,
 	stripTerminalSequences,
-	truncateToWidth,
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
 import { chromePainter } from "./compact-tools-palette.ts";
@@ -156,16 +155,17 @@ function renderThinkingSections(
 	const styleControlPrefix = options.styleControlPrefix ?? ((prefix: string) => prefix);
 	return sections
 		.map(({ summary, detail }, sectionIndex) => {
-			const fittedSummary = stripTerminalSequences(
-				truncateToWidth(summary, Math.max(1, availableWidth), "…"),
-			);
-			const title = options.styleSummary?.(fittedSummary, sectionIndex) ?? fittedSummary;
+			// The summary is never cut short: a provider that sends one unstructured
+			// paragraph has no detail to expand into, so the summary is all there is.
+			// The host's Markdown component wraps it to the available width.
+			const plain = stripTerminalSequences(summary);
+			const title = options.styleSummary?.(plain, sectionIndex) ?? plain;
 			const sectionControls = view === "detail"
 				? typeof controls === "function" ? controls(detail.length > 0) : controls
 				: undefined;
 			const controlLines = sectionControls
-				? wrapTextWithAnsi(sectionControls, Math.max(1, availableWidth - 3)).map(
-						(line, index) => `${index === 0 ? styleControlPrefix("└─ ") : "   "}${line}`,
+				? wrapTextWithAnsi(sectionControls, Math.max(1, availableWidth - 2)).map(
+						(line, index) => `${index === 0 ? styleControlPrefix("└ ") : "  "}${line}`,
 					)
 				: [];
 			if (view === "detail" && detail) {

package/extensions/compact-tools-types.ts

@@ -8,9 +8,22 @@ export type ShellToolName = "bash" | "powershell";
 export type ToolArgs = Record<string, unknown>;
 export type BuiltInDefinition = ToolDefinition<any, any, any>;
 
+export const DISPLAY_MODES = ["normal", "silent"] as const;
+export type DisplayMode = (typeof DISPLAY_MODES)[number];
+
+export interface CustomToolsConfig {
+	/** Render tools registered by other extensions compactly as well. */
+	enabled: boolean;
+	auto_compact: boolean;
+	exclude: string[];
+}
+
 export interface CompactToolsConfig {
+	mode: DisplayMode;
 	tools: CompactToolName[];
-	auto_compact: Record<CompactToolName, boolean>;
+	/** Built-ins always have an entry; custom tools may, and otherwise use custom_tools.auto_compact. */
+	auto_compact: Record<CompactToolName, boolean> & { [tool: string]: boolean | undefined };
+	custom_tools: CustomToolsConfig;
 	previewLines: number;
 }
 

package/extensions/compact-tools-viewport.ts

@@ -0,0 +1,234 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getKeybindings, isKeyRelease, isKeyRepeat, matchesKey, stripTerminalSequences, TuiAltScreen, type TUI } from "@earendil-works/pi-tui";
+import { hookMethod } from "./compact-tools-hook.ts";
+
+const WIDGET_KEY = "compact-tools-viewport";
+// Shared through globalThis: the TUI outlives a /reload of this module, so the
+// render wrapper installed on it must reach whichever instance is loaded now.
+const STATE_KEY = Symbol.for("pi-compact-tools.viewport.state");
+/** Consecutive lines matched together, so a lone repeated line cannot anchor the view. */
+const ANCHOR_LINES = 2;
+/** How far past the anchor to compare when a short window matches in several places. */
+const TIE_BREAK_LINES = 200;
+/** Pi keybindings that change the height of rows throughout the transcript, with Pi's defaults. */
+const RELAYOUT_BINDINGS = { "app.tools.expand": "ctrl+o", "app.thinking.toggle": "ctrl+t" } as const;
+
+interface ScrollViewLike {
+	readonly scrollTop: number;
+	readonly isFollowingEnd: boolean;
+	readonly viewportHeight: number;
+	child?: { render(width: number): string[] };
+	getContentWidth?(width: number): number;
+	updateLayout?(contentHeight: number, viewportHeight: number, requestRender?: () => void): void;
+	requestRenderCallback?: () => void;
+	scrollTo(scrollTop: number, options?: { disableFollow?: boolean }): void;
+}
+
+interface LayoutBox {
+	scrollView?: unknown;
+	scrollContentLines?: string[];
+	rect?: { width: number };
+	children?: LayoutBox[];
+}
+
+interface TuiLike {
+	currentLayout?: { root?: LayoutBox };
+	terminal?: { columns?: number };
+	getPrimaryScrollView?(): ScrollViewLike | undefined;
+	doRender?(...args: unknown[]): unknown;
+}
+
+interface Snapshot {
+	scrollView: ScrollViewLike;
+	columns: number | undefined;
+	width: number;
+	lines: string[];
+	top: number;
+	height: number;
+}
+
+interface ViewportState {
+	tui?: TuiLike;
+	pending?: Snapshot;
+	restore?: (tui: TuiLike) => void;
+}
+
+function sharedState(): ViewportState {
+	const holder = globalThis as typeof globalThis & { [STATE_KEY]?: ViewportState };
+	holder[STATE_KEY] ??= {};
+	return holder[STATE_KEY];
+}
+
+function hasText(line: string | undefined): boolean {
+	return line !== undefined && stripTerminalSequences(line).trim().length > 0;
+}
+
+/** How many lines from `row` in `before` continue unchanged from `start` in `after`. */
+function matchingRun(before: readonly string[], row: number, after: readonly string[], start: number, limit: number): number {
+	let length = 0;
+	while (length < limit && row + length < before.length && before[row + length] === after[start + length]) length++;
+	return length;
+}
+
+/**
+ * Where to scroll so the text the reader was looking at stays on the same screen
+ * row after rows above it grew or shrank. Lines on screen are tried top first,
+ * then lines above the viewport, so a row that disappeared hands over to the
+ * nearest text that survived. Returns undefined when nothing survived.
+ */
+export function findAnchorTop(
+	before: readonly string[],
+	top: number,
+	height: number,
+	after: readonly string[],
+): number | undefined {
+	const starts = new Map<string, number[]>();
+	after.forEach((line, index) => {
+		const list = starts.get(line);
+		if (list) list.push(index);
+		else starts.set(line, [index]);
+	});
+	const bottom = Math.min(before.length, top + Math.max(1, height));
+	const candidates: number[] = [];
+	for (let row = top; row < bottom; row++) candidates.push(row);
+	for (let row = top - 1; row >= 0; row--) candidates.push(row);
+	for (const row of candidates) {
+		const window = before.slice(row, row + ANCHOR_LINES);
+		if (window.length < ANCHOR_LINES || !window.some(hasText)) continue;
+		// Several places can match a short window; the one that keeps matching for
+		// longest is the same text, and distance only breaks a remaining tie.
+		let best: number | undefined;
+		let bestRun = 0;
+		for (const start of starts.get(window[0]!) ?? []) {
+			const run = matchingRun(before, row, after, start, TIE_BREAK_LINES);
+			if (run < ANCHOR_LINES) continue;
+			if (best === undefined || run > bestRun
+				|| (run === bestRun && Math.abs(start - row) < Math.abs(best - row))) {
+				best = start;
+				bestRun = run;
+			}
+		}
+		if (best !== undefined) return Math.max(0, best - (row - top));
+	}
+	return undefined;
+}
+
+function findScrollBox(box: LayoutBox | undefined, scrollView: ScrollViewLike): LayoutBox | undefined {
+	if (!box) return undefined;
+	if (box.scrollView === scrollView) return box;
+	for (const child of box.children ?? []) {
+		const match = findScrollBox(child, scrollView);
+		if (match) return match;
+	}
+	return undefined;
+}
+
+/**
+ * Remember what the transcript shows right now, before a change that resizes rows
+ * throughout it. The next frame scrolls so the same text stays in place. Pi's
+ * fullscreen viewport keeps its offset from the top, so without this, expanding
+ * rows above the reader pushes what they were reading out of view.
+ */
+export function captureViewport(): void {
+	const state = sharedState();
+	state.pending = undefined;
+	const tui = state.tui;
+	const scrollView = tui?.getPrimaryScrollView?.();
+	// Following the end already keeps the newest output in view.
+	if (!tui || !scrollView || scrollView.isFollowingEnd) return;
+	const box = findScrollBox(tui.currentLayout?.root, scrollView);
+	if (!box?.scrollContentLines || !box.rect) return;
+	state.pending = {
+		scrollView,
+		columns: tui.terminal?.columns,
+		width: scrollView.getContentWidth?.(box.rect.width) ?? box.rect.width,
+		lines: box.scrollContentLines.slice(),
+		top: scrollView.scrollTop,
+		height: scrollView.viewportHeight,
+	};
+}
+
+function restoreViewport(tui: TuiLike): void {
+	const state = sharedState();
+	const pending = state.pending;
+	state.pending = undefined;
+	if (!pending || pending.columns !== tui.terminal?.columns) return;
+	const scrollView = pending.scrollView;
+	if (scrollView !== tui.getPrimaryScrollView?.() || scrollView.isFollowingEnd || !scrollView.child) return;
+	// A relayout leaves scrollTop alone. If it moved, the reader scrolled since the
+	// snapshot, and restoring would undo that.
+	if (scrollView.scrollTop !== pending.top) return;
+	const after = scrollView.child.render(pending.width);
+	const top = findAnchorTop(pending.lines, pending.top, pending.height, after);
+	if (top === undefined || top === scrollView.scrollTop) return;
+	// scrollTo clamps against the previous frame's height; publish the new height first.
+	scrollView.updateLayout?.(after.length, scrollView.viewportHeight, scrollView.requestRenderCallback);
+	scrollView.scrollTo(top, { disableFollow: true });
+}
+
+/**
+ * Run the pending restore just before Pi lays out a fullscreen frame, so no frame
+ * shows the jump. The hook sits on the fullscreen renderer's class rather than on
+ * an instance: extensions only ever see a proxy to the current renderer, and a
+ * switch to fullscreen in /settings creates a new one.
+ */
+function hookFullscreenRender(): void {
+	const prototype = (TuiAltScreen as unknown as { prototype?: object } | undefined)?.prototype;
+	if (!prototype) return;
+	hookMethod(prototype, "doRender", "viewport.doRender", (self: TuiLike, args, original) => {
+		if (sharedState().pending) {
+			try {
+				restoreViewport(self);
+			} catch {
+				// Keeping the position is a nicety; never let it block a frame.
+			}
+		}
+		return original.apply(self, args);
+	});
+}
+
+function isRelayoutKey(data: string): boolean {
+	// Kitty terminals also report releases and repeats; only the press relays out.
+	if (isKeyRelease(data) || isKeyRepeat(data)) return false;
+	const keybindings = getKeybindings();
+	return Object.entries(RELAYOUT_BINDINGS).some(([binding, fallback]) =>
+		// A host that never registered Pi's app bindings still uses the defaults.
+		keybindings.getKeys(binding as never).length > 0
+			? keybindings.matches(data, binding as never)
+			: matchesKey(data, fallback));
+}
+
+/** Keeps the reader's place when expand, collapse, thinking, or silent mode resize the transcript. */
+export class ViewportKeeper {
+	private context: ExtensionContext | undefined;
+	private unsubscribe: (() => void) | undefined;
+
+	bind(ctx: ExtensionContext): void {
+		this.dispose();
+		this.context = ctx;
+		hookFullscreenRender();
+		// Earlier versions wrapped a renderer instance directly and call this slot;
+		// pointing it at the current restore keeps those in step until Pi restarts.
+		sharedState().restore = restoreViewport;
+		// An invisible widget is the extension API's way to reach Pi's TUI.
+		ctx.ui.setWidget(WIDGET_KEY, (tui: TUI) => {
+			sharedState().tui = tui as unknown as TuiLike;
+			return { render: () => [], invalidate() {} };
+		}, { placement: "belowEditor" });
+		this.unsubscribe = ctx.ui.onTerminalInput((data) => {
+			if (isRelayoutKey(data)) captureViewport();
+			// Observe only: Pi and the thinking controller still handle the key.
+			return undefined;
+		});
+	}
+
+	dispose(): void {
+		this.unsubscribe?.();
+		this.unsubscribe = undefined;
+		const state = sharedState();
+		state.pending = undefined;
+		state.tui = undefined;
+		this.context?.ui.setWidget(WIDGET_KEY, undefined, { placement: "belowEditor" });
+		this.context = undefined;
+	}
+}