pi-openui 0.0.0-stage → 0.1.0

package/src/blocks/sequence.ts

@@ -0,0 +1,266 @@
+// SequenceDiagram: columns left to right, steps top to bottom.
+import { textWidth, truncateText, type Cell } from "../diagram/canvas.ts";
+import type { El } from "../lang/library.ts";
+import type { Anchor } from "./core.ts";
+import type { Block, Target } from "./types.ts";
+import { cell, fromRows, textCells, wrapText } from "./util.ts";
+
+const ICON: Record<string, string> = { actor: "⚇", service: "◇", database: "◎", queue: "≡", external: "◌" };
+
+type Ev =
+	| { t: "msg"; from: number; to: number; label: string; style: string; id?: string; n: number; depth: number }
+	| { t: "note"; over: number; to?: number; text: string; depth: number }
+	| { t: "open"; kind: string; label: string; depth: number }
+	| { t: "else"; label: string; depth: number }
+	| { t: "close"; depth: number };
+
+export function sequence(el: El, width: number, path: string): { block: Block; anchors: Map<string, Anchor>; overflow: boolean } {
+	const parts: El[] = el.props.participants ?? [];
+	const idx = new Map(parts.map((p, i) => [String(p.props.id), i]));
+	const numbered = el.props.numbered !== false;
+	const anchors = new Map<string, Anchor>();
+	const evs: Ev[] = [];
+	let n = 0;
+	let maxDepth = 0;
+	const walk = (steps: El[], depth: number) => {
+		for (const s of steps ?? []) {
+			if (s.type === "SeqMessage") evs.push({ t: "msg", from: idx.get(s.props.from) ?? 0, to: idx.get(s.props.to) ?? 0, label: String(s.props.label ?? ""), style: s.props.style ?? "sync", id: s.props.id, n: ++n, depth });
+			else if (s.type === "SeqNote") evs.push({ t: "note", over: idx.get(s.props.over) ?? 0, to: s.props.to !== undefined ? idx.get(s.props.to) : undefined, text: String(s.props.text ?? ""), depth });
+			else if (s.type === "SeqGroup") {
+				if (depth >= 3) {
+					walk(s.props.steps, depth);
+					continue;
+				}
+				maxDepth = Math.max(maxDepth, depth + 1);
+				evs.push({ t: "open", kind: s.props.kind, label: String(s.props.label ?? ""), depth });
+				walk(s.props.steps, depth + 1);
+				if (s.props.elseSteps && s.props.elseSteps.length) {
+					evs.push({ t: "else", label: String(s.props.elseLabel ?? ""), depth });
+					walk(s.props.elseSteps, depth + 1);
+				}
+				evs.push({ t: "close", depth });
+			}
+		}
+	};
+	walk(el.props.steps ?? [], 0);
+
+	const layout = (cap: number, headCap: number) => {
+		const heads = parts.map((p) => {
+			const label = truncateText(String(p.props.label ?? ""), headCap);
+			return { label, icon: ICON[p.props.kind ?? "service"] ?? "◇", w: textWidth(label) + 6 };
+		});
+		const gap = heads.slice(1).map((h, i) => Math.ceil((heads[i].w + h.w) / 2) + 2);
+		const lw = (e: Extract<Ev, { t: "msg" }>) => textWidth(truncateText(e.label, cap)) + (numbered ? String(e.n).length + 2 : 0);
+		const spans = evs.filter((e): e is Extract<Ev, { t: "msg" }> => e.t === "msg" && e.from !== e.to).sort((a, b) => Math.abs(a.from - a.to) - Math.abs(b.from - b.to));
+		for (const m of spans) {
+			const lo = Math.min(m.from, m.to);
+			const hi = Math.max(m.from, m.to);
+			const need = lw(m) + 6;
+			let sum = 0;
+			for (let j = lo; j < hi; j++) sum += gap[j];
+			if (sum < need) gap[hi - 1] += need - sum;
+		}
+		let rightExtra = 0;
+		let leftExtra = 0;
+		for (const e of evs) {
+			if (e.t === "msg" && e.from === e.to) {
+				const need = lw(e) + 8;
+				if (e.from < parts.length - 1) gap[e.from] = Math.max(gap[e.from], need);
+				else rightExtra = Math.max(rightExtra, need);
+			} else if (e.t === "note") {
+				const nw = Math.min(30, textWidth(e.text) + 4);
+				const half = Math.ceil(nw / 2) + 2;
+				if (e.to === undefined || e.to === e.over) {
+					if (e.over > 0) gap[e.over - 1] = Math.max(gap[e.over - 1], half + Math.ceil(heads[e.over - 1].w / 2));
+					else leftExtra = Math.max(leftExtra, half);
+					if (e.over < parts.length - 1) gap[e.over] = Math.max(gap[e.over], half + Math.ceil(heads[e.over + 1].w / 2));
+					else rightExtra = Math.max(rightExtra, half);
+				}
+			}
+		}
+		const margin = 2 * maxDepth + 1;
+		const x: number[] = [];
+		x.push(margin + Math.max(Math.ceil(heads[0].w / 2), leftExtra));
+		for (let i = 1; i < parts.length; i++) x.push(x[i - 1] + gap[i - 1]);
+		const total = x[x.length - 1] + Math.max(Math.ceil(heads[heads.length - 1].w / 2), rightExtra) + margin + 1;
+		return { heads, x, total, margin };
+	};
+	let lay = layout(48, 22);
+	for (const [cap, hc] of [[36, 22], [28, 18], [20, 14], [14, 10], [10, 8]] as const) {
+		if (lay.total <= width) break;
+		lay = layout(cap, hc);
+	}
+	const cap = lay.total <= width ? 48 : 10;
+	void cap;
+	const { heads, x, total } = lay;
+	const msgCap = lay.total <= width ? 48 : 10;
+	// rows
+	const H0 = 3;
+	let y = H0;
+	const rowOf: number[] = [];
+	const noteLines: string[][] = [];
+	const noteBox: Array<{ x0: number; x1: number } | null> = [];
+	evs.forEach((e, i) => {
+		rowOf[i] = y;
+		if (e.t === "msg") y += e.from === e.to ? 2 : 2;
+		else if (e.t === "note") {
+			const dx = e.to !== undefined ? Math.abs(x[e.to] - x[e.over]) : 0;
+			const nw = e.to !== undefined && e.to !== e.over ? dx + 5 : Math.min(30, textWidth(e.text) + 4);
+			const x0 = e.to !== undefined && e.to !== e.over ? Math.min(x[e.over], x[e.to]) - 2 : x[e.over] - Math.floor(nw / 2);
+			noteBox[i] = { x0, x1: x0 + nw - 1 };
+			const lines = wrapText(e.text, Math.max(3, nw - 4)).map((r) => r.map((c) => c.ch).join(""));
+			noteLines[i] = lines;
+			y += lines.length + 2;
+		} else y += 1;
+	});
+	const lastRow = y;
+	const height = lastRow + 1;
+	const rows: Cell[][] = Array.from({ length: height }, () => Array.from({ length: total }, () => cell(" ")));
+	const put = (xx: number, yy: number, ch: string, role: string) => {
+		if (yy >= 0 && yy < height && xx >= 0 && xx < total) rows[yy][xx] = cell(ch, role);
+	};
+	const text = (xx: number, yy: number, s: string, role: string) => textCells(s, role).forEach((c, k) => put(xx + k, yy, c.ch, c.role));
+	// lifelines
+	x.forEach((xx) => {
+		for (let r = H0; r <= lastRow; r++) put(xx, r, "┆", "seq.life");
+	});
+	// activation bars
+	const stacks: number[][] = parts.map(() => []);
+	evs.forEach((e, i) => {
+		if (e.t !== "msg" || e.from === e.to) return;
+		const arrow = rowOf[i] + 1;
+		if (e.style === "sync") stacks[e.to].push(arrow);
+		else if (e.style === "return" && stacks[e.from].length) {
+			const s = stacks[e.from].pop()!;
+			for (let r = s; r <= arrow; r++) put(x[e.from], r, "┃", "seq.act");
+		}
+	});
+	stacks.forEach((st, p) => st.forEach((s) => { for (let r = s; r <= lastRow - 1; r++) put(x[p], r, "┃", "seq.act"); }));
+	// headers
+	const targets: Target[] = [];
+	parts.forEach((p, i) => {
+		const h = heads[i];
+		const x0 = x[i] - Math.floor(h.w / 2);
+		put(x0, 0, "╭", "seq.head");
+		put(x0 + h.w - 1, 0, "╮", "seq.head");
+		put(x0, 2, "╰", "seq.head");
+		put(x0 + h.w - 1, 2, "╯", "seq.head");
+		for (let k = 1; k < h.w - 1; k++) {
+			put(x0 + k, 0, "─", "seq.head");
+			put(x0 + k, 2, "─", "seq.head");
+		}
+		put(x0, 1, "│", "seq.head");
+		put(x0 + h.w - 1, 1, "│", "seq.head");
+		put(x[i], 2, "┬", "seq.head");
+		put(x0 + 2, 1, h.icon, "seq.icon");
+		text(x0 + 4, 1, h.label, "seq.title");
+		const rect = { x: x0, y: 0, w: h.w, h: 3 };
+		const id = `seq:${path}:${p.props.id}`;
+		targets.push({ id, kind: "node", rect, label: `${p.props.label} (${p.props.kind ?? "service"})` });
+		anchors.set(String(p.props.id), { rect, targetId: id });
+	});
+	// events
+	const frames: Array<{ open: number; close: number; depth: number; elseRow?: number }> = [];
+	const openStack: number[] = [];
+	evs.forEach((e, i) => {
+		const r = rowOf[i];
+		if (e.t === "msg") {
+			const label = (numbered ? `${e.n}. ` : "") + truncateText(e.label, msgCap);
+			if (e.from === e.to) {
+				const xx = x[e.from];
+				put(xx, r, "├", "seq.arrow");
+				put(xx + 1, r, "─", "seq.arrow");
+				put(xx + 2, r, "─", "seq.arrow");
+				put(xx + 3, r, "╮", "seq.arrow");
+				put(xx + 3, r + 1, "╯", "seq.arrow");
+				put(xx + 2, r + 1, "─", "seq.arrow");
+				put(xx + 1, r + 1, e.style === "async" ? "◁" : "◀", "seq.arrow");
+				text(xx + 5, r, label, "seq.label");
+				if (e.id) anchors.set(e.id, { rect: { x: xx, y: r, w: Math.min(total - xx, textWidth(label) + 6), h: 2 } });
+				return;
+			}
+			const a = x[e.from];
+			const b = x[e.to];
+			const lo = Math.min(a, b);
+			const hi = Math.max(a, b);
+			const dashed = e.style === "return";
+			const ay = r + 1;
+			for (let xx = lo + 1; xx < hi; xx++) put(xx, ay, dashed ? "┄" : "─", "seq.arrow");
+			put(a, ay, a < b ? "├" : "┤", "seq.arrow");
+			const open = e.style !== "sync";
+			put(a < b ? hi - 1 : lo + 1, ay, a < b ? (open ? "▷" : "▶") : open ? "◁" : "◀", "seq.arrow");
+			const span = hi - lo - 1;
+			const lt = truncateText(label, Math.max(1, span - 2));
+			const lx = lo + 1 + Math.max(0, Math.floor((span - textWidth(lt)) / 2));
+			text(lx, r, lt, "seq.label");
+			if (numbered) {
+				const nlen = String(e.n).length + 1;
+				for (let k = 0; k < nlen; k++) if (rows[r][lx + k]) rows[r][lx + k] = cell(rows[r][lx + k].ch, "seq.num");
+			}
+			if (e.id) anchors.set(e.id, { rect: { x: lo, y: r, w: hi - lo + 1, h: 2 } });
+		} else if (e.t === "note") {
+			const b = noteBox[i]!;
+			const lines = noteLines[i];
+			const nw = b.x1 - b.x0 + 1;
+			for (let k = 0; k < lines.length + 2; k++) for (let xx = 0; xx < nw; xx++) put(b.x0 + xx, r + k, " ", "seq.note");
+			put(b.x0, r, "┌", "seq.noteBorder");
+			put(b.x1, r, "┐", "seq.noteBorder");
+			put(b.x0, r + lines.length + 1, "└", "seq.noteBorder");
+			put(b.x1, r + lines.length + 1, "┘", "seq.noteBorder");
+			for (let xx = 1; xx < nw - 1; xx++) {
+				put(b.x0 + xx, r, "─", "seq.noteBorder");
+				put(b.x0 + xx, r + lines.length + 1, "─", "seq.noteBorder");
+			}
+			lines.forEach((ln, k) => {
+				put(b.x0, r + 1 + k, "│", "seq.noteBorder");
+				put(b.x1, r + 1 + k, "│", "seq.noteBorder");
+				text(b.x0 + 2, r + 1 + k, ln, "seq.note");
+			});
+		} else if (e.t === "open") {
+			openStack.push(frames.length);
+			frames.push({ open: r, close: r, depth: e.depth });
+			const f = frames[frames.length - 1];
+			const left = 2 * e.depth;
+			const right = total - 1 - 2 * e.depth;
+			put(left, r, "┌", "seq.group");
+			put(right, r, "┐", "seq.group");
+			for (let xx = left + 1; xx < right; xx++) put(xx, r, "─", "seq.group");
+			text(left + 1, r, ` ${e.kind} `, "seq.groupKind");
+			text(left + 2 + textWidth(e.kind) + 1, r, truncateText(e.label, Math.max(1, right - left - textWidth(e.kind) - 6)), "seq.groupLabel");
+			void f;
+		} else if (e.t === "else") {
+			const f = frames[openStack[openStack.length - 1]];
+			f.elseRow = r;
+			const left = 2 * e.depth;
+			const right = total - 1 - 2 * e.depth;
+			put(left, r, "├", "seq.group");
+			put(right, r, "┤", "seq.group");
+			for (let xx = left + 1; xx < right; xx++) put(xx, r, "╌", "seq.group");
+			if (e.label) text(left + 2, r, ` ${truncateText(e.label, right - left - 6)} `, "seq.groupLabel");
+		} else if (e.t === "close") {
+			const f = frames[openStack.pop()!];
+			f.close = r;
+			const left = 2 * e.depth;
+			const right = total - 1 - 2 * e.depth;
+			put(left, r, "└", "seq.group");
+			put(right, r, "┘", "seq.group");
+			for (let xx = left + 1; xx < right; xx++) put(xx, r, "─", "seq.group");
+		}
+	});
+	for (const f of frames) {
+		const left = 2 * f.depth;
+		const right = total - 1 - 2 * f.depth;
+		for (let r = f.open + 1; r < f.close; r++) {
+			if (r === f.elseRow) continue;
+			put(left, r, "│", "seq.group");
+			put(right, r, "│", "seq.group");
+		}
+	}
+	const title = el.props.title ? [textCells(truncateText(String(el.props.title), total), "chart.title")] : [];
+	const all = [...title, ...rows];
+	const off = title.length;
+	for (const t of targets) t.rect.y += off;
+	for (const [, a] of anchors) a.rect.y += off;
+	return { block: { w: total, rows: all.map((r) => (r.length === total ? r : r.concat(Array.from({ length: total - r.length }, () => cell(" "))))), targets }, anchors, overflow: total > width };
+}
+void fromRows;

