@luan.sh/pi-libtui 0.3.8

package/src/diff/structured.ts

@@ -0,0 +1,264 @@
+import { HUNK_HEADER } from "@pierre/diffs";
+import { sanitizeTuiText } from "../content/terminal-text.ts";
+import type {
+	CreateUnifiedDiffModelOptions,
+	UnifiedDiffFile,
+	UnifiedDiffFileInput,
+	UnifiedDiffHunk,
+	UnifiedDiffLine,
+	UnifiedDiffModel,
+} from "./model.ts";
+
+export const DEFAULT_MAX_CHARACTERS = 1_000_000;
+export const DEFAULT_MAX_ROWS = 20_000;
+export const DEFAULT_MAX_FILES = 2_000;
+
+export function createStructuredDiffModel(
+	files: readonly UnifiedDiffFileInput[],
+	revisionOrOptions?: string | CreateUnifiedDiffModelOptions,
+): UnifiedDiffModel {
+	const options = typeof revisionOrOptions === "string" ? { revision: revisionOrOptions } : (revisionOrOptions ?? {});
+	const maxCharacters = positiveInteger(options.maxCharacters, DEFAULT_MAX_CHARACTERS);
+	const budget = new StructuredBudget(maxCharacters, positiveInteger(options.maxRows, DEFAULT_MAX_ROWS));
+	const converted: UnifiedDiffFile[] = [];
+	let additions = 0;
+	let removals = 0;
+	for (const [index, input] of files.slice(0, DEFAULT_MAX_FILES).entries()) {
+		const file = convertFile(input, index, budget);
+		if (!file) break;
+		converted.push(file);
+		additions += file.additions;
+		removals += file.removals;
+		if (budget.truncated) break;
+	}
+	const modelFiles = Object.freeze(converted);
+	return Object.freeze({
+		revision: hash(options.revision ?? JSON.stringify(modelFiles)),
+		files: modelFiles,
+		preamble: Object.freeze([]),
+		additions,
+		removals,
+		sourceRows: budget.rows,
+		truncated:
+			budget.truncated ||
+			budget.characters >= maxCharacters ||
+			Boolean(options.truncated) ||
+			files.length > DEFAULT_MAX_FILES,
+	});
+}
+
+export function hash(value: string): string {
+	let result = 2_166_136_261;
+	for (let index = 0; index < value.length; index += 1) {
+		result ^= value.charCodeAt(index);
+		result = Math.imul(result, 16_777_619);
+	}
+	return (result >>> 0).toString(36);
+}
+
+type StructuredRow = UnifiedDiffFileInput["hunks"][number]["rows"][number];
+
+function convertFile(
+	input: UnifiedDiffFileInput,
+	index: number,
+	budget: StructuredBudget,
+): UnifiedDiffFile | undefined {
+	const fallback = `file-${index}`;
+	const bothPathsMissing = input.oldPath === undefined && input.newPath === undefined;
+	const oldPath = budget.path(bothPathsMissing ? fallback : input.oldPath);
+	const newPath = budget.path(bothPathsMissing ? fallback : input.newPath);
+	const headers = input.headerLines ?? [
+		`--- ${oldPath ? `a/${oldPath}` : "/dev/null"}`,
+		`+++ ${newPath ? `b/${newPath}` : "/dev/null"}`,
+	];
+	const headerLines: string[] = [];
+	for (const header of headers) {
+		const bounded = budget.row(sanitizeTuiText(header), 16_384);
+		if (bounded === undefined) return undefined;
+		headerLines.push(bounded);
+		if (budget.truncated) break;
+	}
+
+	const hunks: UnifiedDiffHunk[] = [];
+	let additions = 0;
+	let removals = 0;
+	for (const [hunkIndex, inputHunk] of input.hunks.entries()) {
+		if (budget.exhausted) {
+			budget.truncate();
+			break;
+		}
+		const hunk = convertHunk(inputHunk, `f${index}:h${hunkIndex}`, budget);
+		if (!hunk) break;
+		hunks.push(hunk);
+		for (const line of hunk.lines) {
+			if (line.kind === "added") additions += 1;
+			if (line.kind === "removed") removals += 1;
+		}
+		if (budget.truncated) break;
+	}
+	return Object.freeze({
+		ref: `f${index}`,
+		oldPath: oldPath || undefined,
+		newPath: newPath || undefined,
+		headerLines: Object.freeze(headerLines),
+		hunks: Object.freeze(hunks),
+		additions,
+		removals,
+	});
+}
+
+function convertHunk(
+	input: UnifiedDiffFileInput["hunks"][number],
+	ref: string,
+	budget: StructuredBudget,
+): UnifiedDiffHunk | undefined {
+	const shape = hunkShape(input);
+	const header = budget.row(
+		cleanLine(
+			input.header ??
+				`@@ -${shape.oldStart ?? 0},${input.oldCount ?? shape.oldRows} +${shape.newStart ?? 0},${input.newCount ?? shape.newRows} @@`,
+		),
+	);
+	if (header === undefined) return undefined;
+
+	const lines: UnifiedDiffLine[] = [];
+	let oldLine = shape.oldStart;
+	let newLine = shape.newStart;
+	for (const row of input.rows) {
+		const prefix = rowPrefix(row.kind);
+		const text = budget.row(`${prefix}${cleanLine(row.text)}`);
+		if (text === undefined) break;
+		const [old, currentNew, nextOld, nextNew] = lineNumbers(row, oldLine, newLine);
+		lines.push(
+			Object.freeze({
+				ref: `${ref}:l${lines.length}`,
+				kind: row.kind,
+				text: text.slice(prefix.length),
+				oldLine: old,
+				newLine: currentNew,
+			}),
+		);
+		oldLine = nextOld;
+		newLine = nextNew;
+		if (budget.truncated) break;
+	}
+	return Object.freeze({
+		ref,
+		header,
+		oldStart: shape.oldStart,
+		oldCount: shape.oldCount,
+		newStart: shape.newStart,
+		newCount: shape.newCount,
+		lines: Object.freeze(lines),
+	});
+}
+
+function hunkShape(input: UnifiedDiffFileInput["hunks"][number]): {
+	readonly oldStart: number | undefined;
+	readonly oldCount: number | undefined;
+	readonly newStart: number | undefined;
+	readonly newCount: number | undefined;
+	readonly oldRows: number;
+	readonly newRows: number;
+} {
+	const header = input.header ? HUNK_HEADER.exec(input.header) : null;
+	let oldStart = input.oldStart ?? headerNumber(header?.[1]);
+	let newStart = input.newStart ?? headerNumber(header?.[3]);
+	let oldRows = 0;
+	let newRows = 0;
+	for (const row of input.rows) {
+		if (row.kind === "context" || row.kind === "removed") {
+			oldRows += 1;
+			oldStart ??= row.oldLine;
+		}
+		if (row.kind === "context" || row.kind === "added") {
+			newRows += 1;
+			newStart ??= row.newLine;
+		}
+	}
+	return {
+		oldStart,
+		oldCount: input.oldCount ?? headerCount(header?.[2], header),
+		newStart,
+		newCount: input.newCount ?? headerCount(header?.[4], header),
+		oldRows,
+		newRows,
+	};
+}
+
+function headerNumber(value: string | undefined): number | undefined {
+	return value === undefined ? undefined : Number(value);
+}
+
+function headerCount(value: string | undefined, header: RegExpExecArray | null): number | undefined {
+	return header === null ? undefined : (headerNumber(value) ?? 1);
+}
+
+function rowPrefix(kind: UnifiedDiffLine["kind"]): string {
+	return kind === "added" ? "+" : kind === "removed" ? "-" : kind === "context" ? " " : "\\";
+}
+
+function lineNumbers(
+	row: StructuredRow,
+	oldLine: number | undefined,
+	newLine: number | undefined,
+): readonly [number | undefined, number | undefined, number | undefined, number | undefined] {
+	if (row.kind === "metadata" || row.kind === "malformed") return [row.oldLine, row.newLine, oldLine, newLine];
+	const old = row.kind === "added" ? row.oldLine : (row.oldLine ?? oldLine);
+	const currentNew = row.kind === "removed" ? row.newLine : (row.newLine ?? newLine);
+	const nextOld = row.kind === "context" || row.kind === "removed" ? increment(old) : oldLine;
+	const nextNew = row.kind === "context" || row.kind === "added" ? increment(currentNew) : newLine;
+	return [old, currentNew, nextOld, nextNew];
+}
+
+function increment(value: number | undefined): number | undefined {
+	return value === undefined ? undefined : value + 1;
+}
+
+function cleanLine(text: string): string {
+	return sanitizeTuiText(text.replace(/\r?\n$/u, ""));
+}
+
+class StructuredBudget {
+	characters = 0;
+	rows = 0;
+	truncated = false;
+
+	constructor(
+		private readonly maxCharacters: number,
+		private readonly maxRows: number,
+	) {}
+
+	get exhausted(): boolean {
+		return this.characters >= this.maxCharacters || this.rows >= this.maxRows;
+	}
+
+	path(value: string | undefined): string | undefined {
+		return value === undefined ? undefined : this.take(sanitizeTuiText(value).slice(0, 4_096), false);
+	}
+
+	row(value: string, maxLength = Number.POSITIVE_INFINITY): string | undefined {
+		return this.take(value.slice(0, maxLength), true);
+	}
+
+	private take(value: string, row: boolean): string | undefined {
+		if (row && this.rows >= this.maxRows) return this.truncate();
+		const separator = row && this.rows > 0 ? 1 : 0;
+		const available = this.maxCharacters - this.characters - separator;
+		if (available <= 0) return this.truncate();
+		const bounded = value.slice(0, available);
+		this.characters += separator + bounded.length;
+		if (row) this.rows += 1;
+		if (bounded.length < value.length) this.truncated = true;
+		return bounded;
+	}
+
+	truncate(): undefined {
+		this.truncated = true;
+		return undefined;
+	}
+}
+
+function positiveInteger(value: number | undefined, fallback: number): number {
+	return value === undefined || !Number.isFinite(value) ? fallback : Math.max(1, Math.floor(value));
+}

