@sayknow-cli/coding-agent 0.3.16 → 0.4.0

package/src/modes/components/pet-capability.ts

@@ -0,0 +1,115 @@
+import {
+	ImageProtocol,
+	isUnderTerminalMultiplexer,
+	onImageProtocolChanged,
+	type SelectItem,
+	shouldProbeSixelCapability,
+	TERMINAL,
+} from "@sayknow-cli/tui";
+
+export type PetPixelProtocol = "sixel" | "kitty";
+
+export const PET_UNAVAILABLE_DESCRIPTION = "Unavailable: requires compatible Kitty or Sixel overlay rendering";
+export const PET_SAVED_UNAVAILABLE_DESCRIPTION =
+	"Saved, unavailable — requires compatible Kitty or Sixel overlay rendering";
+export const PET_UNAVAILABLE_WARNING =
+	"⚠ Pets aren’t available in this terminal. Its image support isn’t compatible with Sayknow Pet’s overlay rendering yet. Try Kitty, Ghostty, WezTerm, or a terminal with compatible Sixel support.";
+const PET_MULTIPLEXER_UNAVAILABLE_WARNING =
+	"⚠ Sayknow Pet graphics are unavailable inside tmux, screen, or zellij because image escapes are not forwarded end to end. Run skc outside the multiplexer, or set PI_FORCE_IMAGE_PROTOCOL=sixel only when the full terminal chain supports Sixel.";
+
+export function getPetUnavailableWarning(env: NodeJS.ProcessEnv = Bun.env): string {
+	return isUnderTerminalMultiplexer(env) ? PET_MULTIPLEXER_UNAVAILABLE_WARNING : PET_UNAVAILABLE_WARNING;
+}
+
+export function getPetPixelProtocol(): PetPixelProtocol | null {
+	if (TERMINAL.imageProtocol === ImageProtocol.Kitty) return "kitty";
+	if (TERMINAL.imageProtocol === ImageProtocol.Sixel) return "sixel";
+	return null;
+}
+
+export function isPetAvailable(): boolean {
+	return getPetPixelProtocol() !== null;
+}
+
+export function createPetSelectItems(
+	options: ReadonlyArray<SelectItem>,
+	currentValue: string,
+	available: boolean,
+): SelectItem[] {
+	return options.map(option => {
+		const disabled = !available && option.value !== "off";
+		const current = option.value === currentValue;
+		const savedUnavailable = disabled && current;
+		let description = `${option.description ?? ""}${current ? " (current)" : ""}`;
+		if (disabled) {
+			description = savedUnavailable ? PET_SAVED_UNAVAILABLE_DESCRIPTION : PET_UNAVAILABLE_DESCRIPTION;
+		}
+		return {
+			...option,
+			label: savedUnavailable ? `${option.label} (saved)` : option.label,
+			description,
+			disabled,
+		};
+	});
+}
+
+/**
+ * Grace period before declaring the terminal pet-incapable at startup. The
+ * asynchronous Sixel capability probe starts inside `TUI.start()` and answers
+ * within its own 250 ms deadline; this margin covers probe scheduling so a
+ * supported terminal is never told it is incompatible while the probe is
+ * still in flight.
+ */
+export const PET_CAPABILITY_SETTLE_MS = 1_000;
+
+/**
+ * Whether the asynchronous startup Sixel capability probe may still enable
+ * graphics for this session, meaning current unavailability is not final.
+ */
+export function isPetCapabilityProbePending(
+	env: NodeJS.ProcessEnv = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	if (TERMINAL.imageProtocol !== null) return false;
+	if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+	return shouldProbeSixelCapability(env, platform);
+}
+
+/**
+ * Deliver the pet-unavailable startup warning only once the capability
+ * question is settled. With no probe pending, unavailability is final and
+ * `onUnavailable` fires immediately. While a probe may still enable
+ * graphics, the warning is deferred: a protocol-change event cancels it (the
+ * saved pet re-applies through the existing subscription), and only the
+ * settle deadline passing with the terminal still unavailable emits it.
+ * Returns a disposer that cancels the pending decision.
+ */
+export function warnWhenPetCapabilitySettled(options: {
+	probePending: boolean;
+	isAvailable?: () => boolean;
+	onUnavailable: () => void;
+	settleMs?: number;
+}): () => void {
+	if (!options.probePending) {
+		options.onUnavailable();
+		return () => {};
+	}
+	const isAvailable = options.isAvailable ?? isPetAvailable;
+	let settled = false;
+	const finish = () => {
+		if (settled) return;
+		settled = true;
+		clearTimeout(timer);
+		unsubscribe();
+	};
+	const unsubscribe = onImageProtocolChanged(protocol => {
+		if (!protocol) return;
+		finish();
+	});
+	const timer = setTimeout(() => {
+		finish();
+		if (!isAvailable()) options.onUnavailable();
+	}, options.settleMs ?? PET_CAPABILITY_SETTLE_MS);
+	timer.unref?.();
+	return finish;
+}

