@gavin-hu/my-pi-agent 0.8.1 → 0.10.0

package/lib/{tui.ts → tui/chrome.ts}

@@ -18,7 +18,8 @@
 
 import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth, visibleWidth, type EditorTheme, type OverlayOptions } from "@earendil-works/pi-tui";
-import { SEPARATORS } from "./ui.ts";
+import { SEPARATORS } from "./glyphs.ts";
+import { BODY_INDENT } from "./indent.ts";
 
 /**
  * `ctx.ui.custom` options that give a screen the whole terminal.
@@ -36,21 +37,6 @@ export const FULL_SCREEN_OVERLAY: { overlay: true; overlayOptions: OverlayOption
 	overlayOptions: { width: "100%", maxHeight: "100%", anchor: "top-left", margin: 0 },
 };
 
-/**
- * Top border with `label` centered-left, exactly `width` columns wide. When the
- * terminal is too narrow for the title and a border on each side, it degrades to
- * a plain rule rather than truncating the title into an ellipsis.
- */
-export function screenHeader(theme: Theme, width: number, label: string): string {
-	const text = ` ${label} `;
-	const prefix = "───";
-	if (width < visibleWidth(prefix) + visibleWidth(text) + 1) {
-		return theme.fg("borderMuted", "─".repeat(Math.max(0, width)));
-	}
-	const remaining = width - visibleWidth(prefix) - visibleWidth(text);
-	return theme.fg("borderMuted", prefix) + theme.fg("accent", text) + theme.fg("borderMuted", "─".repeat(remaining));
-}
-
 /** A row count, or a live getter so a screen re-sizes with the terminal. */
 export type ViewportRowsSource = number | (() => number | undefined);
 