package/src/diff/view.ts

@@ -0,0 +1,75 @@
+import type { Component } from "@earendil-works/pi-tui";
+import { loadedDiffHighlighter, whenSyntaxReady } from "../syntax.ts";
+import type { UnifiedDiffModel } from "./model.ts";
+import { type RenderUnifiedDiffOptions, renderUnifiedDiff, type UnifiedDiffViewport } from "./render.ts";
+
+export interface UnifiedDiffViewOptions extends Omit<RenderUnifiedDiffOptions, "width"> {
+	readonly model: UnifiedDiffModel;
+	readonly requestRender?: () => void;
+}
+
+/** Small Pi component wrapper around the pure cached renderer. */
+export class UnifiedDiffView implements Component {
+	private options: UnifiedDiffViewOptions;
+	private renderedSource: readonly string[] | undefined;
+	private renderedLines: string[] | undefined;
+	private omissionRow: number | undefined;
+	private omissionRowHovered = false;
+	private syntaxReadyRequested = false;
+
+	constructor(options: UnifiedDiffViewOptions) {
+		this.options = options;
+		this.omissionRow = undefined;
+	}
+
+	setModel(model: UnifiedDiffModel): void {
+		this.options = { ...this.options, model };
+		this.invalidate();
+	}
+
+	getOmissionRow(): number | undefined {
+		return this.omissionRow;
+	}
+
+	setOmissionRowHovered(hovered: boolean): void {
+		if (this.omissionRowHovered === hovered) return;
+		this.omissionRowHovered = hovered;
+		this.invalidate();
+	}
+
+	setViewport(viewport: UnifiedDiffViewport): void {
+		this.options = { ...this.options, viewport };
+		this.invalidate();
+	}
+
+	render(width: number): string[] {
+		this.requestSyntaxReady();
+		const result = renderUnifiedDiff(this.options.model, {
+			...this.options,
+			width,
+			omissionRowHovered: this.omissionRowHovered,
+		});
+		const source = result.lines;
+		this.omissionRow = result.omissionRow;
+		if (source !== this.renderedSource) {
+			this.renderedSource = source;
+			this.renderedLines = [...source];
+		}
+		return this.renderedLines ?? [];
+	}
+
+	invalidate(): void {
+		this.renderedSource = undefined;
+		this.renderedLines = undefined;
+		this.omissionRow = undefined;
+	}
+
+	private requestSyntaxReady(): void {
+		if (this.syntaxReadyRequested || loadedDiffHighlighter() || !this.options.requestRender) return;
+		this.syntaxReadyRequested = true;
+		whenSyntaxReady(() => {
+			this.invalidate();
+			this.options.requestRender?.();
+		});
+	}
+}

