@linxiraos/pi-tui 1.3.2 → 1.4.1

package/src/chat/tool-execution.ts

@@ -438,6 +438,8 @@ export class ToolExecutionComponent extends Container {
 	#spinnerActive = false;
 	// Todo write completion strikethrough reveal animation
 	#todoStrikeInterval?: NodeJS.Timeout;
+	// Once-a-second repaint for renderers that show live elapsed time (`tickElapsed`)
+	#elapsedTicker?: NodeJS.Timeout;
 	// Track if args are still being streamed (for edit/write spinner)
 	#argsComplete = false;
 	#executionStarted = false;
@@ -474,6 +476,8 @@ export class ToolExecutionComponent extends Container {
 		argsComplete?: boolean;
 		executionStarted?: boolean;
 		renderContext?: Record<string, unknown>;
+		/** Live: read at render time, so a ticking spinner advances it. */
+		readonly elapsedMs?: number;
 	} = {
 		expanded: false,
 		isPartial: true,
@@ -491,6 +495,10 @@ export class ToolExecutionComponent extends Container {
 		toolCallId?: string,
 	) {
 		super();
+		Object.defineProperty(this.#renderState, "elapsedMs", {
+			get: () => this.#elapsedMs(this.#nativeStatus()),
+			enumerable: true,
+		});
 		ensureThemeSync();
 		this.#toolCallId = toolCallId;
 		this.#toolName = toolName;
@@ -772,6 +780,32 @@ export class ToolExecutionComponent extends Container {
 				this.#renderState.spinnerFrame = undefined;
 			}
 		}
+		this.#updateElapsedTicker(isBackgroundAsyncRunning);
+	}
+
+	/**
+	 * Repaint once a second while a `tickElapsed` renderer's call executes, so a
+	 * quiet command's elapsed time advances without the 30fps spinner ticker.
+	 */
+	#updateElapsedTicker(isBackgroundAsyncRunning: boolean): void {
+		const needsTicker =
+			this.#renderer?.tickElapsed === true &&
+			this.#executionStarted &&
+			this.#isPartial &&
+			!this.#sealed &&
+			!isBackgroundAsyncRunning &&
+			!isNativeRendering();
+		if (needsTicker && !this.#elapsedTicker) {
+			this.#elapsedTicker = setInterval(() => this.#ui.requestComponentRender(this), 1000);
+		} else if (!needsTicker) {
+			this.#stopElapsedTicker();
+		}
+	}
+
+	#stopElapsedTicker(): void {
+		if (!this.#elapsedTicker) return;
+		clearInterval(this.#elapsedTicker);
+		this.#elapsedTicker = undefined;
 	}
 
 	/**
@@ -917,6 +951,7 @@ export class ToolExecutionComponent extends Container {
 			this.#renderState.spinnerFrame = undefined;
 		}
 		this.#stopTodoStrikeAnimation();
+		this.#stopElapsedTicker();
 		this.#previewReady?.resolve();
 	}
 

package/src/chrome/transcript-container.ts

@@ -5,9 +5,9 @@ import { renderForScrollback } from "../components/image";
 import { col } from "../native/describe";
 import type { NativeNode } from "../native/node";
 import { isNativeSettled, settleNative } from "../native/settle";
-import { TERMINAL } from "../terminal-capabilities";
 import { isUsageRowBlock } from "../overlays/usage-row";
 import { isToolActivityComponent } from "./tool-activity";
+import { directPlacementLift, ImageProtocol, iterm2ImagePayload, TERMINAL } from "../terminal-capabilities";
 
 /** Shared animation time supplied by the constrained transcript root. */
 export interface AnimationFrame {
@@ -126,6 +126,14 @@ interface RowSplit {
 	readonly width: number;
 	readonly hash: number | bigint;
 	readonly text: string;
+	/**
+	 * Inline images in the committed rows, in order, each with its payload and
+	 * the length of `text` before it. Their reserved rows carry no content, so
+	 * relocating by `text` alone would stop above an image and make the
+	 * archived image live again at another width; payload and offset tell the
+	 * archived image apart from a replacement or one moved elsewhere.
+	 */
+	readonly images: readonly { readonly payload: string; readonly offset: number }[];
 	/** Seam of the last render it was located in; renders are memoized per frame. */
 	located?: { readonly rendered: readonly string[]; readonly count: number };
 }
@@ -188,7 +196,33 @@ function contentOf(rows: readonly string[]): string {
  */
 function rowSplit(scrollback: readonly string[], rows: number, width: number): RowSplit {
 	const committed = scrollback.slice(0, rows);
-	return { rows, width, hash: Bun.hash(committed.join("\n")), text: contentOf(committed) };
+	const images: { payload: string; offset: number }[] = [];
+	let text = "";
+	for (const row of committed) {
+		if (TERMINAL.isImageLine(row)) images.push({ payload: iterm2ImagePayload(row) ?? row, offset: text.length });
+		text += contentOf([row]);
+	}
+	return { rows, width, hash: Bun.hash(committed.join("\n")), text, images };
+}
+
+/**
+ * `cut` moved to just below an image it would split, on terminals that cannot
+ * draw part of an image (iTerm2's inline images). There the image row draws
+ * the whole picture upward over its reserved rows; once some of those rows are
+ * in scrollback, the picture has nowhere to go and is dropped, so the image
+ * must reach scrollback whole. Kitty and SIXEL draw the visible part instead.
+ */
+function cutBelowWholeImage(rows: readonly string[], cut: number): number {
+	const protocol = TERMINAL.imageProtocol;
+	if (protocol === null || protocol === ImageProtocol.Kitty || protocol === ImageProtocol.Sixel) return cut;
+	// Only reserved rows sit between a cut inside an image and its image row,
+	// so the first image row at or below the cut decides.
+	for (let index = Math.max(0, cut); index < rows.length; index++) {
+		const row = rows[index]!;
+		if (!TERMINAL.isImageLine(row)) continue;
+		return index - directPlacementLift(row) < cut ? index + 1 : cut;
+	}
+	return cut;
 }
 
 /** Whether `prefix` matches `rows` byte-for-byte from the top. */
@@ -842,13 +876,19 @@ export class TranscriptContainer extends Container {
 		// screen; the rest stays live, so a later shrink of the chrome or the
 		// tail refills the screen from live rows instead of opening a band no
 		// frame can fill (rows still on screen cannot return from scrollback).
+		// One exception: on a terminal that cannot draw part of an image, a cut
+		// inside an image moves below it (cutBelowWholeImage), so up to that
+		// image's height of on-screen rows commits early. A later shrink can then
+		// open a band that tall, which beats losing the image.
 		let split: { index: number; rows: readonly string[]; split: RowSplit } | undefined;
 		if (policy === "pressure" && keep > 0 && limit === this.#frontier + keep) {
 			const boundary = live[keep - 1]!;
 			const visible = room - tailRows - (tailRows > 0 ? 1 : 0);
 			if (boundary.entry.state === "settled" && visible > 0) {
 				const offer = this.#splitOffer(boundary.entry, width, visible);
-				if (offer !== undefined) {
+				if (offer === "whole") {
+					limit = boundary.index + 1;
+				} else if (offer !== undefined) {
 					split = { index: boundary.index, ...offer };
 					limit = boundary.index;
 				}
@@ -891,18 +931,23 @@ export class TranscriptContainer extends Container {
 	 * The head rows of settled `entry` beyond its committed prefix that leave
 	 * `visible` rows live, or undefined when nothing would remain committed
 	 * past that prefix or the scrollback render would not line up row for row.
+	 * `"whole"` when keeping an image whole moves the cut to the block's end:
+	 * the block then retires in full, with the blank row that separates it from
+	 * the next block, which a split never carries.
 	 */
 	#splitOffer(
 		entry: TranscriptEntry,
 		width: number,
 		visible: number,
-	): { rows: readonly string[]; split: RowSplit } | undefined {
+	): { rows: readonly string[]; split: RowSplit } | "whole" | undefined {
 		const measured = this.#measuredRows(entry, width);
 		const start = this.#emittedRowCount(entry, width);
-		const total = measured.length - visible;
-		if (total <= start) return undefined;
+		const cut = measured.length - visible;
+		if (cut <= start) return undefined;
 		const scrollback = renderForScrollback(() => this.#renderEntry(entry, width));
 		if (scrollback.length !== measured.length) return undefined;
+		const total = cutBelowWholeImage(scrollback, cut);
+		if (total >= scrollback.length) return "whole";
 		return { rows: scrollback.slice(start, total), split: rowSplit(scrollback, total, width) };
 	}
 
@@ -1119,13 +1164,40 @@ export class TranscriptContainer extends Container {
 			count = split.rows;
 		} else {
 			let consumed = 0;
-			while (count < rendered.length && consumed < split.text.length) {
-				const row = contentOf([rendered[count]!]);
-				// An empty-content row matches at any offset, so the walk cannot
-				// tell it apart from a revealed row history never received.
-				if (row.length === 0 || !split.text.startsWith(row, consumed)) break;
-				consumed += row.length;
-				count++;
+			let image = 0;
+			while (count < rendered.length && (consumed < split.text.length || image < split.images.length)) {
+				const row = rendered[count]!;
+				const content = contentOf([row]);
+				if (content.length > 0) {
+					if (!split.text.startsWith(content, consumed)) break;
+					consumed += content.length;
+					count++;
+					continue;
+				}
+				// An empty-content row matches at any offset, so the walk cannot tell it
+				// apart from a revealed row history never received; only the next
+				// archived image carries the seam on, through its own reserved rows to
+				// its row, whatever its height here.
+				let index = count;
+				while (
+					index < rendered.length &&
+					!TERMINAL.isImageLine(rendered[index]!) &&
+					contentOf([rendered[index]!]).length === 0
+				) {
+					index++;
+				}
+				const imageRow = rendered[index];
+				if (
+					imageRow === undefined ||
+					!TERMINAL.isImageLine(imageRow) ||
+					(iterm2ImagePayload(imageRow) ?? imageRow) !== split.images[image]?.payload ||
+					consumed !== split.images[image]?.offset ||
+					index - count !== directPlacementLift(imageRow)
+				) {
+					break;
+				}
+				count = index + 1;
+				image++;
 			}
 		}
 		split.located = { rendered, count };

package/src/components/editor.ts

@@ -704,6 +704,8 @@ export class Editor implements Component, Focusable {
 		| { line: number; startCol: number; endCol: number; original: string; cursorOffset: number }
 		| undefined;
 	#autocompletePrefix: string = "";
+	/** False while the popup's untouched top row is a description-only slash hit ({@link AutocompleteItem.descriptionMatch}): Enter then submits the typed text. */
+	#enterAcceptsSelection = true;
 	#autocompleteRequestId: number = 0;
 	#autocompletePendingRequest: AutocompleteRequest | undefined;
 	#autocompleteRequestRunning = false;
@@ -1921,6 +1923,7 @@ export class Editor implements Component, Focusable {
 						this.onAutocompleteUpdate?.();
 					} else {
 						this.#autocompleteList.handleInput(data);
+						this.#enterAcceptsSelection = true;
 						this.onAutocompleteUpdate?.();
 						return;
 					}
@@ -1965,8 +1968,11 @@ export class Editor implements Component, Focusable {
 					// Check for stale autocomplete state while an async refresh is pending
 					const currentLine = this.#state.lines[this.#state.cursorLine] ?? "";
 					const currentTextBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-					if (!this.#autocompletePrefixMatchesCursorText(currentTextBeforeCursor, selected)) {
-						// Autocomplete is stale - cancel and fall through to normal submission
+					if (
+						!this.#autocompletePrefixMatchesCursorText(currentTextBeforeCursor, selected) ||
+						!this.#enterAcceptsSelection
+					) {
+						// Stale, or a description-only hit the user never selected: submit the typed text.
 						this.#cancelAutocomplete();
 					} else {
 						if (selected && this.#autocompleteProvider) {
@@ -1998,10 +2004,12 @@ export class Editor implements Component, Focusable {
 					if (
 						!selected ||
 						!this.#autocompletePrefixMatchesCursorText(currentTextBeforeCursor, selected) ||
-						this.#selectedSlashArgumentIsAlreadyTyped(selected)
+						this.#selectedSlashArgumentIsAlreadyTyped(selected) ||
+						!this.#enterAcceptsSelection
 					) {
-						// Stale, or accepting would only append whitespace to an already fully
-						// typed slash-command argument (`/mcp list` + Enter): cancel and fall
+						// Stale, accepting would only append whitespace to an already fully
+						// typed slash-command argument (`/mcp list` + Enter), or the row is a
+						// description-only hit the user never selected: cancel and fall
 						// through to normal submission instead of swallowing the keypress.
 						this.#cancelAutocomplete();
 					} else {
@@ -2145,9 +2153,10 @@ export class Editor implements Component, Focusable {
 				) {
 					const syncResult = this.#autocompleteProvider.trySyncSlashCompletion(textBeforeCursor);
 					// The collapsed `/skill:` namespace row is not a runnable command; Enter submits
-					// immediately after applying, so only a real command may be completed here.
+					// immediately after applying, so only a real command may be completed here, and
+					// only one whose name matches: a description-only hit would run an unrelated command.
 					const selected = syncResult?.items.find(item => item.value !== SKILL_NAMESPACE);
-					if (syncResult && selected) {
+					if (syncResult && selected && !selected.descriptionMatch) {
 						// Invalidate any pending async autocomplete so its stale results are discarded
 						this.#autocompleteRequestId += 1;
 						// Apply the best match and submit the completed command
@@ -4876,6 +4885,7 @@ export class Editor implements Component, Focusable {
 	): void {
 		this.#autocompletePrefix = suggestions.prefix;
 		this.#autocompleteList = this.#createAutocompleteList(suggestions.prefix, suggestions.items);
+		this.#enterAcceptsSelection = !suggestions.items[0]?.descriptionMatch;
 		this.#autocompleteState = state;
 		this.onAutocompleteUpdate?.();
 	}

package/src/components/image.ts

@@ -1,5 +1,6 @@
 import { encodeSixelAsync } from "@linxiraos/pi-natives";
 import { getKittyGraphics } from "../kitty-graphics";
+import { ensureSixelRasterWidth } from "../sixel";
 import {
 	encodeSixelNow,
 	getCellDimensions,
@@ -736,7 +737,7 @@ export class Image implements Component {
 		const request: SixelEncode = { widthPx, heightPx, backgroundRgb };
 		this.#sixel = request;
 		const settle = (sequence: string | null): void => {
-			request.sequence = sequence;
+			request.sequence = sequence === null ? null : ensureSixelRasterWidth(sequence);
 			if (this.#sixel !== request || getTerminalBackgroundColor() !== backgroundRgb) return;
 			this.invalidate();
 			if (this.#options.requestRender) this.#options.requestRender();
@@ -845,9 +846,9 @@ export class Image implements Component {
 				// height. First (rows-1) lines are empty (TUI clears them); the last
 				// saves the final-row cursor, moves up to the image origin, emits the
 				// image sequence, then restores the final-row cursor. When the block
-				// straddles the viewport top, the renderer rewrites this line to the
-				// visible slice (encodeKittyPlacementLine) from the geometry
-				// registered below.
+				// straddles the viewport top, the renderer crops the source raster
+				// for SIXEL or rewrites the Kitty placement's visible source slice
+				// from the geometry registered below.
 				if (this.#imageId != null && this.#budget !== undefined) {
 					this.#budget.registerPlacementGeometry(
 						this.#imageId,

package/src/components/markdown.ts

@@ -4420,7 +4420,7 @@ export class Markdown implements Component {
 	 * Delegates to wrapTextWithAnsi() so ANSI codes + long tokens are handled
 	 * consistently with the rest of the renderer.
 	 */
-	#wrapCellText(text: string, maxWidth: number): string[] {
+	#wrapCellText(text: string, maxWidth: number, clampOversized = true): string[] {
 		const cellWidth = Math.max(1, maxWidth);
 		// Wrap the whole cell in one call so wrapTextWithAnsi() balances OSC 8
 		// hyperlink state across explicit newlines (e.g. `<br>` rendered as \n);
@@ -4435,7 +4435,14 @@ export class Markdown implements Component {
 		// (e.g. mdCode) would bleed into the "│" and the following cells.
 		// Terminate each line at default fg, clearing bold/italic but keeping
 		// any ambient background (message-bg rendering) intact.
-		return wrapped.map(line => `${line}\x1b[22m\x1b[23m\x1b[39m`);
+		// A wide glyph can exceed a one-cell column without wrapping (a 2-cell
+		// emoji in a column squeezed to 1), so clamp here before the row is
+		// spliced between borders; otherwise the overwide row is re-wrapped and
+		// the trailing border lands on its own line.
+		return wrapped.map(line => {
+			const fitted = clampOversized && visibleWidth(line) > cellWidth ? truncateToWidth(line, cellWidth) : line;
+			return `${fitted}\x1b[22m\x1b[23m\x1b[39m`;
+		});
 	}
 
 	/**
@@ -4626,7 +4633,8 @@ export class Markdown implements Component {
 				if (rowCellLines[openCell].length > settledLineCount) {
 					const width = columnWidths[openCell];
 					const kept = rowCellLines[openCell].slice(0, settledLineCount);
-					const last = width > 1 ? (this.#wrapCellText(kept[settledLineCount - 1], width - 1)[0] ?? "") : "";
+					const last =
+						width > 1 ? (this.#wrapCellText(kept[settledLineCount - 1], width - 1, false)[0] ?? "") : "";
 					kept[settledLineCount - 1] = `${visibleWidth(last) < width ? last : ""}…`;
 					rowCellLines[openCell] = kept;
 				}

package/src/components/sparkline.d.ts

@@ -0,0 +1,34 @@
+/**
+ * One-row block sparklines (`▁▂▃▅▇█`) for ANSI renderers: the usage history
+ * in `zetacode usage`, a job widget's series in the `wait` card and status line.
+ */
+/** Block glyphs from lowest to highest. */
+export declare const SPARK_LEVELS: readonly ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+/** How {@link renderSparkline} maps values to glyphs and styles them. */
+export interface SparklineOptions {
+    /** Domain low end; values at or below it draw the lowest block. Default 0. */
+    readonly min?: number;
+    /** Domain high end; values at or above it draw the full block. Default the largest value. */
+    readonly max?: number;
+    /** Styles one glyph; `fraction` is the value's 0–1 position in the domain. */
+    readonly style?: (glyph: string, value: number, fraction: number) => string;
+    /** What a missing value draws, already styled. Default a space. */
+    readonly gap?: string;
+}
+/** The block glyph for a 0–1 fraction of the domain. */
+export declare function sparkGlyph(fraction: number): string;
+/** One cell per value, oldest first; `undefined` (and non-finite) values draw the gap. */
+export declare function renderSparkline(values: readonly (number | undefined)[], options?: SparklineOptions): string;
+/**
+ * `values` squeezed into at most `cells` points by equal-count bucket means,
+ * newest bucket last; shorter series come back unchanged.
+ */
+export declare function fitSparkValues(values: readonly number[], cells: number): readonly number[];
+/**
+ * The largest value per time bucket over `[sinceMs, nowMs]`, `cells` buckets
+ * wide; buckets without a point are `undefined` (a gap in the sparkline).
+ */
+export declare function peakBuckets(points: Iterable<{
+    readonly at: number;
+    readonly value: number;
+}>, sinceMs: number, nowMs: number, cells: number): (number | undefined)[];

package/src/components/sparkline.ts

@@ -0,0 +1,89 @@
+/**
+ * One-row block sparklines (`▁▂▃▅▇█`) for ANSI renderers: the usage history
+ * in `zetacode usage`, a job widget's series in the `wait` card and status line.
+ */
+
+/** Block glyphs from lowest to highest. */
+export const SPARK_LEVELS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"] as const;
+
+/** How {@link renderSparkline} maps values to glyphs and styles them. */
+export interface SparklineOptions {
+	/** Domain low end; values at or below it draw the lowest block. Default 0. */
+	readonly min?: number;
+	/** Domain high end; values at or above it draw the full block. Default the largest value. */
+	readonly max?: number;
+	/** Styles one glyph; `fraction` is the value's 0–1 position in the domain. */
+	readonly style?: (glyph: string, value: number, fraction: number) => string;
+	/** What a missing value draws, already styled. Default a space. */
+	readonly gap?: string;
+}
+
+/** The block glyph for a 0–1 fraction of the domain. */
+export function sparkGlyph(fraction: number): string {
+	const clamped = Number.isFinite(fraction) ? Math.min(Math.max(fraction, 0), 1) : 0;
+	return SPARK_LEVELS[Math.min(SPARK_LEVELS.length - 1, Math.floor(clamped * SPARK_LEVELS.length))]!;
+}
+
+/** One cell per value, oldest first; `undefined` (and non-finite) values draw the gap. */
+export function renderSparkline(values: readonly (number | undefined)[], options: SparklineOptions = {}): string {
+	const min = options.min ?? 0;
+	let max = options.max;
+	if (max === undefined) {
+		max = min;
+		for (const value of values) if (value !== undefined && Number.isFinite(value) && value > max) max = value;
+	}
+	const span = max - min;
+	const gap = options.gap ?? " ";
+	let out = "";
+	for (const value of values) {
+		if (value === undefined || !Number.isFinite(value)) {
+			out += gap;
+			continue;
+		}
+		const fraction = span > 0 ? (value - min) / span : value > min ? 1 : 0;
+		const glyph = sparkGlyph(fraction);
+		out += options.style ? options.style(glyph, value, Math.min(Math.max(fraction, 0), 1)) : glyph;
+	}
+	return out;
+}
+
+/**
+ * `values` squeezed into at most `cells` points by equal-count bucket means,
+ * newest bucket last; shorter series come back unchanged.
+ */
+export function fitSparkValues(values: readonly number[], cells: number): readonly number[] {
+	const count = Math.max(0, Math.floor(cells));
+	if (values.length <= count) return values;
+	const out: number[] = [];
+	for (let bucket = 0; bucket < count; bucket++) {
+		const from = Math.floor((bucket * values.length) / count);
+		const to = Math.max(from + 1, Math.floor(((bucket + 1) * values.length) / count));
+		let sum = 0;
+		for (let i = from; i < to; i++) sum += values[i]!;
+		out.push(sum / (to - from));
+	}
+	return out;
+}
+
+/**
+ * The largest value per time bucket over `[sinceMs, nowMs]`, `cells` buckets
+ * wide; buckets without a point are `undefined` (a gap in the sparkline).
+ */
+export function peakBuckets(
+	points: Iterable<{ readonly at: number; readonly value: number }>,
+	sinceMs: number,
+	nowMs: number,
+	cells: number,
+): (number | undefined)[] {
+	const span = Math.max(1, nowMs - sinceMs);
+	const count = Math.max(0, Math.floor(cells));
+	const buckets: (number | undefined)[] = Array.from({ length: count }, () => undefined);
+	if (count === 0) return buckets;
+	for (const point of points) {
+		const offset = Math.floor(((point.at - sinceMs) / span) * count);
+		const index = Math.min(count - 1, Math.max(0, offset));
+		const prev = buckets[index];
+		buckets[index] = prev === undefined ? point.value : Math.max(prev, point.value);
+	}
+	return buckets;
+}

package/src/index.d.ts

@@ -25,6 +25,7 @@ export * from "./components/section";
 export * from "./components/select-list";
 export * from "./components/settings-list";
 export * from "./components/spacer";
+export * from "./components/sparkline";
 export * from "./components/tab-bar";
 export * from "./components/table";
 export * from "./components/text";

package/src/index.ts

@@ -30,6 +30,7 @@ export * from "./components/section";
 export * from "./components/select-list";
 export * from "./components/settings-list";
 export * from "./components/spacer";
+export * from "./components/sparkline";
 export * from "./components/tab-bar";
 export * from "./components/table";
 export * from "./components/text";

package/src/native/backend.ts

@@ -54,6 +54,7 @@ import { getNativeBlob, type NativeBlob } from "./blobs";
 import { node } from "./describe";
 import { encodeTspJson, encodeTspMessage, type TspHello, TspReader, splitTspMessage } from "./encode";
 import type { DescribeContext, NativeChild, NativeNode, NativeSurface, NativeUiEvent } from "./node";
+import { NARROW_SHEET_COLS } from "./overlay";
 import { nativeComponentId, Reconciler } from "./reconcile";
 import { setNativeRendering } from "./state";
 
@@ -244,6 +245,10 @@ class Surface {
 	acked = 0;
 	/** Send times of unacknowledged frames, oldest first. */
 	unacked: number[] = [];
+	/** Send time of the oldest frame left unanswered when the current stall began; cleared by the next ack. */
+	stalledSince: number | undefined;
+	/** Credit resets since {@link stalledSince}. */
+	stallResets = 0;
 	focus: string | null = null;
 	dirty = false;
 
@@ -456,6 +461,8 @@ export class NativeBackend {
 		surface.reconciler.detachLive();
 		surface.unacked = [];
 		surface.acked = surface.seq;
+		surface.stalledSince = undefined;
+		surface.stallResets = 0;
 		surface.focus = null;
 		surface.dirty = false;
 		this.#write("o", { id: surface.id, mode: "inline", title: "omp", role: SESSION_ROLE, adopt: true });
@@ -612,11 +619,16 @@ export class NativeBackend {
 		if (surface.unacked.length < this.#credits) return true;
 		const oldest = surface.unacked[0]!;
 		if (this.#scheduler.now() - oldest < STALLED_ACK_MS) return false;
-		logger.warn("TSP: terminal stopped acknowledging frames; resuming without credits", {
-			sf: surface.id,
-			s: surface.seq,
-			acked: surface.acked,
-		});
+		// One warning per stall: a terminal that never acks would otherwise log one every `STALLED_ACK_MS`.
+		if (surface.stalledSince === undefined) {
+			surface.stalledSince = oldest;
+			logger.warn("TSP: terminal stopped acknowledging frames; resuming without credits", {
+				sf: surface.id,
+				s: surface.seq,
+				acked: surface.acked,
+			});
+		}
+		surface.stallResets++;
 		surface.unacked = [];
 		surface.acked = surface.seq;
 		return true;
@@ -801,6 +813,15 @@ export class NativeBackend {
 				const newly = Math.min(event.s, surface.seq) - surface.acked;
 				surface.acked = Math.min(event.s, surface.seq);
 				surface.unacked.splice(0, newly);
+				if (surface.stalledSince !== undefined) {
+					logger.debug("TSP: terminal acknowledging frames again", {
+						sf: surface.id,
+						stalledMs: this.#scheduler.now() - surface.stalledSince,
+						resets: surface.stallResets,
+					});
+					surface.stalledSince = undefined;
+					surface.stallResets = 0;
+				}
 				this.#clearStallTimer();
 				if (surface.dirty) this.#host.requestRender();
 				return;
@@ -919,7 +940,12 @@ export class NativeBackend {
 		if (overlay.component.nativeSheet?.(this.#cx)) return overlay.component;
 		const own = overlay.component.nativeOverlay;
 		const anchor = own?.anchor ?? overlayAnchor(overlay.options);
-		const size = own?.size ?? overlaySize(overlay.options, this.#cx.cols);
+		let size = own?.size ?? overlaySize(overlay.options, this.#cx.cols);
+		// A centered sheet in a narrow pane fills it instead of floating with margins: `lg`, and a component's own `md`
+		// sheet (an undeclared `md` is a generic dialog sized from its options).
+		if (anchor === "center" && this.#cx.cols < NARROW_SHEET_COLS && (size === "lg" || own?.size === "md")) {
+			size = "full";
+		}
 		const modal = overlay.focused || overlay.options?.fullscreen === true;
 		const role = own?.role;
 		const head = own?.head;

package/src/native/describe.d.ts

@@ -9,7 +9,7 @@
  *   ]);
  * }
  */
-import type { TspKind, TspProps, TspSpan, TspText } from "@linxiraos/pi-wire";
+import type { TspKind, TspPropNode, TspProps, TspSpan, TspText } from "@linxiraos/pi-wire";
 import type { NativeChild, NativeNode } from "./node";
 /** A node of any kind. */
 export declare function node<K extends TspKind>(k: K, p?: TspProps<K>, c?: readonly NativeChild[], key?: string): NativeNode;
@@ -37,6 +37,12 @@ export declare const EMPTY_NODE: NativeNode;
 export declare function keyed(described: NativeNode, key: string): NativeNode;
 /** `described` mounted but not laid out when `hidden` (cheap visibility toggles keep ids and view state). */
 export declare function withHidden(described: NativeNode, hidden: boolean): NativeNode;
+/**
+ * A described tree as the node tree a prop carries (a `hovercard`): plain
+ * nodes only, since nothing reconciles inside a prop; component children
+ * (which describe themselves per frame) are left out.
+ */
+export declare function propNode(described: NativeNode): TspPropNode;
 /** Stable node key for an arbitrary identity string; keys join into `/` keypaths, so identities are hashed. */
 export declare function stableKey(identity: string): string;
 /** Drop absent entries (`undefined`, `null`, `false`) from a child list. */

package/src/native/describe.ts

@@ -9,7 +9,7 @@
  *   ]);
  * }
  */
-import type { TspKind, TspProps, TspSpan, TspText } from "@linxiraos/pi-wire";
+import type { TspKind, TspPropNode, TspProps, TspSpan, TspText } from "@linxiraos/pi-wire";
 import type { NativeChild, NativeNode } from "./node";
 
 /** A node of any kind. */
@@ -76,6 +76,23 @@ export function withHidden(described: NativeNode, hidden: boolean): NativeNode {
 	return node(described.k, { ...described.p, hidden: true } as TspProps, described.c, described.key);
 }
 
+/**
+ * A described tree as the node tree a prop carries (a `hovercard`): plain
+ * nodes only, since nothing reconciles inside a prop; component children
+ * (which describe themselves per frame) are left out.
+ */
+export function propNode(described: NativeNode): TspPropNode {
+	const out: { k: TspKind; p?: TspProps; c?: TspPropNode[]; key?: string } = { k: described.k };
+	if (described.p !== undefined) out.p = described.p;
+	if (described.c !== undefined) {
+		const children: TspPropNode[] = [];
+		for (const child of described.c) if ("k" in child) children.push(propNode(child));
+		out.c = children;
+	}
+	if (described.key !== undefined) out.key = described.key;
+	return out as TspPropNode;
+}
+
 /** Stable node key for an arbitrary identity string; keys join into `/` keypaths, so identities are hashed. */
 export function stableKey(identity: string): string {
 	return Bun.hash(identity).toString(36);

package/src/native/overlay.d.ts

@@ -10,6 +10,8 @@ import type { TspProps, TspSpan, TspText } from "@linxiraos/pi-wire";
 import { type KeyName } from "../key-hint-format";
 import { type Keybinding } from "../keybindings";
 import type { NativeChild, NativeNode } from "./node";
+/** Below this many columns a centered sheet fills the pane instead of floating with margins. */
+export declare const NARROW_SHEET_COLS = 100;
 /** One footer hint: the keys that trigger it and what it does. */
 export interface NativeHint {
     /** Key ids (`"ctrl+o"`, `"escape"`); alternatives render side by side. */

package/src/native/overlay.ts

@@ -12,6 +12,9 @@ import { getKeybindings, type Keybinding } from "../keybindings";
 import { card, kbd, list, node, row, span, text } from "./describe";
 import type { NativeChild, NativeNode } from "./node";
 
+/** Below this many columns a centered sheet fills the pane instead of floating with margins. */
+export const NARROW_SHEET_COLS = 100;
+
 /** One footer hint: the keys that trigger it and what it does. */
 export interface NativeHint {
 	/** Key ids (`"ctrl+o"`, `"escape"`); alternatives render side by side. */