@@ -80,23 +66,26 @@ export function viewportRows(source: ViewportRowsSource | undefined, options: Vi
 export type ScreenHint = string | { text: string; color?: ThemeColor };
 
 /**
- * A two-space-indented key-hint footer, joined with ` · `. Plain hints are dim;
+ * A key-hint footer indented by `indent` columns (default `BODY_INDENT`, which
+ * hangs it under a screen's title rule), joined with ` · `. Plain hints are dim;
  * an object hint uses its color (dim when omitted). Hints are added while they
  * fit, so a narrow terminal drops whole keys instead of truncating one in half.
  * The first hint is always kept; the result is clipped to `width`.
  */
-export function screenHint(theme: Theme, width: number, hints: ScreenHint[]): string {
+export function screenHint(theme: Theme, width: number, hints: ScreenHint[], indent = BODY_INDENT): string {
 	const target = Math.max(1, width);
+	// Keep a column for the hint itself, however deep the caller indents.
+	const lead = " ".repeat(Math.max(0, Math.min(Math.floor(indent), target - 1)));
 	const render = (hint: ScreenHint): string =>
 		typeof hint === "string" ? theme.fg("dim", hint) : theme.fg(hint.color ?? "dim", hint.text);
 	const separator = theme.fg("dim", SEPARATORS.item);
 	const kept: ScreenHint[] = [];
 	for (const hint of hints) {
 		const candidate = [...kept, hint].map(render).join(separator);
-		if (kept.length > 0 && visibleWidth(`  ${candidate}`) > target) break;
+		if (kept.length > 0 && visibleWidth(`${lead}${candidate}`) > target) break;
 		kept.push(hint);
 	}
-	return truncateToWidth(`  ${kept.map(render).join(separator)}`, target);
+	return truncateToWidth(`${lead}${kept.map(render).join(separator)}`, target);
 }
 
 /**
@@ -105,12 +94,8 @@ export function screenHint(theme: Theme, width: number, hints: ScreenHint[]): st
  * the frame only places them.
  */
 export interface DockListFrame {
-	/** Semantic theme for the header rule and the hint row. */
-	theme: Theme;
-	/** Body width in columns. */
-	width: number;
-	/** The header label, e.g. `Extensions`. */
-	title: string;
+	/** The pre-rendered header line, usually `titleRule(theme, width, title)`. */
+	header: string;
 	/** A summary line under the header; a blank line follows it. */
 	summary?: string;
 	/** The list rows, or the screen's single empty-state line. */
@@ -124,18 +109,16 @@ export interface DockListFrame {
 }
 
 /**
- * Assemble a docked list screen: the `─` header rule, an optional summary and
- * its blank line, the body, an optional range row, optional detail rows, and
+ * Assemble a docked list screen: the caller's header rule, an optional summary
+ * and its blank line, the body, an optional range row, optional detail rows, and
  * the blank-line-padded key-hint footer.
  *
- * This is the convention the bytefly panel (`/bytefly`, and the `/extensions`
- * and `/doctor` aliases) shares with `/jobs` and `/todos`. `/rewind` (a blank
- * after the header and no blank before the hint) places its blanks differently,
- * so it stays hand-rolled rather than changing its output to fit this helper.
+ * This is the convention every docked list screen shares — the bytefly panel,
+ * `/jobs`, `/watch`, `/todos`, `/memory`, and `/rewind`. The header line is built
+ * by the caller (usually `titleRule`), so the frame never picks a rule style.
  */
 export function dockListFrame(frame: DockListFrame): string[] {
-	const width = Math.max(1, frame.width);
-	const lines: string[] = [screenHeader(frame.theme, width, frame.title)];
+	const lines: string[] = [frame.header];
 	if (frame.summary !== undefined) lines.push(frame.summary, "");
 	lines.push(...frame.body);
 	if (frame.range !== undefined) lines.push(frame.range);

package/lib/tui/columns.ts

@@ -0,0 +1,96 @@
+/**
+ * Width arithmetic for the terminal: justify, fit, pad, and clip lines.
+ *
+ * Every function works in terminal columns via `visibleWidth` /
+ * `truncateToWidth`, never string length, and every result fits the width it
+ * was given. Themed strings pass through unchanged except where a cell has to
+ * be clipped, so a color survives every cell that fits.
+ *
+ * Value-only: pure functions over their arguments.
+ */
+
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+/** A usable origin: terminal arithmetic starts from one column, never zero. */
+function columns(width: number): number {
+	return Math.max(1, Math.floor(width));
+}
+
+/** Clip a possibly-themed string to `width` columns, marking a cut with `ellipsis`. */
+export function clip(text: string, width: number, ellipsis = "…"): string {
+	return truncateToWidth(text, columns(width), ellipsis);
+}
+
+/** Pad `text` on the right to exactly `width` columns. Never truncates. */
+export function padTo(text: string, width: number): string {
+	const missing = columns(width) - visibleWidth(text);
+	return missing > 0 ? text + " ".repeat(missing) : text;
+}
+
+/**
+ * Left/right justify on one line: the left cell sits at the margin, the right
+ * cell at the edge, and at least `minGap` columns separate them.
+ *
+ * The right cell is the anchor — it is clipped only after the left cell has
+ * been clipped away — so a value at the end of a line (a model name, a metric)
+ * survives a tight terminal instead of vanishing. An empty right cell means a
+ * plain left-aligned line with no trailing spaces.
+ */
+export function splitRow(left: string, right: string, width: number, minGap = 1): string {
+	const w = columns(width);
+	if (!right) return clip(left, w);
+	const gap = Math.max(0, Math.floor(minGap));
+	const rightCell = clip(right, w);
+	const rightWidth = visibleWidth(rightCell);
+	const leftBudget = w - rightWidth - gap;
+	if (leftBudget <= 0) return rightCell;
+	return padTo(clip(left, leftBudget), w - rightWidth) + rightCell;
+}
+
+/**
+ * Join as many whole cells as fit, dropping trailing cells rather than
+ * clipping one in half. The first cell is always kept, so an over-wide line
+ * degrades to a clipped first cell instead of an empty one.
+ */
+export function fitCells(cells: readonly string[], width: number, separator = " "): string {
+	const w = columns(width);
+	const kept: string[] = [];
+	for (const cell of cells) {
+		const candidate = [...kept, cell].join(separator);
+		if (kept.length > 0 && visibleWidth(candidate) > w) break;
+		kept.push(cell);
+	}
+	return clip(kept.join(separator), w);
+}
+
+/**
+ * Lay atomic, already-themed cells onto lines no wider than `width`.
+ *
+ * Cells are never split: one that would not fit moves to the next line, and one
+ * wider than the whole width is clipped. Use this for a row of independent
+ * tokens (tabs, tags) where `fitCells`' single-line drop would lose one; unlike
+ * {@link fitCells} it may return several lines, and always returns one.
+ */
+export function flowCells(cells: readonly string[], width: number): string[] {
+	const w = columns(width);
+	const lines: string[] = [];
+	let current = "";
+	let currentWidth = 0;
+	for (const cell of cells) {
+		let text = cell;
+		let cellWidth = visibleWidth(cell);
+		if (cellWidth > w) {
+			text = truncateToWidth(cell, w);
+			cellWidth = visibleWidth(text);
+		}
+		if (currentWidth > 0 && currentWidth + cellWidth > w) {
+			lines.push(current);
+			current = "";
+			currentWidth = 0;
+		}
+		current += text;
+		currentWidth += cellWidth;
+	}
+	lines.push(current);
+	return lines;
+}

package/lib/{list-cursor.ts → tui/cursor.ts}

@@ -3,18 +3,23 @@
  * it (`/rewind`, `/todos`, `/jobs`).
  *
  * Each screen keeps its own layout, rows, and selection model — rewind uses an
- * index, jobs use a stable id, todos have no cursor at all — but
+ * index, jobs and watchers use a stable id, todos have no cursor at all — but
  * they all need the same arithmetic: how many rows fit, how to keep the focus
  * in view, which keys navigate, and how to render the "showing X–Y of N" row.
  * That shared part lives here so a fix or a rebinding happens once.
  *
- * No runtime dependencies beyond `lib/tui.ts` and `@earendil-works/pi-tui`; the
+ * `ListCursor` tracks an index, which is right for a list whose shape is the
+ * screen's own. `IdCursor` tracks a stable id, which is right for a list that
+ * is re-sorted from live state on every render.
+ *
+ * No runtime dependencies beyond `lib/tui/chrome.ts` and `@earendil-works/pi-tui`; the
  * theme is passed in and there is no cross-extension state.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
-import { viewportRows, type ViewportRowsSource } from "./tui.ts";
+import { viewportRows, type ViewportRowsSource } from "./chrome.ts";
+import { GLYPHS } from "./glyphs.ts";
 
 /**
  * Rows that fit for a list of `itemCount`, reserving one extra line when the
@@ -71,7 +76,7 @@ export function wheelDelta(event: TuiMouseEvent): number | undefined {
 
 /** The `❯ ` selection marker (accent) or a same-width blank. */
 export function selectionMarker(theme: Theme, selected: boolean): string {
-	return selected ? theme.fg("accent", "❯ ") : "  ";
+	return selected ? theme.fg("accent", `${GLYPHS.prompt} `) : "  ";
 }
 
 /**
@@ -147,6 +152,55 @@ export class ListCursor {
 	}
 }
 
+/**
+ * Cursor and scroll for a list whose order changes under it.
+ *
+ * A live list (jobs, watchers) is re-read and re-sorted on every render, so an
+ * index would silently point at a different row. This cursor remembers the id
+ * of the focused row and re-derives its index against the current items, falling
+ * back to the first row when that id is gone. It is pure state: the screen owns
+ * `requestRender`, and assigns `visible` from {@link fitRows} each render.
+ */
+export class IdCursor {
+	/** Id of the focused row, or `undefined` before the first paint. */
+	id: string | undefined;
+	/** First visible row. */
+	scroll = 0;
+	/** Rows shown at once; the screen sets this before use. */
+	visible = 1;
+
+	/** Index of the focused row, or `0` when its id is gone or the list is empty. */
+	indexOf<T>(items: readonly T[], key: (item: T) => string): number {
+		if (items.length === 0) return 0;
+		const index = this.id === undefined ? -1 : items.findIndex((item) => key(item) === this.id);
+		return index >= 0 ? index : 0;
+	}
+
+	/** Re-anchor the id against the current items; never repaints. */
+	clamp<T>(items: readonly T[], key: (item: T) => string): void {
+		if (items.length === 0) {
+			this.id = undefined;
+			this.scroll = 0;
+			return;
+		}
+		this.id = key(items[this.indexOf(items, key)]);
+		this.scroll = clampScroll(this.scroll, items.length, this.visible);
+	}
+
+	/** Focus the row at `index` (clamped) and scroll it into view. */
+	select<T>(items: readonly T[], key: (item: T) => string, index: number): void {
+		if (items.length === 0) return;
+		const clamped = Math.min(Math.max(0, index), items.length - 1);
+		this.id = key(items[clamped]);
+		this.ensureVisible(clamped);
+	}
+
+	/** Scroll `index` into view without moving the focus. */
+	ensureVisible(index: number): void {
+		this.scroll = Math.max(0, keepVisible(this.scroll, index, this.visible));
+	}
+}
+
 /**
  * Apply a standard navigation key to `cursor`, reporting whether it handled it.
  *

package/lib/tui/gauge.ts

@@ -0,0 +1,78 @@
+/**
+ * The gauge: filled and empty blocks, and the tone they carry.
+ *
+ * One implementation for every bar in the package — the footer's context
+ * meter, a plan's scroll position — so the block glyphs, the floor, and the
+ * tone thresholds cannot drift between surfaces.
+ *
+ * Value-only: pure functions, theme passed in.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { GLYPHS } from "./glyphs.ts";
+import { paint, type TuiRole } from "./tokens.ts";
+
+/** The percentages at which a gauge changes tone. */
+export interface GaugeThresholds {
+	/** Above this (exclusive), the gauge warns. */
+	warn: number;
+	/** Above this (exclusive), the gauge is in error. */
+	danger: number;
+}
+
+/** The package default: warn past 70%, error past 90%. */
+export const DEFAULT_GAUGE_THRESHOLDS: GaugeThresholds = { warn: 70, danger: 90 };
+
+/**
+ * Filled and empty block counts for a percentage across `blocks` cells.
+ *
+ * The fill floors so the bar reads full only at 100%, and forces one block for
+ * any non-zero usage so a small percentage is still visible. A `null` percent
+ * (unknown) fills nothing, leaving the caller to decide whether to draw the
+ * empty track; a known `0` draws it.
+ */
+export function computeGauge(percent: number | null, blocks: number): { filled: number; empty: number } {
+	if (blocks <= 0) return { filled: 0, empty: 0 };
+	if (percent === null) return { filled: 0, empty: blocks };
+	const clamped = Math.max(0, Math.min(100, percent));
+	const filled = Math.max(clamped > 0 ? 1 : 0, Math.floor((clamped / 100) * blocks));
+	return { filled, empty: blocks - filled };
+}
+
+/** The role a context percentage is drawn in. Neutral until it crosses a threshold. */
+export function gaugeRole(percent: number | null, thresholds: GaugeThresholds = DEFAULT_GAUGE_THRESHOLDS): TuiRole {
+	if (percent === null) return "meta";
+	if (percent > thresholds.danger) return "bad";
+	if (percent > thresholds.warn) return "warn";
+	return "meta";
+}
+
+/** A gauge bar's content. */
+export interface GaugeBarOptions {
+	/** The percentage, or `null` when it is unknown. */
+	percent: number | null;
+	/** Cells the track occupies. */
+	blocks: number;
+	/** Override the role instead of deriving it from the thresholds. */
+	role?: TuiRole;
+	/** Role for the empty track. Defaults to the filled role. */
+	emptyRole?: TuiRole;
+	thresholds?: GaugeThresholds;
+}
+
+/**
+ * The colored bar, or `""` when the percentage is unknown.
+ *
+ * Unknown and zero stay distinct: a known `0%` still draws the empty track so
+ * the column does not jump, while an unknown value draws nothing and leaves the
+ * caller to print a muted `?` instead.
+ */
+export function gaugeBar(theme: Theme, options: GaugeBarOptions): string {
+	if (options.percent === null) return "";
+	const { filled, empty } = computeGauge(options.percent, options.blocks);
+	const role = options.role ?? gaugeRole(options.percent, options.thresholds);
+	const emptyRole = options.emptyRole ?? role;
+	const track = filled > 0 ? paint(theme, role, GLYPHS.gaugeFull.repeat(filled)) : "";
+	const rest = empty > 0 ? paint(theme, emptyRole, GLYPHS.gaugeEmpty.repeat(empty)) : "";
+	return track + rest;
+}

package/lib/{ui.ts → tui/glyphs.ts}

@@ -10,14 +10,14 @@
 import { keyText, type Theme } from "@earendil-works/pi-coding-agent";
 
 /**
- * Leading glyphs for status chips and footer segments.
+ * Leading glyphs for status chips, footer segments, and transcript rails.
  *
- * Every glyph is a single terminal column in every profile: narrow or neutral
- * `East_Asian_Width`, never ambiguous, wide, or fullwidth, and never emoji. A
- * CJK-width profile renders an ambiguous glyph two columns wide, which drifts a
- * chip, a rail, or a footer row; `visibleWidth` cannot catch that (it counts an
- * ambiguous character as one column), so `lib/ui.test.ts` checks the width class
- * directly. Add a new glyph only after checking it against `EastAsianWidth.txt`.
+ * A glyph is a single terminal column: never wide, fullwidth, or emoji, which
+ * are two columns in every profile. East-Asian *ambiguous* glyphs are allowed —
+ * a CJK-width profile draws those two columns, so one costs a column there, but
+ * the vocabulary is no longer limited to narrow/neutral characters. Add a glyph
+ * only after checking its `East_Asian_Width` against `EastAsianWidth.txt`;
+ * `lib/tui/glyphs.test.ts` bans wide, fullwidth, and emoji.
  */
 export const GLYPHS = {
 	branch: "⎇",
@@ -34,6 +34,7 @@ export const GLYPHS = {
 	gaugeFull: "▰",
 	gaugeEmpty: "▱",
 	turnRule: "╌",
+	divider: "╎",
 	check: "✓",
 	warn: "!",
 	cross: "✕",
@@ -47,18 +48,16 @@ export const GLYPHS = {
 	boxOff: "◻",
 	prev: "‹",
 	next: "›",
+	prompt: "❯",
 } as const;
 
-/** Columns before a transcript rail body glyph, shared by `goal` and `todo`. */
-export const BODY_INDENT = 2;
-
 /** Columns between a rail body glyph and its text. */
 export const GLYPH_GAP = 1;
 
 /** Padding used to join (`item`) or group (`group`) UI segments. */
 export const SEPARATORS = {
 	item: " · ",
-	group: " │ ",
+	group: ` ${GLYPHS.divider} `,
 } as const;
 
 /** `ctx.ui.setStatus` keys; one per extension that publishes a chip. */

package/lib/tui/indent.ts

@@ -0,0 +1,166 @@
+/**
+ * The transcript indent: how a non-prose block sits under its headline.
+ *
+ * A tool block, a shared notice, and a subagent's quoted output all hang from one
+ * left edge. A block may lead with a headline (a tool's own call line) at the
+ * outer indent; the body sits `BODY_INDENT` further in, directly under it with no
+ * separator line, which is what keeps a tool block compact. The body's first
+ * indent column may instead carry a rail glyph, passed in pre-painted by the
+ * caller so this module stays value-only.
+ *
+ * Value-only: pure functions and constants, no theme.
+ */
+
+import { type Component, stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+/** Columns the body sits in beyond a block's outer indent. */
+export const BODY_INDENT = 2;
+
+/** How an indented block is placed. */
+export interface IndentOptions {
+	/** Columns the body is indented; a headline sits `BODY_INDENT` to its left. */
+	indent?: number;
+	/**
+	 * A pre-painted, one-column rail glyph for the body's first indent column; the
+	 * rest of the indent stays spaces. Ignored below `BODY_INDENT`, where there is
+	 * no column to spare. Default: no rail.
+	 */
+	rail?: string;
+	/**
+	 * Start the rail after the headline's continuation: keep the leading run of
+	 * non-blank body lines plain-indented, up to the first blank line. Set when the
+	 * headline degenerated to the bare subject name (a tool's call line whose path
+	 * moved onto the body), so the rail begins with the result instead of the
+	 * wrapped call. Ignored without a rail. Default false.
+	 */
+	railAfterCall?: boolean;
+	/** Drop leading lines with no visible content. Default false. */
+	trimLeading?: boolean;
+	/** Drop trailing lines with no visible content. Default true. */
+	trimTrailing?: boolean;
+	/**
+	 * Lead with the first non-blank line as the block's headline, at
+	 * `indent - BODY_INDENT`, with the body immediately after it. Default false.
+	 */
+	headline?: boolean;
+	/**
+	 * Suffix appended when a body line is clipped. Default empty: a body is clipped
+	 * silently. The headline always clips with `…`. A notice sets `…` so a
+	 * truncated row reads as truncated.
+	 */
+	bodyClip?: string;
+}
+
+/**
+ * A line with no visible text. Tested after stripping terminal sequences, so a
+ * line that is only spaces carrying a background (a `Box`'s own padding) counts
+ * as blank rather than as content.
+ */
+function isBlank(line: string): boolean {
+	return stripTerminalSequences(line).trim().length === 0;
+}
+
+/** An image-protocol line must pass through unprefixed, or the sequence corrupts. */
+const IMAGE_LINE = /^\u001b(?:P|_G|\]1337;)/;
+
+/** The body indent, clamped so the prefix always leaves at least one column. */
+function clampIndent(indent: number, width: number): number {
+	return Math.max(0, Math.min(Math.floor(indent), Math.max(0, width - 1)));
+}
+
+/**
+ * The body prefix: the rail glyph in the indent's first body column, or plain
+ * spaces. The glyph must be one visible column, so the prefix is exactly `indent`
+ * columns wide; the gap after it is the remaining `BODY_INDENT - 1`.
+ */
+function bodyPrefix(indent: number, rail: string | undefined): string {
+	if (!rail || indent < BODY_INDENT) return " ".repeat(indent);
+	const base = Math.max(0, indent - BODY_INDENT);
+	return `${" ".repeat(base)}${rail}${" ".repeat(indent - base - 1)}`;
+}
+
+/**
+ * Indent each line of an already-rendered block by `indent` columns, clipping
+ * each to `width`. The block should be built at `width - indent` so nothing is
+ * lost to the prefix; the clip is only a safety net. A line carrying an image
+ * protocol sequence is passed through untouched, and trailing lines with no
+ * visible content are dropped (by default). When `headline` is set, the first
+ * non-blank line leads at `indent - BODY_INDENT` and the body follows directly —
+ * no separator line — and its own leading blanks are dropped so a tool's spacing
+ * never leaves a gap under the headline. With `rail` set, the body's first indent
+ * column carries the glyph instead of a space; `railAfterCall` keeps the call's
+ * continuation lines plain, so the rail starts with the result.
+ */
+export function indentBlockLines(body: readonly string[], width: number, options: IndentOptions = {}): string[] {
+	const w = Math.max(1, width);
+	const indent = clampIndent(options.indent ?? 0, w);
+	const prefix = bodyPrefix(indent, options.rail);
+	const plainPrefix = " ".repeat(indent);
+
+	// The headline is the first line with something to say; it leads at the base.
+	let headline: string | undefined;
+	let rest: readonly string[] = body;
+	if (options.headline) {
+		const index = body.findIndex((line) => !IMAGE_LINE.test(line) && !isBlank(line));
+		if (index >= 0) {
+			headline = body[index];
+			rest = body.slice(index + 1);
+		}
+	}
+
+	// A call whose subject moved onto the body keeps those lines unrailed, so the
+	// rail starts with the result rather than under a bare tool name.
+	let railStart = 0;
+	if (options.rail && options.railAfterCall) {
+		while (railStart < rest.length && !isBlank(rest[railStart] ?? "")) railStart++;
+	}
+
+	const lines: string[] = [];
+	const blank: boolean[] = [];
+	for (const [index, line] of rest.entries()) {
+		if (IMAGE_LINE.test(line)) {
+			lines.push(line);
+			blank.push(false);
+			continue;
+		}
+		lines.push(truncateToWidth(`${index < railStart ? plainPrefix : prefix}${line}`, w, options.bodyClip ?? ""));
+		blank.push(isBlank(line));
+	}
+	if (options.trimLeading) {
+		while (blank.length > 0 && blank[0]) {
+			lines.shift();
+			blank.shift();
+		}
+	}
+	if (options.trimTrailing !== false) {
+		while (blank.length > 0 && blank[blank.length - 1]) {
+			lines.pop();
+			blank.pop();
+		}
+	}
+	if (headline !== undefined) {
+		const base = Math.max(0, indent - BODY_INDENT);
+		lines.unshift(truncateToWidth(`${" ".repeat(base)}${headline}`, w, "…"));
+	}
+	return lines;
+}
+
+/**
+ * Render `inner` at the width the indent leaves, so nothing is lost to the
+ * prefix. An absent `inner` renders nothing, so a tool with no output adds no
+ * blank block. The lines are not indented yet; a caller that has to inspect the
+ * block before placing it passes them to `indentBlockLines`.
+ */
+export function bodyLines(inner: Component | undefined, width: number, indent = 0): string[] {
+	if (!inner) return [];
+	const w = Math.max(1, width);
+	const prefixWidth = visibleWidth(bodyPrefix(clampIndent(indent, w), undefined));
+	return inner.render(Math.max(1, w - prefixWidth));
+}
+
+/** Render `inner` at the width the indent leaves, then indent it. */
+export function indentedLines(inner: Component | undefined, width: number, options: IndentOptions = {}): string[] {
+	const w = Math.max(1, width);
+	const indent = clampIndent(options.indent ?? 0, w);
+	return indentBlockLines(bodyLines(inner, w, indent), w, { ...options, indent });
+}

package/lib/tui/index.ts

@@ -0,0 +1,27 @@
+/**
+ * The Bytefly terminal design system: one kit for every interactive surface.
+ *
+ * Import from `lib/tui/index.ts` rather than a leaf module so the surface reads
+ * as one system. The leaves: `tokens.ts` (semantic role -> theme token),
+ * `glyphs.ts` (the shared glyph, separator, and status-key vocabulary),
+ * `chrome.ts` (screen frame, hints, viewport, overlay), `cursor.ts` (list
+ * scroll and navigation), `columns.ts` (width math), `rules.ts` (the rule
+ * grammar), `rows.ts` (list rows, checkboxes, chips, empty states), `gauge.ts`
+ * (the context gauge), `indent.ts` (the transcript block indent), and
+ * `line-pane.ts` (the scrollable log/match pane).
+ *
+ * Value-only, like every `lib/` module: pure functions, constants, and classes,
+ * with no module-level state.
+ */
+
+export * from "./chrome.ts";
+export * from "./columns.ts";
+export * from "./cursor.ts";
+export * from "./gauge.ts";
+export * from "./glyphs.ts";
+export * from "./line-pane.ts";
+export * from "./indent.ts";
+export * from "./rows.ts";
+export * from "./rules.ts";
+export * from "./status-controller.ts";
+export * from "./tokens.ts";