package/src/editor/chrome.ts

@@ -0,0 +1,341 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	CURSOR_MARKER,
+	stripTerminalSequences,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+import { getTuiAppearance } from "../appearance.ts";
+import { BackgroundSurface } from "../background-surface.ts";
+import { type TuiBackgroundToken, tuiTheme } from "../color/theme.ts";
+import { renderPill } from "../decoration/powerline-pill.ts";
+import { animationSmoothnessCadenceMs, animationSpeedMultiplier, pulseGlyphFrame } from "../motion.ts";
+
+export type EditorSurfaceStyle = "transparent" | "base" | "editor" | "raised" | "inset" | "accent";
+export type EditorTopTreatment = "none" | "half-block" | "rule" | "status-band";
+export type EditorBottomTreatment = "none" | "rule";
+export type EditorRailStyle = "off" | "static" | "animated";
+export type EditorPromptMarkerMotion = "static" | "working" | "always";
+export type EditorStatusSeparator = "space" | "dot" | "chevron" | "powerline";
+export type EditorStatusBandStyle = "transparent" | "filled" | "powerline";
+
+export interface EditorCompositionStyle {
+	readonly surface: EditorSurfaceStyle;
+	readonly top: EditorTopTreatment;
+	readonly bottom: EditorBottomTreatment;
+	readonly leftRail: EditorRailStyle;
+	readonly rightRail: EditorRailStyle;
+	readonly promptMarker: readonly string[];
+	readonly promptMarkerMotion: EditorPromptMarkerMotion;
+	readonly bottomStatus: boolean;
+	readonly statusSeparator: EditorStatusSeparator;
+	readonly statusBand: EditorStatusBandStyle;
+	readonly inactiveRailTone: "accent" | "border";
+}
+
+export interface EditorCompositionStatus {
+	readonly left?: string;
+	readonly right?: string;
+}
+
+export interface EditorCompositionRenderOptions {
+	readonly width: number;
+	readonly content: readonly string[];
+	/** Segments rendered in the top-left and top-right regions. */
+	readonly topStatus?: EditorCompositionStatus;
+	readonly active?: boolean;
+	readonly elapsedMs?: number;
+}
+
+export interface EditorCompositionPreview {
+	readonly style: EditorCompositionStyle;
+	readonly prompt?: string;
+	readonly topStatus?: EditorCompositionStatus;
+	readonly bottomStatus?: EditorCompositionStatus;
+}
+
+class Rows implements Component {
+	constructor(private readonly lines: readonly string[]) {}
+	render(width: number): string[] {
+		return this.lines.map((line) => truncateToWidth(line, width, ""));
+	}
+	invalidate(): void {}
+}
+
+function surfaceToken(surface: EditorSurfaceStyle): TuiBackgroundToken | undefined {
+	switch (surface) {
+		case "transparent":
+			return undefined;
+		case "base":
+			return "surface.base";
+		case "editor":
+			return "surface.editor";
+		case "raised":
+			return "surface.raised";
+		case "inset":
+			return "surface.inset";
+		case "accent":
+			return "surface.accent";
+	}
+}
+
+function fit(line: string, width: number): string {
+	const clipped = truncateToWidth(line, Math.max(0, width), "");
+	return `${clipped}${" ".repeat(Math.max(0, width - visibleWidth(clipped)))}`;
+}
+
+function editorContentUsedWidth(line: string): number {
+	const trimmedWidth = visibleWidth(stripTerminalSequences(line).trimEnd());
+	const cursor = line.indexOf(CURSOR_MARKER);
+	const cursorWidth = cursor < 0 ? 0 : visibleWidth(line.slice(0, cursor)) + 1;
+	return Math.max(trimmedWidth, cursorWidth);
+}
+
+function paintRows(theme: Theme, surface: EditorSurfaceStyle, width: number, lines: readonly string[]): string[] {
+	const token = surfaceToken(surface);
+	if (!token) return lines.map((line) => fit(line, width));
+	return new BackgroundSurface({ theme, component: new Rows(lines), background: token }).render(width);
+}
+
+function rail(
+	theme: Theme,
+	style: EditorRailStyle,
+	glyph: string,
+	active: boolean,
+	elapsedMs: number,
+	inactiveTone: "accent" | "border",
+): string {
+	if (style === "off") return "";
+	const colors = tuiTheme(theme);
+	if (style !== "animated" || !active) return colors.fg(inactiveTone, glyph);
+	const appearance = getTuiAppearance();
+	return pulseGlyphFrame(colors, glyph, elapsedMs, {
+		periodMs: 1_600 / animationSpeedMultiplier(appearance.animationSpeed),
+		baseTone: "border",
+		highlightTone: "accent",
+		reducedMotion: false,
+	});
+}
+
+function markerFrame(style: EditorCompositionStyle, active: boolean, elapsedMs: number): string {
+	const frames = style.promptMarker;
+	if (frames.length === 0) return "";
+	const moving = style.promptMarkerMotion === "always" || (style.promptMarkerMotion === "working" && active);
+	if (!moving || frames.length === 1) return frames[0] ?? "";
+	const appearance = getTuiAppearance();
+	const frameMs = Math.max(40, 180 / animationSpeedMultiplier(appearance.animationSpeed));
+	return frames[Math.floor(elapsedMs / frameMs) % frames.length] ?? frames[0] ?? "";
+}
+
+/** Cells removed from Pi's native editor width by the selected chrome. */
+export function editorCompositionContentWidth(style: EditorCompositionStyle, width: number): number {
+	const left = style.leftRail === "off" ? 0 : 2;
+	const right = style.rightRail === "off" ? 0 : 2;
+	const marker = style.promptMarker.length === 0 ? 0 : Math.max(...style.promptMarker.map(visibleWidth)) + 1;
+	return Math.max(1, Math.floor(width) - left - right - marker);
+}
+
+export function editorStatusSeparator(style: EditorStatusSeparator): string {
+	switch (style) {
+		case "space":
+			return " ";
+		case "dot":
+			return " · ";
+		case "chevron":
+			return " > ";
+		case "powerline":
+			return "  ";
+	}
+}
+
+export function composeEditorStatus(left: string, right: string, width: number): string {
+	const safeWidth = Math.max(0, width);
+	if (safeWidth === 0) return "";
+	const fittedRight = truncateToWidth(right, safeWidth, "");
+	if (!left) return `${" ".repeat(Math.max(0, safeWidth - visibleWidth(fittedRight)))}${fittedRight}`;
+	if (!right) return truncateToWidth(left, safeWidth, "");
+	if (visibleWidth(fittedRight) >= safeWidth) return fittedRight;
+	const fittedLeft = truncateToWidth(left, Math.max(0, safeWidth - visibleWidth(fittedRight) - 1), "");
+	const gap = Math.max(1, safeWidth - visibleWidth(fittedLeft) - visibleWidth(fittedRight));
+	return `${fittedLeft}${" ".repeat(gap)}${fittedRight}`;
+}
+
+function statusLine(
+	theme: Theme,
+	style: EditorCompositionStyle,
+	status: EditorCompositionStatus,
+	width: number,
+): string {
+	const left = status.left ?? "";
+	const right = status.right ?? "";
+	if (style.statusBand !== "powerline") return composeEditorStatus(left, right, width);
+	const leftPill = left
+		? renderPill(theme, { label: left, icon: false }, "surface.raised", "text.primary", "surface.base")
+		: "";
+	const rightPill = right
+		? renderPill(theme, { label: right, icon: false }, "surface.raised", "text.primary", "surface.base")
+		: "";
+	return composeEditorStatus(leftPill, rightPill, width);
+}
+
+function ruleLine(theme: Theme, width: number, status?: string): string {
+	const colors = tuiTheme(theme);
+	if (!status) return colors.fg("border", "─".repeat(Math.max(0, width)));
+	const clipped = truncateToWidth(status, Math.max(0, width - 4), "");
+	const remaining = Math.max(0, width - visibleWidth(clipped) - 2);
+	const left = Math.floor(remaining / 2);
+	const right = remaining - left;
+	return `${colors.fg("border", "─".repeat(left))} ${clipped} ${colors.fg("border", "─".repeat(right))}`;
+}
+
+/** Render generic editor chrome around already-rendered native input rows. */
+export function renderEditorComposition(
+	theme: Theme,
+	style: EditorCompositionStyle,
+	options: EditorCompositionRenderOptions,
+): string[] {
+	const width = Math.max(1, Math.floor(options.width));
+	const active = options.active ?? false;
+	const elapsedMs = options.elapsedMs ?? 0;
+	const colors = tuiTheme(theme);
+	const leftWidth = style.leftRail === "off" ? 0 : 2;
+	const rightWidth = style.rightRail === "off" ? 0 : 2;
+	const innerWidth = Math.max(1, width - leftWidth - rightWidth);
+	const markerWidth = style.promptMarker.length === 0 ? 0 : Math.max(...style.promptMarker.map(visibleWidth)) + 1;
+	const marker = markerFrame(style, active, elapsedMs);
+	const topStatus = options.topStatus ?? {};
+	const headerLeft = topStatus.left ?? "";
+	const headerRight = topStatus.right ?? "";
+	const header = headerLeft ? composeEditorStatus(headerLeft, headerRight, innerWidth) : headerRight;
+	const headerWidth = visibleWidth(header);
+	const firstContentUsedWidth = editorContentUsedWidth(options.content[0] ?? "");
+	const inlineHeader =
+		style.top === "half-block" &&
+		headerLeft.length === 0 &&
+		headerWidth > 0 &&
+		markerWidth + firstContentUsedWidth + 2 + headerWidth <= innerWidth;
+	const renderedTopStatus = statusLine(theme, style, topStatus, width);
+	const topRuleStatus = statusLine(theme, style, topStatus, Math.max(1, width - 4));
+	const leftRail = (glyph = "┃") =>
+		style.leftRail === "off" ? "" : `${rail(theme, style.leftRail, glyph, active, elapsedMs, style.inactiveRailTone)} `;
+	const rightRail = (glyph = "┃") =>
+		style.rightRail === "off"
+			? ""
+			: ` ${rail(theme, style.rightRail, glyph, active, elapsedMs, style.inactiveRailTone)}`;
+	const rows = options.content.map((line, index) => {
+		const prefix =
+			markerWidth === 0
+				? ""
+				: `${index === 0 ? colors.fg("accent", marker) : ""}${" ".repeat(Math.max(0, markerWidth - (index === 0 ? visibleWidth(marker) : 0)))}`;
+		let content = `${prefix}${line}`;
+		if (index === 0 && inlineHeader) {
+			const usedWidth = markerWidth + firstContentUsedWidth;
+			content = composeEditorStatus(truncateToWidth(content, usedWidth, ""), header, innerWidth);
+		}
+		return `${leftRail()}${fit(content, innerWidth)}${rightRail()}`;
+	});
+	const paintedRows = paintRows(theme, style.surface, width, rows);
+	const result: string[] = [];
+	if (style.top === "none" && renderedTopStatus) {
+		result.push(
+			...paintRows(theme, style.statusBand === "filled" ? "raised" : "transparent", width, [renderedTopStatus]),
+		);
+	}
+	if (style.top === "half-block") {
+		const token = surfaceToken(style.surface);
+		const capCell = token ? colors.fg(colors.color(token), "▄") : " ";
+		const liftedHeader = inlineHeader ? "" : truncateToWidth(header, Math.max(0, innerWidth - 1), "");
+		const liftedHeaderWidth = visibleWidth(liftedHeader);
+		const fillWidth = Math.max(0, innerWidth - liftedHeaderWidth - (liftedHeader ? 2 : 0));
+		const fill = token
+			? colors.fg(colors.color(token), `${"▄".repeat(fillWidth)}${liftedHeader ? "▟" : ""}`)
+			: " ".repeat(fillWidth);
+		const paintedHeader =
+			token && liftedHeader ? colors.bg(token, ` ${liftedHeader}`) : liftedHeader ? ` ${liftedHeader}` : "";
+		const leftCap =
+			style.leftRail === "off"
+				? ""
+				: `${rail(theme, style.leftRail, "╻", active, elapsedMs, style.inactiveRailTone)}${capCell}`;
+		const rightCap =
+			style.rightRail === "off"
+				? ""
+				: `${liftedHeader && token ? colors.bg(token, " ") : capCell}${rail(
+						theme,
+						style.rightRail,
+						liftedHeader ? "┃" : "╻",
+						active,
+						elapsedMs,
+						style.inactiveRailTone,
+					)}`;
+		result.push(`${leftCap}${fit(`${fill}${paintedHeader}`, innerWidth)}${rightCap}`);
+	} else if (style.top === "rule") {
+		result.push(ruleLine(theme, width, topRuleStatus));
+	} else if (style.top === "status-band" && renderedTopStatus) {
+		result.push(
+			...paintRows(theme, style.statusBand === "transparent" ? "transparent" : "raised", width, [renderedTopStatus]),
+		);
+	}
+	result.push(...paintedRows);
+	if (style.bottom === "rule") result.push(ruleLine(theme, width));
+	return result;
+}
+
+/** Render a standalone status row for Pi's footer mount or an xsettings preview. */
+export function renderEditorCompositionStatus(
+	theme: Theme,
+	style: EditorCompositionStyle,
+	status: EditorCompositionStatus,
+	width: number,
+	options: Pick<EditorCompositionRenderOptions, "active" | "elapsedMs"> = {},
+): string[] {
+	if (!style.bottomStatus) return [];
+	const safeWidth = Math.max(1, Math.floor(width));
+	const leftWidth = style.leftRail === "off" ? 0 : 2;
+	const rightWidth = style.rightRail === "off" ? 0 : 2;
+	const innerWidth = Math.max(1, safeWidth - leftWidth - rightWidth);
+	const line = statusLine(theme, style, status, innerWidth);
+	if (!line) return [];
+	const active = options.active ?? false;
+	const elapsedMs = options.elapsedMs ?? 0;
+	const leftRail =
+		style.leftRail === "off" ? "" : `${rail(theme, style.leftRail, "┃", active, elapsedMs, style.inactiveRailTone)} `;
+	const rightRail =
+		style.rightRail === "off" ? "" : ` ${rail(theme, style.rightRail, "┃", active, elapsedMs, style.inactiveRailTone)}`;
+	const row = `${leftRail}${fit(line, innerWidth)}${rightRail}`;
+	return paintRows(theme, style.surface, safeWidth, [row]);
+}
+
+/** Production composition renderer used by xsettings for candidate previews. */
+export function renderEditorCompositionPreview(
+	theme: Theme,
+	preview: EditorCompositionPreview,
+	width: number,
+	elapsedMs = 720,
+): string[] {
+	const style = preview.style;
+	const prompt = preview.prompt ?? "Ask anything, edit files, run tools";
+	const contentWidth = editorCompositionContentWidth(style, width);
+	const input = [truncateToWidth(prompt, contentWidth, "…")];
+	return [
+		...renderEditorComposition(theme, style, {
+			width,
+			content: input,
+			topStatus: preview.topStatus,
+			active: true,
+			elapsedMs,
+		}),
+		...renderEditorCompositionStatus(theme, style, preview.bottomStatus ?? {}, width, { active: true, elapsedMs }),
+	];
+}
+
+/** Repaint cadence needed by always-moving prompt markers. */
+export function editorCompositionCadenceMs(style: EditorCompositionStyle, active: boolean): number | undefined {
+	const movingMarker =
+		style.promptMarker.length > 1 &&
+		(style.promptMarkerMotion === "always" || (style.promptMarkerMotion === "working" && active));
+	const movingRail = active && (style.leftRail === "animated" || style.rightRail === "animated");
+	if (!movingMarker && !movingRail) return undefined;
+	const appearance = getTuiAppearance();
+	return animationSmoothnessCadenceMs(appearance.animationSmoothness);
+}