@linxiraos/pi-tui 1.2.1 → 1.3.0

package/src/prompt/queued-messages.ts

@@ -18,7 +18,7 @@ export interface QueuedMessageGroup {
  * Messages queued while the agent works, above the editor. ANSI: a heading
  * per group, numbered dim rows and the dequeue hint. Natively (§8.1): a
  * stack of pills, each `corner-down-right` · the text · `⌥↑ Edit`, the total
- * count in the first pill when more than one waits; the edit control sends
+ * (`N queued`, not a position) in the first pill when more than one waits; the edit control sends
  * `queue.edit`, answered like the dequeue key.
  */
 export class QueuedMessagesBand extends Container {
@@ -63,7 +63,14 @@ export class QueuedMessagesBand extends Container {
 					),
 				];
 				if (pills.length === 0 && count > 1) {
-					children.push(node("badge", { text: `${count}`, role: "zeta.queue.count" }, undefined, "count"));
+					children.push(
+						node(
+							"badge",
+							{ text: `${count} queued`, title: `${count} messages queued`, role: "zeta.queue.count" },
+							undefined,
+							"count",
+						),
+					);
 				}
 				children.push(
 					node(

package/src/prompt/tips.txt

@@ -29,5 +29,4 @@ Turn on `/advisor` to attach a second model that reviews every turn and quietly
 Try starting your prompt with a ->, and writing a list (1. Do X, 2. Do Y)
 Press {key:shift+tab} to cycle through reasoning effort levels
 zeta can reconfigure and extend itself — ask any questions you have!
-Lint/type errors piling up? `zetacode cleanse` (or /cleanse right here) hunts project diagnostics and fixes them with parallel subagents — {key:escape} cancels
-[NO-TERN] Psst, zeta has a natural habitat 🐦 [tern](https://scl.so/tern)
+Lint/type errors piling up? `zetacode cleanse` (or /cleanse right here) hunts project diagnostics and fixes them with parallel subagents — {key:escape} cancels

package/src/prompt/typing-word.ts

@@ -0,0 +1,59 @@
+/**
+ * The word being typed in the composer. Misspelling marks hold off on it until
+ * the caret leaves it (a space or punctuation, a caret move, losing focus), the
+ * way Slack and Chromium mark a typo only once its word is done; marks on other
+ * words stay while typing.
+ */
+
+/** A word of one logical line, as UTF-16 columns `[start, end)`. */
+export interface TypingWord {
+	line: number;
+	start: number;
+	end: number;
+}
+
+/** Letters, marks and digits, with apostrophes joining contractions. */
+const WORD_CHAR = /[\p{L}\p{M}\p{N}'\u2019]/u;
+
+/** The run of word characters around column `col` of `line` (`undefined` between non-word characters). */
+function wordAround(line: string, col: number): { start: number; end: number } | undefined {
+	let start = col;
+	while (start > 0 && WORD_CHAR.test(line.charAt(start - 1))) start--;
+	let end = col;
+	while (end < line.length && WORD_CHAR.test(line.charAt(end))) end++;
+	return start < end ? { start, end } : undefined;
+}
+
+/** Follows an editor's text revision and caret to know which word is being typed. */
+export class TypingWordTracker {
+	#revision: number | undefined;
+	#word: TypingWord | undefined;
+
+	/** The word being typed, if any. */
+	get word(): TypingWord | undefined {
+		return this.#word;
+	}
+
+	/**
+	 * Catch up with the editor: an edit that leaves the caret in (or right after)
+	 * a word starts typing it; a caret move out of that word, or losing focus,
+	 * ends it. The first call only records the revision, so a restored draft is
+	 * not held. Returns whether the held word changed.
+	 */
+	update(revision: number, lines: readonly string[], line: number, col: number, focused: boolean): boolean {
+		const before = this.#word;
+		const edited = this.#revision !== undefined && this.#revision !== revision;
+		this.#revision = revision;
+		if (!focused) {
+			this.#word = undefined;
+		} else if (edited) {
+			const span = wordAround(lines[line] ?? "", col);
+			this.#word = span && { line, start: span.start, end: span.end };
+		} else if (before && (before.line !== line || col < before.start || col > before.end)) {
+			this.#word = undefined;
+		}
+		return (
+			before?.line !== this.#word?.line || before?.start !== this.#word?.start || before?.end !== this.#word?.end
+		);
+	}
+}

package/src/prompt/welcome.ts

@@ -15,27 +15,21 @@ import type { Component } from "../tui";
 import { padding, replaceTabs, visibleWidth, wrapTextWithAnsi } from "../utils";
 import tipsText from "./tips.txt" with { type: "text" };
 
-/** Leading marker for a tip that pitches Tern: shown only while no TSP surface
- *  is live, since a live one means the user is already in Tern. */
-const NO_TERN_TIP_MARKER = /^\[NO-TERN\]\s*/;
-
 /** Trailing marker that flags a tip as a "what's new" callout. Stripped before
  *  wrapping (with any preceding whitespace) and replaced by {@link NEW_TAG_TEXT}
  *  painted as a shimmering rainbow. Non-global so `.test` stays stateless. */
 const NEW_TIP_MARKER = /\s*\[NEW\]\s*$/;
 
-/** A tips.txt line. The structural markers stay in the source line — they drive
- *  pool selection and the "[NEW]" weighting — while the user-visible text is
+/** A tips.txt line. The `[NEW]` marker stays in the source line — it drives
+ *  pool selection and the weighting — while the user-visible text is
  *  resolved from the host catalogue under `tipN`, N = the 1-based line number. */
 interface TipLine {
 	/** 1-based tips.txt line number; the catalogue key is `tip${line}`. */
 	readonly line: number;
-	/** Raw line, markers intact — what the weighted picker selects from. */
+	/** Raw line, marker intact — what the weighted picker selects from. */
 	readonly raw: string;
-	/** English body with both markers stripped: the `tuiText` fallback. */
+	/** English body with the `[NEW]` marker stripped: the `tuiText` fallback. */
 	readonly english: string;
-	/** Pitches Tern; excluded from the TSP pool. */
-	readonly noTern: boolean;
 	/** "What's new" callout; carries the heavier selection weight. */
 	readonly isNew: boolean;
 }
@@ -49,19 +43,47 @@ const TIP_LINES: readonly TipLine[] = tipsText.split("\n").flatMap((line, index)
 		{
 			line: index + 1,
 			raw,
-			english: raw.replace(NO_TERN_TIP_MARKER, "").replace(NEW_TIP_MARKER, ""),
-			noTern: NO_TERN_TIP_MARKER.test(raw),
+			english: raw.replace(NEW_TIP_MARKER, ""),
 			isNew: NEW_TIP_MARKER.test(raw),
 		},
 	];
 });
 
-/** Classic pool: every tip's raw line, so {@link pickWeightedTip} can still read
- *  the trailing {@link NEW_TIP_MARKER} for its selection weight. */
+/** Every tip's raw line, so {@link pickWeightedTip} can still read the
+ *  trailing {@link NEW_TIP_MARKER} for its selection weight. */
 const TIPS: readonly string[] = TIP_LINES.map(tip => tip.raw);
 
-/** TSP pool: those marked {@link NO_TERN_TIP_MARKER} dropped. */
-const TSP_TIPS: readonly string[] = TIP_LINES.filter(tip => !tip.noTern).map(tip => tip.raw);
+/** Catalogue keys (`tip${line}`) of every tips.txt line, in file order. The
+ *  host needs them to gate a tip by the product feature it advertises. */
+export const TIP_CATALOGUE_KEYS: readonly string[] = TIP_LINES.map(tip => `tip${tip.line}`);
+
+/**
+ * Host-installable tip gate: receives the tip's catalogue key and its raw
+ * tips.txt line; returning false removes it from the splash pool.
+ */
+export type TuiTipFilter = (key: string, raw: string) => boolean;
+
+let tipFilter: TuiTipFilter | undefined;
+
+/**
+ * Install the host's tip gate (pass `undefined` to reset). Consulted for every
+ * candidate on every pick, so no roll can surface a rejected tip — used when a
+ * feature a tip advertises is switched off by configuration.
+ */
+export function setTuiTipFilter(filter: TuiTipFilter | undefined): void {
+	tipFilter = filter;
+}
+
+/** The pool {@link WelcomeComponent} picks from, with the host gate applied. */
+function tipPool(): readonly string[] {
+	// Captured so the narrowing survives into the filter callback.
+	const filter = tipFilter;
+	if (!filter) return TIPS;
+	return TIPS.filter(tip => {
+		const entry = TIP_LINES.find(candidate => candidate.raw === tip);
+		return entry === undefined || filter(`tip${entry.line}`, tip);
+	});
+}
 
 /** Visible text rendered in place of {@link NEW_TIP_MARKER}. */
 const NEW_TAG_TEXT = "NEW!";
@@ -99,7 +121,7 @@ interface ResolvedTip {
 	readonly isNew: boolean;
 }
 
-/** Localise a picked tip. `raw` is a {@link TIPS}/{@link TSP_TIPS} member (or the
+/** Localise a picked tip. `raw` is a {@link TIPS} member (or the
  *  nerdfont nudge); the catalogue is consulted live, so `/language` applies. */
 function resolveTip(raw: string): ResolvedTip {
 	if (raw === NERDFONT_TIP) return { text: tuiText("welcomeNerdFontJoke", NERDFONT_TIP), isNew: false };
@@ -165,7 +187,7 @@ function expandTipKeys(tip: string): string {
 	});
 }
 
-/** Markdown-style links in tips.txt: `[Tern](https://scl.so/tern)` shows the label, linked to the URL. */
+/** Markdown-style links in tips.txt: `[docs](https://example.com)` shows the label, linked to the URL. */
 const TIP_LINK = /\[([^\]]+)\]\(([^\s)]+)\)/g;
 
 /** Tip links as underlined OSC 8 labels, or `label (url)` where the terminal cannot link. */