package/src/blocks/table.ts

@@ -0,0 +1,70 @@
+import { textWidth, truncateText, type Cell, type Rect } from "../diagram/canvas.ts";
+import type { Block } from "./types.ts";
+import { cell, fromRows, padRow, textCells } from "./util.ts";
+
+export interface TableAnchors {
+	rows: Rect[];
+	cols: Rect[];
+	cells: Rect[][];
+}
+
+const NUMERIC = /^[-+]?[\d.,]+\s*(%|ms|s|kb|mb|gb|tb|x)?$/i;
+
+export function tableBlock(columns: string[], rows: Array<Array<string | number>>, width: number): { block: Block; anchors: TableAnchors } {
+	const n = Math.max(1, columns.length);
+	const str = (v: string | number) => String(v ?? "").replace(/\s+/g, " ").trim();
+	const data = rows.map((r) => columns.map((_, i) => str(r[i] ?? "")));
+	const heads = columns.map(str);
+	const numeric = heads.map((_, i) => data.length > 0 && data.every((r) => r[i] === "" || NUMERIC.test(r[i])));
+	const nat = heads.map((h, i) => Math.max(textWidth(h), ...data.map((r) => textWidth(r[i])), 1));
+	const avail = Math.max(n, width - (3 * n + 1));
+	const w = nat.slice();
+	let sum = w.reduce((a, b) => a + b, 0);
+	while (sum > avail) {
+		let k = 0;
+		for (let i = 1; i < n; i++) if (w[i] > w[k]) k = i;
+		if (w[k] <= 3) break;
+		w[k]--;
+		sum--;
+	}
+	const total = w.reduce((a, b) => a + b, 0) + 3 * n + 1;
+	const line = (l: string, m: string, r: string): Cell[] => {
+		const out: Cell[] = [cell(l, "table.border")];
+		w.forEach((cw, i) => {
+			for (let k = 0; k < cw + 2; k++) out.push(cell("─", "table.border"));
+			out.push(cell(i === n - 1 ? r : m, "table.border"));
+		});
+		return out;
+	};
+	const rowCells = (vals: string[], role: string, align: boolean[]): Cell[] => {
+		const out: Cell[] = [cell("│", "table.border")];
+		vals.forEach((v, i) => {
+			const t = truncateText(v, w[i]);
+			const tw = textWidth(t);
+			const pad = w[i] - tw;
+			out.push(cell(" "));
+			if (align[i]) for (let k = 0; k < pad; k++) out.push(cell(" "));
+			out.push(...textCells(t, role));
+			if (!align[i]) for (let k = 0; k < pad; k++) out.push(cell(" "));
+			out.push(cell(" "), cell("│", "table.border"));
+		});
+		return out;
+	};
+	const out: Cell[][] = [line("┌", "┬", "┐")];
+	out.push(rowCells(heads, "table.head", heads.map(() => false)));
+	out.push(line("├", "┼", "┤"));
+	data.forEach((r) => out.push(rowCells(r, "", numeric)));
+	out.push(line("└", "┴", "┘"));
+	const colX: number[] = [];
+	let x = 1;
+	w.forEach((cw) => {
+		colX.push(x + 1);
+		x += cw + 3;
+	});
+	const anchors: TableAnchors = {
+		cols: w.map((cw, i) => ({ x: colX[i], y: 1, w: cw, h: 1 })),
+		rows: data.map((_, ri) => ({ x: 0, y: 3 + ri, w: total, h: 1 })),
+		cells: data.map((_, ri) => w.map((cw, i) => ({ x: colX[i], y: 3 + ri, w: cw, h: 1 }))),
+	};
+	return { block: fromRows(total, out.map((r) => padRow(r, total))), anchors };
+}