package/src/modes/components/pet-selector.ts

@@ -1,6 +1,6 @@
-import { Container, PET_SKIN_IDS, PET_SKINS, type SelectItem, SelectList } from "@sayknow-cli/tui";
-import { getSelectListTheme } from "../theme/theme";
-import { DynamicBorder } from "./dynamic-border";
+import { Container, PET_SKIN_IDS, PET_SKINS, type SelectList } from "@sayknow-cli/tui";
+import { FramedSelect } from "./chrome";
+import { createPetSelectItems } from "./pet-capability";
 import type { PetMode } from "./sayknow-pet-widget";
 
 const PET_OPTIONS: { value: PetMode; label: string; description: string }[] = [
@@ -24,29 +24,21 @@ export class PetSelectorComponent extends Container {
 		onSelect: (mode: PetMode) => void,
 		onCancel: () => void,
 		onPreview: (mode: PetMode) => void,
+		available: boolean,
 	) {
 		super();
 
-		const items: SelectItem[] = PET_OPTIONS.map(option => ({
-			value: option.value,
-			label: option.label,
-			description: option.value === current ? `${option.description} (current)` : option.description,
-		}));
-
-		this.addChild(new DynamicBorder());
-
-		this.#selectList = new SelectList(items, 10, getSelectListTheme());
-		const currentIndex = PET_OPTIONS.findIndex(option => option.value === current);
-		if (currentIndex !== -1) {
-			this.#selectList.setSelectedIndex(currentIndex);
-		}
-
-		this.#selectList.onSelect = item => onSelect(item.value as PetMode);
-		this.#selectList.onCancel = () => onCancel();
-		this.#selectList.onSelectionChange = item => onPreview(item.value as PetMode);
-
-		this.addChild(this.#selectList);
-		this.addChild(new DynamicBorder());
+		const items = createPetSelectItems(PET_OPTIONS, current, available);
+
+		const framed = FramedSelect(undefined, items, {
+			maxVisible: 10,
+			selectedValue: current,
+			onSelect: item => onSelect(item.value as PetMode),
+			onCancel,
+			onSelectionChange: item => onPreview(item.value as PetMode),
+		});
+		this.#selectList = framed.selectList;
+		this.addChild(framed.container);
 	}
 
 	getSelectList(): SelectList {

package/src/modes/components/plan-preview-overlay.ts

@@ -0,0 +1,295 @@
+import { createHash } from "node:crypto";
+import { Container, Input, type KeyId, type MouseEvent, matchesKey, truncateToWidth } from "@sayknow-cli/tui";
+
+import { theme } from "../theme/theme";
+import { DynamicBorder } from "./dynamic-border";
+
+export const PLAN_REVIEW_ACTIONS = [
+	"Approve and execute",
+	"Approve and compact context",
+	"Approve and keep context",
+	"Refine plan",
+] as const;
+export type PlanReviewAction = (typeof PLAN_REVIEW_ACTIONS)[number];
+export type PlanPreviewFocus = "preview" | "sourceSelect" | "commentInput" | "actionBar";
+export interface PlanPreviewOptions {
+	externalEditorKey?: string;
+	externalEditorKeys?: readonly KeyId[];
+	onExternalEditor?: () => Promise<string | null>;
+}
+
+export interface PlanComment {
+	id: string;
+	startLine: number;
+	endLine: number;
+	text: string;
+	snapshotHash: string;
+	createdAt: number;
+}
+export interface PlanPreviewResult {
+	action?: PlanReviewAction;
+	comments: PlanComment[];
+	notes: string;
+	snapshotHash: string;
+}
+
+export function planSnapshotHash(content: string): string {
+	return createHash("sha256").update(content).digest("hex");
+}
+export function serializePlanReviewComments(
+	content: string,
+	hash: string,
+	comments: readonly PlanComment[],
+	notes = "",
+): string {
+	const lines = content.split("\n").map(line => line.replace(/\r$/, ""));
+	const valid = comments.filter(
+		comment =>
+			comment.snapshotHash === hash &&
+			comment.text.trim() &&
+			Number.isInteger(comment.startLine) &&
+			Number.isInteger(comment.endLine) &&
+			comment.startLine >= 1 &&
+			comment.endLine >= comment.startLine &&
+			comment.startLine <= lines.length,
+	);
+	if (!valid.length && !notes.trim()) return "";
+	const block = [`Plan review comments (snapshot ${hash.slice(0, 8)}):`];
+	for (const comment of valid) {
+		const end = Math.min(lines.length, Math.max(comment.startLine, comment.endLine));
+		block.push(`- L${comment.startLine}${end === comment.startLine ? "" : `-L${end}`}: ${comment.text.trim()}`);
+		for (let line = comment.startLine; line <= Math.min(end, comment.startLine + 5); line++)
+			block.push(`> ${lines[line - 1]}`);
+	}
+	if (notes.trim()) block.push(notes.trim());
+	return block.join("\n");
+}
+
+/** Modal pre-decision review. Its result is consumed by InteractiveMode, which owns audit and dispatch semantics. */
+export class PlanPreviewOverlay extends Container {
+	#focus: PlanPreviewFocus = "preview";
+	#scroll = 0;
+	#sourceLine = 1;
+	#actionIndex = 0;
+	#comments: PlanComment[] = [];
+	#notes = "";
+	#input = new Input();
+	#inputKind: "comment" | "notes" = "comment";
+	#renderedSourceLines: number[] = [];
+	#renderedBody: string[] = [];
+	#renderedBodyWidth = 0;
+	content: string | null;
+
+	snapshotHash: string;
+	lines: string[];
+	constructor(
+		content: string | null,
+		private readonly done: (result: PlanPreviewResult) => void,
+		private readonly requestRender: () => void,
+		private readonly options: PlanPreviewOptions = {},
+	) {
+		super();
+		this.content = content;
+		this.snapshotHash = planSnapshotHash(content ?? "");
+		this.lines = (content ?? "").split("\n");
+		this.#input.onSubmit = text => this.#saveInput(text);
+	}
+
+	get focusState(): PlanPreviewFocus {
+		return this.#focus;
+	}
+	get comments(): readonly PlanComment[] {
+		return this.#comments;
+	}
+	get pageOffset(): number {
+		return this.#scroll;
+	}
+	get sourceLine(): number {
+		return this.#sourceLine;
+	}
+	override render(width: number): string[] {
+		const height = Math.max(5, (process.stdout.rows || 40) - 8);
+		const bodyWidth = Math.max(1, width - 2);
+		const body = this.#renderSourceRows(bodyWidth);
+		this.#scroll = Math.max(0, Math.min(this.#scroll, Math.max(0, body.length - height)));
+		const visible = body.slice(this.#scroll, this.#scroll + height);
+		const actions = PLAN_REVIEW_ACTIONS.map(
+			(action, index) => `${this.#focus === "actionBar" && index === this.#actionIndex ? "▶ " : "  "}${action}`,
+		);
+		const actionBar = width < 40 ? actions : [actions.join("  ")];
+		const footer =
+			this.#focus === "commentInput"
+				? `${this.#inputKind === "notes" ? "Notes" : `Comment for source line ${this.#sourceLine}`} (Enter save, Esc cancel): ${this.#input.getValue()}`
+				: this.#focus === "sourceSelect"
+					? `Source line ${this.#sourceLine}/${this.lines.length || 1}  j/k:select  c:comment  Esc:done`
+					: `${this.#scroll + 1}-${Math.min(this.#scroll + height, body.length)}/${body.length || 1}  s:source line  n:notes  ${this.options.externalEditorKey ? `${this.options.externalEditorKey.toLowerCase()}:edit  ` : ""}Tab:actions  PgUp/PgDn:page`;
+
+		const rendered = [
+			new DynamicBorder().render(width)[0] ?? "",
+			` ${theme.bold(theme.fg("accent", "Plan review"))}`,
+			...visible.map(line => ` ${line}`),
+			"",
+			...actionBar.map(action => ` ${action}`),
+			` ${footer}`,
+			new DynamicBorder().render(width)[0] ?? "",
+		];
+		return rendered.map(line =>
+			!this.content && width < 40 && PLAN_REVIEW_ACTIONS.some(action => line.includes(action))
+				? line
+				: truncateToWidth(line, width),
+		);
+	}
+	handleMouse(event: MouseEvent): void {
+		if (event.kind !== "click" || this.#focus === "commentInput") return;
+		const renderedRow = this.#scroll + (event.localY ?? event.y) - 2;
+		const sourceLine = this.#renderedSourceLines[renderedRow];
+		if (sourceLine === undefined) return;
+		this.#sourceLine = sourceLine;
+		this.#focus = "sourceSelect";
+		this.requestRender();
+	}
+
+	handleInput(key: string): void {
+		if (this.#focus === "commentInput") {
+			if (matchesKey(key, "escape")) {
+				this.#focus = "preview";
+				this.#input.setValue("");
+				this.requestRender();
+				return;
+			}
+			this.#input.handleInput(key);
+			this.requestRender();
+			return;
+		}
+		if (matchesKey(key, "escape")) {
+			this.done({ comments: this.#comments, notes: this.#notes, snapshotHash: this.snapshotHash });
+			return;
+		}
+		if (this.#matchesExternalEditor(key)) {
+			void this.#openExternalEditor();
+			return;
+		}
+
+		if (matchesKey(key, "tab")) {
+			this.#focus = this.#focus === "actionBar" ? "preview" : "actionBar";
+			this.requestRender();
+			return;
+		}
+		if (this.#focus === "actionBar") {
+			if (matchesKey(key, "left") || matchesKey(key, "up")) this.#actionIndex = Math.max(0, this.#actionIndex - 1);
+			else if (matchesKey(key, "right") || matchesKey(key, "down"))
+				this.#actionIndex = Math.min(PLAN_REVIEW_ACTIONS.length - 1, this.#actionIndex + 1);
+			else if (matchesKey(key, "enter") || key === "\r")
+				this.done({
+					action: PLAN_REVIEW_ACTIONS[this.#actionIndex],
+					comments: this.#comments,
+
+					notes: this.#notes,
+					snapshotHash: this.snapshotHash,
+				});
+			this.requestRender();
+			return;
+		}
+		if (this.#focus === "sourceSelect") {
+			if (key === "j" || matchesKey(key, "down"))
+				this.#sourceLine = Math.min(this.lines.length || 1, this.#sourceLine + 1);
+			else if (key === "k" || matchesKey(key, "up")) this.#sourceLine = Math.max(1, this.#sourceLine - 1);
+			else if (key === "c") {
+				this.#inputKind = "comment";
+				this.#focus = "commentInput";
+			} else if (matchesKey(key, "enter")) this.#focus = "preview";
+			this.requestRender();
+			return;
+		}
+		if (key === "s") {
+			this.#focus = "sourceSelect";
+			this.requestRender();
+			return;
+		}
+		if (key === "c") {
+			this.#inputKind = "comment";
+			this.#focus = "commentInput";
+			this.requestRender();
+			return;
+		}
+		if (key === "n") {
+			this.#inputKind = "notes";
+			this.#focus = "commentInput";
+			this.requestRender();
+			return;
+		}
+		if (matchesKey(key, "pageDown")) this.#scroll += 15;
+		if (matchesKey(key, "pageUp")) this.#scroll -= 15;
+		this.requestRender();
+	}
+	#saveInput(text: string): void {
+		if (text.trim()) {
+			if (this.#inputKind === "notes") this.#notes = text;
+			else
+				this.#comments.push({
+					id: crypto.randomUUID(),
+					startLine: this.#sourceLine,
+					endLine: this.#sourceLine,
+					text,
+					snapshotHash: this.snapshotHash,
+					createdAt: Date.now(),
+				});
+		}
+		this.#input.setValue("");
+		this.#focus = "preview";
+		this.requestRender();
+	}
+	// Render numbered source rather than Markdown so every displayed row has an exact source-line owner.
+	#renderSourceRows(width: number): string[] {
+		if (!this.content) {
+			this.#renderedSourceLines = [];
+			this.#renderedBody = [theme.fg("warning", "Plan file is empty or missing.")];
+			this.#renderedBodyWidth = width;
+			return this.#renderedBody;
+		}
+		if (this.#renderedBodyWidth === width) return this.#renderedBody;
+
+		const lineNumberWidth = String(this.lines.length).length;
+		const prefixWidth = lineNumberWidth + 3;
+		const sourceWidth = Math.max(1, width - prefixWidth);
+		const body: string[] = [];
+		const sourceLines: number[] = [];
+		for (let index = 0; index < this.lines.length; index++) {
+			const prefix = `${String(index + 1).padStart(lineNumberWidth)} │ `;
+			const wrapped = Bun.wrapAnsi(this.lines[index]!.replace(/\r$/, ""), sourceWidth, {
+				hard: true,
+				trim: false,
+			});
+			const rows = wrapped ? wrapped.split("\n") : [""];
+			for (const row of rows) {
+				body.push(`${prefix}${row}`);
+				sourceLines.push(index + 1);
+			}
+		}
+		this.#renderedSourceLines = sourceLines;
+		this.#renderedBody = body;
+		this.#renderedBodyWidth = width;
+		return body;
+	}
+	#matchesExternalEditor(key: string): boolean {
+		return Boolean(
+			this.options.onExternalEditor && this.options.externalEditorKeys?.some(binding => matchesKey(key, binding)),
+		);
+	}
+	async #openExternalEditor(): Promise<void> {
+		const updatedContent = await this.options.onExternalEditor?.();
+		if (updatedContent === null || updatedContent === undefined || updatedContent === this.content) return;
+		this.content = updatedContent;
+		this.snapshotHash = planSnapshotHash(updatedContent);
+		this.lines = updatedContent.split("\n");
+		this.#renderedSourceLines = [];
+		this.#renderedBody = [];
+		this.#renderedBodyWidth = 0;
+		this.#comments = [];
+		this.#notes = "";
+		this.#scroll = 0;
+		this.#sourceLine = 1;
+		this.#focus = "preview";
+		this.requestRender();
+	}
+}

package/src/modes/components/queue-mode-selector.ts

@@ -1,6 +1,5 @@
-import { Container, type SelectItem, SelectList } from "@sayknow-cli/tui";
-import { getSelectListTheme } from "../../modes/theme/theme";
-import { DynamicBorder } from "./dynamic-border";
+import { Container, type SelectItem, type SelectList } from "@sayknow-cli/tui";
+import { FramedSelect } from "./chrome";
 
 /**
  * Component that renders a queue mode selector with borders
@@ -24,30 +23,14 @@ export class QueueModeSelectorComponent extends Container {
 			{ value: "all", label: "all", description: "Process all queued messages at once" },
 		];
 
-		// Add top border
-		this.addChild(new DynamicBorder());
-
-		// Create selector
-		this.#selectList = new SelectList(queueModes, 2, getSelectListTheme());
-
-		// Preselect current mode
-		const currentIndex = queueModes.findIndex(item => item.value === currentMode);
-		if (currentIndex !== -1) {
-			this.#selectList.setSelectedIndex(currentIndex);
-		}
-
-		this.#selectList.onSelect = item => {
-			onSelect(item.value as "all" | "one-at-a-time");
-		};
-
-		this.#selectList.onCancel = () => {
-			onCancel();
-		};
-
-		this.addChild(this.#selectList);
-
-		// Add bottom border
-		this.addChild(new DynamicBorder());
+		const framed = FramedSelect(undefined, queueModes, {
+			maxVisible: 2,
+			selectedValue: currentMode,
+			onSelect: item => onSelect(item.value as "all" | "one-at-a-time"),
+			onCancel,
+		});
+		this.#selectList = framed.selectList;
+		this.addChild(framed.container);
 	}
 
 	getSelectList(): SelectList {

package/src/modes/components/queue-pane.ts

@@ -0,0 +1,79 @@
+import { Container, matchesKey, type SelectItem, SelectList, Spacer, Text } from "@sayknow-cli/tui";
+import type { QueuedMessageEditEntry } from "../../session/agent-session";
+import { getSelectListTheme, theme } from "../theme/theme";
+import { DynamicBorder } from "./dynamic-border";
+
+const MAX_VISIBLE_QUEUE_MESSAGES = 8;
+const RAW_UP = "\x1b[A";
+const RAW_DOWN = "\x1b[B";
+
+export class QueuePaneComponent extends Container {
+	#selectList: SelectList;
+	#selectedEntry: QueuedMessageEditEntry | undefined;
+	#selectedIndex: number;
+	#onDelete: (entry: QueuedMessageEditEntry, index: number) => void;
+	#onMove: (entry: QueuedMessageEditEntry, index: number, direction: "up" | "down") => void;
+
+	constructor(
+		entries: QueuedMessageEditEntry[],
+		options: {
+			selectedIndex?: number;
+			onDelete: (entry: QueuedMessageEditEntry, index: number) => void;
+			onMove: (entry: QueuedMessageEditEntry, index: number, direction: "up" | "down") => void;
+			onClose: () => void;
+		},
+	) {
+		super();
+		this.#onDelete = options.onDelete;
+		this.#onMove = options.onMove;
+		this.#selectedIndex = Math.max(0, Math.min(options.selectedIndex ?? 0, entries.length - 1));
+		this.#selectedEntry = entries[this.#selectedIndex];
+		const byId = new Map(entries.map(entry => [entry.id, entry]));
+		const items: SelectItem[] = entries.map((entry, index) => ({
+			value: entry.id,
+			label: `${entry.label} ${index + 1}`,
+			description: entry.text,
+			hint: "Del remove · Ctrl+↑/↓ move",
+		}));
+
+		this.addChild(new Spacer(1));
+		this.addChild(new Text(theme.bold("Message queue"), 1, 0));
+		this.addChild(new Text(theme.fg("muted", "Del remove · Ctrl+↑/↓ move · Esc close"), 1, 0));
+		this.addChild(new Spacer(1));
+		this.addChild(new DynamicBorder());
+		this.#selectList = new SelectList(items, MAX_VISIBLE_QUEUE_MESSAGES, getSelectListTheme());
+		this.#selectList.onSelectionChange = item => {
+			const index = entries.findIndex(entry => entry.id === item.value);
+			this.#selectedIndex = index === -1 ? this.#selectedIndex : index;
+			this.#selectedEntry = byId.get(item.value);
+		};
+		this.#selectList.setSelectedIndex(this.#selectedIndex);
+		this.#selectList.onCancel = options.onClose;
+		this.addChild(this.#selectList);
+		this.addChild(new DynamicBorder());
+	}
+
+	handleInput(keyData: string): void {
+		if (matchesKey(keyData, "alt+up")) {
+			this.#selectList.handleInput(RAW_UP);
+			return;
+		}
+		if (matchesKey(keyData, "alt+down")) {
+			this.#selectList.handleInput(RAW_DOWN);
+			return;
+		}
+		if (matchesKey(keyData, "ctrl+up") || matchesKey(keyData, "ctrl+shift+up")) {
+			if (this.#selectedEntry) this.#onMove(this.#selectedEntry, this.#selectedIndex, "up");
+			return;
+		}
+		if (matchesKey(keyData, "ctrl+down") || matchesKey(keyData, "ctrl+shift+down")) {
+			if (this.#selectedEntry) this.#onMove(this.#selectedEntry, this.#selectedIndex, "down");
+			return;
+		}
+		if (matchesKey(keyData, "delete")) {
+			if (this.#selectedEntry) this.#onDelete(this.#selectedEntry, this.#selectedIndex);
+			return;
+		}
+		this.#selectList.handleInput(keyData);
+	}
+}

package/src/modes/components/read-tool-group.ts

@@ -80,6 +80,7 @@ export class ReadToolGroupComponent extends Container implements ToolExecutionHa
 	#entries = new Map<string, ReadEntry>();
 	#text: Text;
 	#expanded = false;
+	#manuallyExpanded: boolean | undefined;
 	#showContentPreview: boolean;
 
 	constructor(options: ReadToolGroupOptions = {}) {
@@ -137,7 +138,19 @@ export class ReadToolGroupComponent extends Container implements ToolExecutionHa
 		this.#updateDisplay();
 	}
 
+	/** Applies automatic expansion unless this renderer instance has an explicit fold choice. */
 	setExpanded(expanded: boolean): void {
+		if (this.#manuallyExpanded !== undefined) return;
+		this.#expanded = expanded;
+		this.#updateDisplay();
+	}
+
+	/**
+	 * Applies and pins an explicit fold choice for this renderer instance only.
+	 * Transcript rebuilds recreate components from global state and drop this pin.
+	 */
+	setManuallyExpanded(expanded: boolean): void {
+		this.#manuallyExpanded = expanded;
 		this.#expanded = expanded;
 		this.#updateDisplay();
 	}