@@ -238,10 +260,11 @@ export function renderWelcomeTip(tip: string, width: number, phase = 0, isNew =
 }
 
 /**
- * The session's welcome banner. In a terminal: the gradient logo beside the
- * `zeta` wordmark with the version under it (the logo alone when the lockup does
+ * The session's welcome banner. In a terminal: the gradient mark beside the
+ * `Zeta` wordmark, with the version under the wordmark and the `Linxira-Zeta`
+ * identity subline centered below the pair (the mark alone when the lockup does
  * not fit) and the tip of the session (dropped below {@link TIP_MIN_COLUMNS}
- * columns). Natively: a card with the same logo, wordmark, version and tip
+ * columns). Natively: a card with the same mark, wordmark, version and tip
  * ({@link WelcomeComponent.describe}).
  */
 export class WelcomeComponent implements Component {
@@ -249,10 +272,8 @@ export class WelcomeComponent implements Component {
 	#animTimer: Timer | null = null;
 	#requestRender: (() => void) | null = null;
 	// Tip randomness is latched once so the tip is stable across renders, but
-	// the nerdfont-nag gate re-reads the live preset and the pool re-reads the
-	// live TSP state: the startup prepaint can run under the default "unicode"
-	// preset before settings resolve the real one, and an optimistic Tern start
-	// falls back to the classic renderer when `hello` never confirms.
+	// the nerdfont-nag gate re-reads the live preset: the startup prepaint can
+	// run under the default "unicode" preset before settings resolve the real one.
 	#nagRoll: number | undefined;
 	#tipRoll: number | undefined;
 	// Render cache: the welcome box is the first transcript-area component, so
@@ -272,7 +293,7 @@ export class WelcomeComponent implements Component {
 		if (theme.getSymbolPreset() === "unicode" && this.#nagRoll < 0.1) {
 			return NERDFONT_TIP;
 		}
-		return pickWeightedTip(isNativeRendering() ? TSP_TIPS : TIPS, this.#tipRoll) || undefined;
+		return pickWeightedTip(tipPool(), this.#tipRoll) || undefined;
 	}
 
 	invalidate(): void {
@@ -284,7 +305,8 @@ export class WelcomeComponent implements Component {
 	/**
 	 * A `card` (`zeta.welcome`) mirroring the terminal banner: the lockup
 	 * (`zeta.welcome.lockup`: the terminal's builtin `zeta` mark, which it animates,
-	 * beside the wordmark with the version under it) and the tip of the session.
+	 * beside the `Zeta` wordmark with the version and the `Linxira-Zeta`
+	 * subline under it) and the tip of the session.
 	 * Roles carry the look (gradient logo, type scale); a "[NEW]" tip
 	 * carries a terminal-clocked shimmering tag.
 	 */
@@ -313,8 +335,9 @@ export class WelcomeComponent implements Component {
 					keyed(
 						col(
 							[
-								art([span("Z e t a", "strong")], "zeta.welcome.wordmark"),
+								art([span("Zeta", "strong")], "zeta.welcome.wordmark"),
 								art([span(`v${this.version}`, "dim mono")], "zeta.welcome.version"),
+								art([span("Linxira-Zeta", "dim")], "zeta.welcome.subline"),
 							],
 							{ role: "zeta.welcome.mark" },
 						),
@@ -466,22 +489,39 @@ export class WelcomeComponent implements Component {
 	}
 }
 
-/** Block-grid brand mark shared by the welcome and setup surfaces. */
-export const ZETA_LOGO = ["████████████", "   ████████ ", "  ████████  ", " ████████▒▒▒", "████████████"];
+// The three arrays below are GENERATED by the standard FIGlet tool, never
+// hand-drawn: `bun scripts/brand/generate-logo-art.ts` rewrites them from the
+// FIGlet fonts vendored under `scripts/brand/fonts/` (mark + wordmark in the
+// standard "ANSI Shadow" font, the `Linxira-Zeta` subline in "mini"), and
+// `bun scripts/brand/brand-check.ts` fails on any hand-edited glyph. Standard
+// FIGlet fonts carry no Greek block, so the mark is the Latin `Z` — the same
+// glyph as `Ζ` (see `scripts/brand/logo-art.ts`).
+
+/** Brand mark: FIGlet `ANSI Shadow` render of `Z` (generated). */
+export const ZETA_LOGO = ["███████╗", "╚══███╔╝", "  ███╔╝ ", " ███╔╝  ", "███████╗", "╚══════╝"];
+
+/** Primary product name: FIGlet `ANSI Shadow` render of `Zeta` (generated). */
+export const ZETA_WORDMARK = [
+	"███████╗███████╗████████╗ █████╗ ",
+	"╚══███╔╝██╔════╝╚══██╔══╝██╔══██╗",
+	"  ███╔╝ █████╗     ██║   ███████║",
+	" ███╔╝  ██╔══╝     ██║   ██╔══██║",
+	"███████╗███████╗   ██║   ██║  ██║",
+	"╚══════╝╚══════╝   ╚═╝   ╚═╝  ╚═╝",
+];
 
-/** Columns of {@link ZETA_LOGO}. */
-const LOGO_WIDTH = Math.max(...ZETA_LOGO.map(row => row.length));
+/** Secondary identity line: FIGlet `mini` render of `Linxira-Zeta` (generated). */
+export const ZETA_SUBLINE = [
+	"                       __            ",
+	" |  o ._     o ._ _. __ /  _ _|_  _. ",
+	" |_ | | | >< | | (_|   /_ (/_ |_ (_| ",
+];
 
-/**
- * The `Zeta` wordmark in half-blocks, set beside {@link ZETA_LOGO} from its
- * second row: the `Z` is a solid zig-zag closed by a light step, `e`/`a` sit on
- * the x-height, the `t` ascender rises above it, and the version takes the
- * fifth row.
- */
-const WORDMARK = ["███▀         ▄        ", " ██   ███▄  ███   ▄██▄", "▄▄██  █▄▄    █▄   █▄▄█"];
+/** Columns of {@link ZETA_LOGO}. */
+const LOGO_WIDTH = Math.max(...ZETA_LOGO.map(row => visibleWidth(row)));
 
-/** Columns of {@link WORDMARK}. */
-const WORDMARK_WIDTH = Math.max(...WORDMARK.map(row => row.length));
+/** Columns of {@link ZETA_WORDMARK}. */
+const WORDMARK_WIDTH = Math.max(...ZETA_WORDMARK.map(row => visibleWidth(row)));
 
 /** Columns between the logo and the wordmark. */
 const LOCKUP_GAP = 4;
@@ -492,10 +532,22 @@ const TIP_MEASURE = 72;
 /** Narrowest terminal that still shows the tip; below it the banner is the logo alone. */
 const TIP_MIN_COLUMNS = 50;
 
-/** Logo frame `logo` with the wordmark beside it and `version` (styled) under the wordmark. */
+/**
+ * The lockup block: the mark beside the wordmark, `version` (styled) under the
+ * wordmark, and the `Linxira-Zeta` subline centered under the pair.
+ */
 function lockup(logo: readonly string[], version: string): string[] {
-	const beside = ["", ...WORDMARK.map(row => theme.bold(theme.fg("text", row))), version];
-	return logo.map((row, index) => `${row}${padding(LOCKUP_GAP)}${beside[index] ?? ""}`);
+	const beside = [...ZETA_WORDMARK.map(row => theme.bold(theme.fg("text", row))), version];
+	const rows = Math.max(logo.length, beside.length);
+	const art = Array.from({ length: rows }, (_, index) => {
+		const mark = logo[index] ?? "";
+		return `${mark}${padding(LOGO_WIDTH - visibleWidth(mark) + LOCKUP_GAP)}${beside[index] ?? ""}`;
+	});
+	const blockWidth = Math.max(...art.map(line => visibleWidth(line)));
+	for (const row of ZETA_SUBLINE) {
+		art.push(padding(Math.max(0, Math.floor((blockWidth - visibleWidth(row)) / 2))) + theme.fg("dim", row));
+	}
+	return art;
 }
 
 /**
@@ -508,7 +560,7 @@ function centerBlock(lines: readonly string[], width: number): string[] {
 	return lines.map(line => indent + line);
 }
 
-/** The block-grid brand mark as accent lines; `shimmer` declares the terminal-clocked shine sweep. */
+/** The generated brand mark as accent lines; `shimmer` declares the terminal-clocked shine sweep. */
 export function logoNode(lines: readonly string[], shimmer: boolean): NativeNode {
 	return col(
 		lines.map(line =>

package/src/render/code-cell.ts

@@ -8,6 +8,7 @@ import { code, md, span } from "../native/describe";
 import type { NativeNode } from "../native/node";
 import { getMarkdownTheme, highlightCode, type Theme } from "../theme/theme";
 import { formatDuration, formatExpandHint, formatMoreItems, formatStatusIcon, replaceTabs } from "./render-utils";
+import { wrapPrefixedLine } from "./hanging-wrap";
 import {
 	describeOutputBlock,
 	type NativeOutputBlockSection,
@@ -167,6 +168,7 @@ export function renderCodeCell(options: CodeCellOptions, theme: Theme): string[]
 		}
 	}
 
+	const numberedCodeLines: string[] = [];
 	if (lineNumberWidth > 0 && visibleLineNumbers) {
 		for (let i = 0; i < codeLines.length; i++) {
 			const lineNum = visibleLineNumbers[i];
@@ -174,10 +176,14 @@ export function renderCodeCell(options: CodeCellOptions, theme: Theme): string[]
 				lineNum !== null && lineNum !== undefined
 					? String(lineNum).padStart(lineNumberWidth, " ")
 					: " ".repeat(lineNumberWidth);
-			codeLines[i] = theme.fg("dim", `${gutter} `) + codeLines[i];
+			const prefix = theme.fg("dim", `${gutter} `);
+			numberedCodeLines.push(
+				...wrapPrefixedLine(prefix, " ".repeat(lineNumberWidth + 1), codeLines[i]!, outputBlockContentWidth(width)),
+			);
 		}
 	}
 
+	const displayCodeLines = lineNumberWidth > 0 ? numberedCodeLines : codeLines;
 	if (hiddenCodeLines > 0) {
 		const hint = formatExpandHint(theme, expanded, hiddenCodeLines > 0);
 		const gutterPad = lineNumberWidth > 0 ? " ".repeat(lineNumberWidth + 1) : "";
@@ -185,16 +191,16 @@ export function renderCodeCell(options: CodeCellOptions, theme: Theme): string[]
 			// Earlier rows scrolled above the live tail window — mark them on top so
 			// the newest streamed line stays pinned to the bottom of the box.
 			const earlier = `… ${hiddenCodeLines} earlier line${hiddenCodeLines === 1 ? "" : "s"}${hint ? ` ${hint}` : ""}`;
-			codeLines.unshift(theme.fg("dim", gutterPad + earlier));
+			displayCodeLines.unshift(theme.fg("dim", gutterPad + earlier));
 		} else {
 			const moreLine = `${formatMoreItems(hiddenCodeLines, "line")}${hint ? ` ${hint}` : ""}`;
-			codeLines.push(theme.fg("dim", gutterPad + moreLine));
+			displayCodeLines.push(theme.fg("dim", gutterPad + moreLine));
 		}
 	}
 
 	const outputLines = renderCellOutput(output, expanded, outputMaxLines, theme);
 
-	const sections: Array<{ label?: string; lines: readonly string[] }> = [{ lines: codeLines }];
+	const sections: Array<{ label?: string; lines: readonly string[] }> = [{ lines: displayCodeLines }];
 	if (outputLines.length > 0) {
 		sections.push({ label: theme.fg("toolTitle", "Output"), lines: outputLines });
 	}
@@ -252,7 +258,14 @@ export function describeCodeCell(options: Omit<CodeCellOptions, "width">, theme:
 	const sections: NativeOutputBlockSection[] = [
 		{
 			key: "code",
-			body: [code(options.code ?? "", { lang: options.language, start, numbers: start !== undefined || undefined })],
+			body: [
+				code(options.code ?? "", {
+					lang: options.language,
+					start,
+					numbers: start !== undefined || undefined,
+					wrap: true,
+				}),
+			],
 		},
 	];
 	const output = describeCellOutput(options.output, expanded, outputMaxLines);

package/src/render/hanging-wrap.d.ts

@@ -0,0 +1,7 @@
+import type { Theme } from "../theme/theme";
+/** Wrap content under a distinct first-row prefix, preserving its column on continuation rows. */
+export declare function wrapPrefixedLine(prefix: string, continuationPrefix: string, content: string, width: number): string[];
+/** Preserve a tree connector's ancestor guides while hanging a long node beneath its label. */
+export declare function wrapTreeLine(line: string, width: number, theme: Theme): string[] | undefined;
+/** Hang a tree row beneath its connector, or a connector-less detail row beneath its guide rails. */
+export declare function wrapGuidedLine(line: string, width: number, theme: Theme): string[];

package/src/render/hanging-wrap.ts

@@ -0,0 +1,58 @@
+import { visibleWidth, wrapTextWithAnsi } from "../utils";
+import type { Theme } from "../theme/theme";
+
+/** Wrap content under a distinct first-row prefix, preserving its column on continuation rows. */
+export function wrapPrefixedLine(prefix: string, continuationPrefix: string, content: string, width: number): string[] {
+	const prefixWidth = visibleWidth(prefix);
+	const continuationWidth = visibleWidth(continuationPrefix);
+	if (width <= Math.max(prefixWidth, continuationWidth)) return wrapTextWithAnsi(prefix + content, width);
+	const rows = wrapTextWithAnsi(content, width - Math.max(prefixWidth, continuationWidth));
+	return rows.map((row, index) => `${index === 0 ? prefix : continuationPrefix}${row}`);
+}
+
+/** Preserve a tree connector's ancestor guides while hanging a long node beneath its label. */
+export function wrapTreeLine(line: string, width: number, theme: Theme): string[] | undefined {
+	for (const connector of [theme.tree.branch, theme.tree.last]) {
+		const marker = theme.fg("dim", connector);
+		const index = line.indexOf(marker);
+		if (index < 0) continue;
+		const before = line.slice(0, index);
+		if (!/^ *$/.test(Bun.stripANSI(before).replaceAll(theme.tree.vertical, ""))) continue;
+		const end = index + marker.length + 1;
+		if (line[end - 1] !== " ") continue;
+		const connectorWidth = visibleWidth(connector);
+		const guide =
+			connector === theme.tree.last
+				? " ".repeat(connectorWidth)
+				: `${theme.fg("dim", theme.tree.vertical)}${" ".repeat(Math.max(0, connectorWidth - visibleWidth(theme.tree.vertical)))}`;
+		return wrapPrefixedLine(line.slice(0, end), `${before}${guide} `, line.slice(end), width);
+	}
+	return undefined;
+}
+
+const SGR = /\x1b\[[0-9;]*m/y;
+
+/** End of the leading run of spaces, `vertical` guides and SGR escapes that a tree detail row hangs beneath. */
+function guideRunEnd(line: string, vertical: string): number {
+	let index = 0;
+	while (index < line.length) {
+		if (line[index] === " ") {
+			index++;
+		} else if (vertical && line.startsWith(vertical, index)) {
+			index += vertical.length;
+		} else {
+			SGR.lastIndex = index;
+			if (!SGR.test(line)) break;
+			index = SGR.lastIndex;
+		}
+	}
+	return index;
+}
+
+/** Hang a tree row beneath its connector, or a connector-less detail row beneath its guide rails. */
+export function wrapGuidedLine(line: string, width: number, theme: Theme): string[] {
+	const tree = wrapTreeLine(line, width, theme);
+	if (tree) return tree;
+	const prefix = line.slice(0, guideRunEnd(line, theme.tree.vertical));
+	return wrapPrefixedLine(prefix, prefix, line.slice(prefix.length), width);
+}

package/src/render/hyperlink.d.ts

@@ -70,6 +70,8 @@ export declare function urlHyperlinkAlways(url: string, displayText: string): st
  * Non-HTTP(S) or unparsable URLs yield a plain span.
  */
 export declare function urlLinkSpan(target: string, displayText: string, s?: string): TspSpan;
+/** Whether native link spans and nodes may carry an `href`: everything but an explicit `off` policy. */
+export declare function isNativeLinkEnabled(): boolean;
 /**
  * A native link span to a filesystem path as a plain `file://` URI (the
  * terminal opens it through the system; the location stays in the visible

package/src/render/hyperlink.ts

@@ -196,6 +196,11 @@ export function urlLinkSpan(target: string, displayText: string, s = "link"): Ts
 	}
 }
 
+/** Whether native link spans and nodes may carry an `href`: everything but an explicit `off` policy. */
+export function isNativeLinkEnabled(): boolean {
+	return hyperlinkMode !== "off";
+}
+
 /**
  * A native link span to a filesystem path as a plain `file://` URI (the
  * terminal opens it through the system; the location stays in the visible

package/src/render/render-utils.d.ts

@@ -105,14 +105,22 @@ export declare function cappedHeadLines(lines: readonly string[], max: number):
 };
 /** Get the first nonblank preview lines, trimmed and width-capped. */
 export declare function getPreviewLines(text: string, maxLines: number, maxLineLen: number, ellipsis?: Ellipsis): string[];
+/** Collapse a possibly multi-line string into one line; whitespace runs (tabs included) become one space. */
+export declare function flattenLine(text: string): string;
 /**
  * Collapse a possibly multi-line string into a single line, then truncate it to
  * `maxWidth` display cells. {@link truncateToWidth} alone caps width but
  * newlines are zero-width, so multi-line content (markdown briefs, tool args,
  * provider errors) would otherwise spill a single status row across several
- * visual lines. Whitespace runs collapse to one space, so tabs are handled too.
+ * visual lines.
  */
 export declare function previewLine(text: string, maxWidth: number, ellipsis?: Ellipsis): string;
+/**
+ * Clip a result row to `maxWidth` only while collapsed. Expanded rows stay whole
+ * so the frame wraps them: the expand key ({@link formatExpandHint}) must reveal
+ * text, not re-clip it.
+ */
+export declare function clipCollapsed(text: string, maxWidth: number, expanded: boolean | undefined): string;
 /**
  * Extract domain from URL, stripping www. prefix.
  */

package/src/render/render-utils.ts

@@ -233,15 +233,29 @@ export function getPreviewLines(text: string, maxLines: number, maxLineLen: numb
 	return lines.slice(0, maxLines).map(l => truncateToWidth(l.trim(), maxLineLen, ellipsis));
 }
 
+/** Collapse a possibly multi-line string into one line; whitespace runs (tabs included) become one space. */
+export function flattenLine(text: string): string {
+	return text.replace(/\s+/g, " ").trim();
+}
+
 /**
  * Collapse a possibly multi-line string into a single line, then truncate it to
  * `maxWidth` display cells. {@link truncateToWidth} alone caps width but
  * newlines are zero-width, so multi-line content (markdown briefs, tool args,
  * provider errors) would otherwise spill a single status row across several
- * visual lines. Whitespace runs collapse to one space, so tabs are handled too.
+ * visual lines.
  */
 export function previewLine(text: string, maxWidth: number, ellipsis?: Ellipsis): string {
-	return truncateToWidth(text.replace(/\s+/g, " ").trim(), maxWidth, ellipsis);
+	return truncateToWidth(flattenLine(text), maxWidth, ellipsis);
+}
+
+/**
+ * Clip a result row to `maxWidth` only while collapsed. Expanded rows stay whole
+ * so the frame wraps them: the expand key ({@link formatExpandHint}) must reveal
+ * text, not re-clip it.
+ */
+export function clipCollapsed(text: string, maxWidth: number, expanded: boolean | undefined): string {
+	return expanded ? text : truncateToWidth(text, maxWidth);
 }
 
 // =============================================================================

package/src/render/utils.d.ts

@@ -32,7 +32,7 @@ export interface RenderCache {
     lines: string[];
 }
 /** Build indentation and continuing branches for ancestor levels. */
-export declare function buildTreePrefix(ancestors: boolean[], theme: Theme): string;
+export declare function buildTreePrefix(ancestors: readonly boolean[], theme: Theme): string;
 /** Return the branch glyph for a final or continuing tree item. */
 export declare function getTreeBranch(isLast: boolean, theme: Theme): string;
 /** Return the continuation prefix for subsequent lines of a tree item. */

package/src/render/utils.ts

@@ -76,7 +76,7 @@ export interface RenderCache {
 }
 
 /** Build indentation and continuing branches for ancestor levels. */
-export function buildTreePrefix(ancestors: boolean[], theme: Theme): string {
+export function buildTreePrefix(ancestors: readonly boolean[], theme: Theme): string {
 	return ancestors.map(hasNext => (hasNext ? `${theme.tree.vertical}  ` : "   ")).join("");
 }
 

package/src/render/width-aware-text.ts

@@ -25,7 +25,6 @@ export class WidthAwareText implements Component {
 	#cachedContentWidth = -1;
 	#cachedText: string | undefined;
 	#ignoreTight = false;
-	#nativeCols = -1;
 	#native: NativeNode | undefined;
 
 	constructor(format: (contentWidth: number) => string, paddingX = 1, paddingY = 1) {
@@ -71,10 +70,12 @@ export class WidthAwareText implements Component {
 	 * (the only width a describer knows) and again on `reformat()`.
 	 */
 	describe(cx: DescribeContext): NativeNode {
-		if (this.#cachedText === undefined || cx.cols !== this.#nativeCols) {
-			this.#nativeCols = cx.cols;
-			this.#cachedContentWidth = -1;
-			this.#cachedText = this.#format(Math.max(1, cx.cols));
+		// Native describe emits no padding, so the formatter gets the full
+		// column budget — the same width a native Text.describe() would use.
+		const contentWidth = Math.max(1, cx.cols);
+		if (this.#cachedText === undefined || contentWidth !== this.#cachedContentWidth) {
+			this.#cachedContentWidth = contentWidth;
+			this.#cachedText = this.#format(contentWidth);
 			this.#inner.setText(this.#cachedText);
 		}
 		this.#native ??= col([this.#inner]);