package/src/blocks/types.ts

@@ -0,0 +1,126 @@
+import type { Cell, Rect } from "../diagram/canvas.ts";
+import type { El } from "../lang/library.ts";
+
+export interface Tip {
+	hint?: string;
+	detail?: string;
+	code?: string;
+	language?: string;
+	tone?: string;
+	link?: string;
+	linkLabel?: string;
+}
+
+export type TargetKind =
+	| "tab"
+	| "button"
+	| "choice"
+	| "faq"
+	| "node"
+	| "copy"
+	| "tip"
+	| "image"
+	/** something a note can be attached to (see notes.ts); only reachable in notes mode */
+	| "item"
+	/** a row of the notes tray */
+	| "note"
+	| "noteadd"
+	| "noteclear"
+	/** the footer chip that turns notes mode on and off */
+	| "notes";
+
+/** What a note says about the element it is attached to. All words are already cleaned for a message the user will send. */
+export interface ItemInfo {
+	/** the element's path in the tree: items of one component share it */
+	host: string;
+	type: string;
+	/** the variable the component was defined under */
+	name?: string;
+	/** the tooltip vocabulary key ("row:3", "a>b"), or "" for the whole component */
+	key: string;
+	/** where inside the component, in words: `row 3, cell "CrashLoop"` */
+	where: string;
+	/** a short label for the hover line and the tray: `Table > row 3` */
+	short: string;
+	/** the tab it sits under */
+	tab?: string;
+	/** source line, to identify a component that has no variable */
+	line: number;
+	/** the item that contains this one (a table cell's row, a column's table), by target id */
+	parent?: string;
+}
+
+export interface Note {
+	id: number;
+	itemId: string;
+	info: ItemInfo;
+	text: string;
+}
+
+/** Something the user can click or reach with the keyboard. Rects are relative to the block that owns them. */
+export interface Target {
+	id: string;
+	kind: TargetKind;
+	rect: Rect;
+	label: string;
+	tip?: Tip;
+	/** text sent to the assistant when activated */
+	send?: string;
+	openUrl?: string;
+	copy?: string;
+	/** extra cells (block coordinates) that belong to the target besides its rect, e.g. the wedge of a pie slice */
+	cells?: Array<[number, number]>;
+	/** for kind "item": what a note on it is about */
+	item?: ItemInfo;
+	/** for kind "note": the note this tray row shows */
+	noteId?: number;
+	/** for kind "image": where the picture goes and how big it is, in cells */
+	image?: { key: string; cols: number; rows: number };
+	/** a diagram that may be wider than its view: focusing this target should reveal it */
+	pan?: { key: string; x: number; w: number; view: number; total: number };
+}
+
+export interface Block {
+	w: number;
+	rows: Cell[][];
+	targets: Target[];
+}
+
+export interface WState {
+	tab: Record<string, number>;
+	faq: Record<string, boolean>;
+	picked: Record<string, string>;
+	pan: Record<string, number>;
+	tip: string | null;
+	focus: string | null;
+	hover: string | null;
+	copied: string | null;
+	/** the user's notes on this widget, in the order they were written */
+	notes: Note[];
+	/** notes mode: clicks and Enter write notes instead of acting */
+	noteMode: boolean;
+	noteSeq: number;
+}
+
+export const newState = (): WState => ({ tab: {}, faq: {}, picked: {}, pan: {}, tip: null, focus: null, hover: null, copied: null, notes: [], noteMode: false, noteSeq: 0 });
+
+/** Supplied by the host when it can draw bitmaps. Without it, an Image is drawn as a labelled frame. */
+export interface ImageService {
+	/** Load the image and reserve a size for it. Null when it cannot be drawn here (no protocol, unreadable, unsupported). */
+	place(src: string, maxCols: number, maxRows: number): { key: string; cols: number; rows: number } | null;
+	/** Human text for the frame when the picture itself cannot be shown, e.g. "800×600 png, 120 KB". */
+	describe(src: string): string;
+}
+
+export interface Services {
+	images?: ImageService;
+}
+
+export interface Ctx {
+	state: WState;
+	warnings: string[];
+	services: Services;
+	/** labels of the tabs the element being drawn sits under, outermost first */
+	tabs: string[];
+	render: (el: El, width: number, path: string) => Block;
+}

package/src/blocks/util.ts

@@ -0,0 +1,171 @@
+// Layout helpers for blocks: rows of cells with a fixed width.
+import { cell, EMPTY, gWidth, graphemes, textWidth, truncateText, type Cell, type Rect } from "../diagram/canvas.ts";
+import type { Block, Target } from "./types.ts";
+
+export { cell, EMPTY };
+
+export function textCells(s: string, role = ""): Cell[] {
+	const out: Cell[] = [];
+	for (const g of graphemes(s)) {
+		const w = gWidth(g);
+		if (w === 0) continue;
+		out.push(cell(g, role));
+		if (w === 2) out.push(cell("", role));
+	}
+	return out;
+}
+
+export function padRow(row: Cell[], w: number): Cell[] {
+	if (row.length === w) return row;
+	if (row.length > w) {
+		const cut = row.slice(0, w);
+		if (cut.length && cut[cut.length - 1].ch !== "" && w < row.length && row[w].ch === "") cut[cut.length - 1] = EMPTY;
+		return cut;
+	}
+	return row.concat(Array.from({ length: w - row.length }, () => EMPTY));
+}
+
+export const blank = (w: number, h: number): Block => ({ w, rows: Array.from({ length: h }, () => Array.from({ length: w }, () => EMPTY)), targets: [] });
+
+export function fromRows(w: number, rows: Cell[][], targets: Target[] = []): Block {
+	return { w, rows: rows.map((r) => padRow(r, w)), targets };
+}
+
+export interface Run {
+	t: string;
+	role: string;
+}
+
+/** Word-wrap styled runs to `width` columns. Explicit "\n" starts a new line. */
+export function wrapRuns(runs: Run[], width: number): Cell[][] {
+	width = Math.max(1, width);
+	const lines: Cell[][] = [[]];
+	let col = 0;
+	const cur = () => lines[lines.length - 1];
+	const newline = () => {
+		lines.push([]);
+		col = 0;
+	};
+	for (const run of runs) {
+		const parts = run.t.split("\n");
+		parts.forEach((part, pi) => {
+			if (pi > 0) newline();
+			// split into words and spaces
+			for (const tok of part.match(/\s+|\S+/g) ?? []) {
+				const isSpace = /^\s+$/.test(tok);
+				const tw = textWidth(tok);
+				if (isSpace) {
+					if (col === 0 || col + tw > width) continue; // no leading spaces, no trailing overflow
+					cur().push(...textCells(tok, run.role));
+					col += tw;
+					continue;
+				}
+				if (col + tw > width && col > 0) {
+					// trim one trailing space
+					while (cur().length && cur()[cur().length - 1].ch === " ") cur().pop();
+					newline();
+				}
+				if (tw <= width) {
+					cur().push(...textCells(tok, run.role));
+					col += tw;
+				} else {
+					// break a long word
+					for (const g of graphemes(tok)) {
+						const gw = gWidth(g);
+						if (col + gw > width) newline();
+						cur().push(...textCells(g, run.role));
+						col += gw;
+					}
+				}
+			}
+		});
+	}
+	while (lines.length > 1 && lines[lines.length - 1].length === 0) lines.pop();
+	for (const l of lines) while (l.length && l[l.length - 1].ch === " ") l.pop();
+	return lines;
+}
+
+export const wrapText = (s: string, width: number, role = ""): Cell[][] => wrapRuns([{ t: s, role }], width);
+
+export function shiftTargets(ts: Target[], dx: number, dy: number): Target[] {
+	return ts.map((t) => ({ ...t, rect: { ...t.rect, x: t.rect.x + dx, y: t.rect.y + dy }, ...(t.cells ? { cells: t.cells.map(([x, y]) => [x + dx, y + dy] as [number, number]) } : {}) }));
+}
+
+export function vstack(blocks: Block[], gap: number, w?: number): Block {
+	const width = w ?? Math.max(0, ...blocks.map((b) => b.w));
+	const rows: Cell[][] = [];
+	const targets: Target[] = [];
+	blocks.forEach((b, i) => {
+		if (!b.rows.length) return;
+		if (rows.length && gap > 0) for (let g = 0; g < gap; g++) rows.push(Array.from({ length: width }, () => EMPTY));
+		targets.push(...shiftTargets(b.targets, 0, rows.length));
+		for (const r of b.rows) rows.push(padRow(r, width));
+		void i;
+	});
+	return { w: width, rows, targets };
+}
+
+export function hstack(blocks: Block[], gap: number): Block {
+	const h = Math.max(0, ...blocks.map((b) => b.rows.length));
+	const w = blocks.reduce((a, b, i) => a + b.w + (i ? gap : 0), 0);
+	const rows: Cell[][] = Array.from({ length: h }, () => []);
+	const targets: Target[] = [];
+	let x = 0;
+	blocks.forEach((b, i) => {
+		if (i) for (const r of rows) for (let g = 0; g < gap; g++) r.push(EMPTY);
+		for (let y = 0; y < h; y++) rows[y].push(...(b.rows[y] ?? Array.from({ length: b.w }, () => EMPTY)));
+		targets.push(...shiftTargets(b.targets, x, 0));
+		x += b.w + gap;
+	});
+	return { w, rows, targets };
+}
+
+export interface BoxOpts {
+	title?: string;
+	role: string;
+	titleRole?: string;
+	/** text drawn in the top border on the right */
+	tag?: string;
+	tagRole?: string;
+	padX?: number;
+	dashed?: boolean;
+}
+
+/** Wrap a block in a rounded box. `inner` is placed with padX columns of padding. Returns the boxed block. */
+export function boxed(inner: Block, opts: BoxOpts): Block {
+	const padX = opts.padX ?? 1;
+	const w = inner.w + 2 + 2 * padX;
+	const role = opts.role;
+	const hz = opts.dashed ? "╌" : "─";
+	const vt = opts.dashed ? "╎" : "│";
+	const top: Cell[] = [cell("╭", role)];
+	for (let i = 0; i < w - 2; i++) top.push(cell(hz, role));
+	top.push(cell("╮", role));
+	if (opts.title) {
+		const t = truncateText(opts.title, Math.max(1, w - 6 - (opts.tag ? textWidth(opts.tag) + 2 : 0)));
+		const cells = textCells(` ${t} `, opts.titleRole ?? role);
+		for (let i = 0; i < cells.length && 2 + i < w - 1; i++) top[2 + i] = cells[i];
+	}
+	if (opts.tag) {
+		const cells = textCells(` ${opts.tag} `, opts.tagRole ?? role);
+		const start = w - 2 - cells.length;
+		for (let i = 0; i < cells.length; i++) if (start + i > 1) top[start + i] = cells[i];
+	}
+	const rows: Cell[][] = [top];
+	for (const r of inner.rows) rows.push([cell(vt, role), ...Array.from({ length: padX }, () => EMPTY), ...padRow(r, inner.w), ...Array.from({ length: padX }, () => EMPTY), cell(vt, role)]);
+	rows.push([cell("╰", role), ...Array.from({ length: w - 2 }, () => cell(hz, role)), cell("╯", role)]);
+	return { w, rows, targets: shiftTargets(inner.targets, 1 + padX, 1) };
+}
+
+export const rectOf = (x: number, y: number, w: number, h: number): Rect => ({ x, y, w, h });
+
+export function textBlock(s: string, width: number, role = ""): Block {
+	const lines = wrapText(s, width, role);
+	return fromRows(width, lines);
+}
+
+export function lineOf(parts: Array<[string, string]>, w: number): Cell[] {
+	const out: Cell[] = [];
+	for (const [t, r] of parts) out.push(...textCells(t, r));
+	return padRow(out, w);
+}