pi-openui 0.2.0 → 0.3.0

package/src/lang/samples.ts

@@ -233,4 +233,138 @@ doc = Markdown("## A picture in the text\\n\\nThe line below is only an image: i
 img = Image("${SAMPLE_PNG_DATA_URI}", "Sunset over the ridge", "Generated test picture, 192x108", [t])
 t = Tooltip("image", "Test picture, drawn by the extension", "Pictures use the terminal's image protocol (Kitty, Ghostty, WezTerm, Warp, herdr). Other terminals get a labelled frame with the file details.", null, null, "info")`,
 	},
+	// ---- Small screens. `/openui-gallery wide` draws these: each is something that does not fit a phone (about 60 columns), and
+	// each shows what it does instead of being cut. Try them in a narrow pane.
+	{
+		key: "wide-table",
+		title: "A wide table: it scrolls, and Host is pinned so a row stays readable",
+		source: `root = Stack([title, t])
+title = Text("Homelab fleet: five columns, Host stays put while the rest scrolls", "heading")
+t = Table(["Host", "OS", "Role", "Tailnet IP", "State"], [["dgx-spark", "Ubuntu 24.04", "Gateway host, LiteLLM", "100.76.148.76", "up"], ["dgx-spark2", "Ubuntu 24.04", "Cluster TP=2 node A", "100.87.121.4", "up"], ["divi-pc-ubuntu", "Ubuntu 24.04", "RTX 5090 workstation", "100.68.119.2", "down 8d"], ["bosgame-m5-ubuntu", "Ubuntu 26.04", "Strix Halo, dual-boot", "100.125.2.9", "down 7d"], ["davids-macbook", "macOS", "Control plane; llm-ctl", "100.123.55.118", "up"]], null, ["Host"])`,
+	},
+	{
+		key: "wide-table-cut",
+		title: "Long cells: one that is cut to fit ends in an ellipsis, tap it to read it whole",
+		source: `root = Stack([title, t])
+title = Text("Three columns fit by squeezing: tap a cell that ends in … to read it all", "heading")
+t = Table(["Service", "Status", "Last event"], [["billing-api-gateway", "degraded", ${JSON.stringify("Rolling restart in progress since 14:02 (owner: platform-team, ticket OPS-4471). Two of three replicas are draining; traffic is shifted to the third.")}], ["auth", "up", "Certificate renewed"], ["search-indexer", "down", ${JSON.stringify("Out of disk on /var/lib/index after the 02:10 compaction. The on-call was paged at 02:14 and the volume was extended at 02:51.")}]])`,
+	},
+	{
+		key: "wide-code",
+		title: "Code with a long line: it scrolls inside its box, [copy] still copies all of it",
+		source: `root = Stack([c])
+c = CodeBlock(${JSON.stringify(`curl -sS -X POST https://api.example.com/v1/chat/completions -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' -d '{"model": "qwen3-235b", "messages": [{"role": "user", "content": "hello"}]}' | jq -r '.choices[0].message.content'\necho done`)}, "bash", "Call the gateway")`,
+	},
+	{
+		key: "wide-tabs",
+		title: "Tabs whose labels do not fit one line: the strip wraps",
+		source: `root = Stack([tabs])
+tabs = Tabs([a, b, c, d, e, f])
+a = TabItem("Infrastructure map", [x1])
+b = TabItem("Inventory table", [x2])
+c = TabItem("Services and ports", [x3])
+d = TabItem("Alerts", [x4])
+e = TabItem("Deployments history", [x5])
+f = TabItem("Settings", [x6])
+x1 = Text("The first tab is selected. Tap another label: every one is whole, and each is a tap target.")
+x2 = Text("Inventory")
+x3 = Text("Services")
+x4 = Text("Alerts")
+x5 = Text("Deployments")
+x6 = Text("Settings")`,
+	},
+	{
+		key: "wide-tiles",
+		title: "A row of tiles and buttons: it wraps onto more rows instead of squeezing them",
+		source: `root = Stack([tiles, actions])
+tiles = Stack([a, b, c, d], "row", "m")
+a = Metric("Requests per second", "1,234,567", "+12% vs last hour", "good")
+b = Metric("p99 latency", "842 ms", "-3%", "bad")
+c = Metric("Error budget remaining", "99.95 %")
+d = Metric("Queue depth", "12,345,678", "+8%", "warn")
+actions = Stack([b1, b2, b3, b4], "row", "s")
+b1 = Button("Restart the vllm service", @ToAssistant("Restart the vllm service"))
+b2 = Button("Drain node", @ToAssistant("Drain the node"))
+b3 = Button("Show logs for the last hour", @ToAssistant("Show the logs for the last hour"))
+b4 = Button("Escalate to on-call", @ToAssistant("Escalate to the on-call engineer"))`,
+	},
+	{
+		key: "wide-infra-map",
+		title: "A wide InfraMap: whole labels, scroll sideways",
+		source: `root = Stack([map])
+map = InfraMap([clients, edge, spark, strix], [l1, l2, l3, l4, l5], "Homelab fleet", "LR")
+clients = InfraZone("Clients", [mbp, mbp2, iphone, ipad])
+edge = InfraZone("Public edge", [cf, caddy], "info")
+spark = InfraZone("DGX Spark fleet", [s1, s2, s3], "good")
+strix = InfraZone("Strix Halo", [bos, evo])
+mbp = InfraNode("mbp", "MacBook Pro", "service", "up", "control plane; llm-ctl")
+mbp2 = InfraNode("mbp2", "MacBook Pro 2", "service", "unknown", "idle 23h")
+iphone = InfraNode("iphone", "iPhone 15 PM", "service", "up")
+ipad = InfraNode("ipad", "iPad mini 6", "service", "unknown")
+cf = InfraNode("cf", "Cloudflare tunnel", "cloud", "up", "ingress for gateway")
+caddy = InfraNode("caddy", "Caddy", "gateway", "up", "reverse proxy; fronts services")
+s1 = InfraNode("s1", "dgx-spark", "service", "up", "LiteLLM, Postgres")
+s2 = InfraNode("s2", "dgx-spark2", "service", "up", "TP=2 half A")
+s3 = InfraNode("s3", "dgx-spark3", "service", "up", "TP=2 half B")
+bos = InfraNode("bos", "bosgame-m5", "service", "down", "Strix Halo")
+evo = InfraNode("evo", "evo-x3", "service", "down", "Strix Halo")
+l1 = InfraLink("mbp", "caddy", "tailnet")
+l2 = InfraLink("iphone", "caddy", "tailnet")
+l3 = InfraLink("cf", "caddy", "tunnel")
+l4 = InfraLink("caddy", "s1", "/v1")
+l5 = InfraLink("s2", "s3", "200G TP", "dashed")`,
+	},
+	{
+		key: "wide-dag",
+		title: "A pipeline with long step names: labels shrink a little, then it scrolls whole",
+		source: `root = Stack([d])
+d = Dag([a, b, c, e, f, g], [["a", "b"], ["b", "c"], ["c", "e"], ["e", "f"], ["f", "g"]], "LR", "Release pipeline")
+a = DagNode("a", "Compile the frontend bundle", "done")
+b = DagNode("b", "Run the unit test suite", "done")
+c = DagNode("c", "Build the docker image", "running")
+e = DagNode("e", "Push to the registry", "pending")
+f = DagNode("f", "Deploy to staging now", "pending")
+g = DagNode("g", "Run the smoke tests live", "pending")`,
+	},
+	{
+		key: "wide-erd",
+		title: "A schema with long field lines: shrunk to fit (down to 30 characters), scrolling only past that",
+		source: `root = Stack([e])
+e = Erd([u, o, li], [r1, r2], "Orders")
+u = Entity("users", ["id uuid PK", "email_verification_token_hash text UNIQUE NOT NULL", "display_name text", "created_at timestamptz"])
+o = Entity("orders", ["id uuid PK", "user_id uuid FK", "total_amount_in_minor_units bigint", "status text"])
+li = Entity("order_line_items_with_a_long_name", ["id uuid PK", "order_id uuid FK", "sku text", "quantity int"])
+r1 = Relation("users", "orders", "1:N", "places")
+r2 = Relation("orders", "order_line_items_with_a_long_name", "1:N", "contains")`,
+	},
+	{
+		key: "wide-sequence",
+		title: "Five participants and long message labels",
+		source: `root = Stack([s])
+s = SequenceDiagram([a, b, c, d, e], [m1, m2, m3, m4], "Checkout", true)
+a = SeqParticipant("a", "Browser", "actor")
+b = SeqParticipant("b", "API gateway", "service")
+c = SeqParticipant("c", "Auth service", "service")
+d = SeqParticipant("d", "Postgres primary", "database")
+e = SeqParticipant("e", "Billing provider", "external")
+m1 = SeqMessage("a", "b", "POST /v1/orders with the cart and a payment token")
+m2 = SeqMessage("b", "c", "verify the session token")
+m3 = SeqMessage("c", "d", "select * from sessions where id = ?")
+m4 = SeqMessage("b", "e", "charge the card, idempotency key attached")`,
+	},
+	{
+		key: "wide-markdown",
+		title: "Markdown with a code fence and a table that are wider than a phone",
+		source: `root = Stack([m])
+m = Markdown(${JSON.stringify("## Rollout notes\n\nRun this on the gateway first, then check the table below:\n\n```bash\nkubectl rollout status deployment/billing-api-gateway --namespace production --timeout=300s && kubectl get pods -l app=billing-api-gateway -o wide\n```\n\n| service | status | region | owner | notes | updated |\n|---|---|---|---|---|---|\n| billing-api-gateway | degraded | us-east-1 | platform team | rolling restart in progress | 2026-11-14 |\n| auth | up | eu-west-2 | identity | certificate renewed | 2026-11-13 |\n\nA word too long for any line: " + "abcdefghij".repeat(8))})`,
+	},
+	{
+		key: "wide-card",
+		title: "A long card title, a callout and a question with long options",
+		source: `root = Stack([c, note, q])
+c = Card([t], "A card title that is much longer than a phone is wide, so it wraps inside the card")
+t = Text("The title is not cut: when it does not fit the border it moves inside as a heading.")
+note = Callout("A callout with a long unbroken word is broken, not cut: ${"averyveryverylongword".repeat(4)} and then the sentence goes on.", "warn")
+q = Choice("Which of these long options would you like the agent to run next on the whole cluster?", ["Restart every service in the staging environment one at a time", "Drain the node and wait for the jobs to finish", "Do nothing"])`,
+	},
 ];

package/src/pi/config.ts

@@ -0,0 +1,185 @@
+// The user's settings for pi-openui: one JSON file next to pi's own, `openui.json` in pi's agent directory.
+//
+//   { "table": { "minColumnWidth": 12 }, "scroll": { "step": 8 } }
+//
+// Why not pi's settings.json: pi documents no place in it for another package's keys and may rewrite the file. Why not a
+// per-project file: pi asks for trust before it reads those, and how wide a screen is belongs to the user, not the project.
+// Everything here takes the file system and the environment as arguments, so the hostile cases are plain tests, and nothing
+// throws on bad input: a bad value is the default plus a sentence the person can act on.
+//
+// A setting is one row of SETTINGS: its place in the file, its environment variable, its range and its default. Adding one is
+// adding a row (and a field to `Settings`); validation, the environment, saving and /openui-config all read the table.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export interface Settings {
+	/** the narrowest a table column is squeezed to before the table scrolls sideways instead */
+	tableMinCol: number;
+	/** cells one tap on a fine arrow (‹ ›) scrolls; the page arrows (« ») scroll three quarters of the pane */
+	scrollStep: number;
+}
+
+export const DEFAULTS: Settings = { tableMinCol: 12, scrollStep: 8 };
+export const TABLE_MIN_COL_RANGE = [4, 40] as const;
+export const SCROLL_STEP_RANGE = [1, 40] as const;
+
+interface Def {
+	/** the dotted name, `section.key` in the file */
+	key: SettingKey;
+	field: keyof Settings;
+	env: string;
+	range: readonly [number, number];
+	what: string;
+}
+export type SettingKey = "table.minColumnWidth" | "scroll.step";
+
+const SETTINGS: Def[] = [
+	{ key: "table.minColumnWidth", field: "tableMinCol", env: "PI_OPENUI_TABLE_MIN_COL", range: TABLE_MIN_COL_RANGE, what: "the narrowest a table column is squeezed to before the table scrolls" },
+	{ key: "scroll.step", field: "scrollStep", env: "PI_OPENUI_SCROLL_STEP", range: SCROLL_STEP_RANGE, what: "cells one tap on a fine arrow scrolls" },
+];
+const def = (key: string): Def | undefined => SETTINGS.find((d) => d.key === key);
+const rangeOf = (d: Def) => `a whole number from ${d.range[0]} to ${d.range[1]}`;
+
+type Env = Record<string, string | undefined>;
+type Source = "default" | "file" | "env";
+
+export interface Parsed {
+	settings: Settings;
+	problems: string[];
+	sources: Record<keyof Settings, Source>;
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** A number into the setting's range. A problem is reported when it had to move. */
+function fit(d: Def, n: number, where: string, problems: string[]): number {
+	const [lo, hi] = d.range;
+	const v = Math.min(hi, Math.max(lo, Math.round(n)));
+	if (v !== Math.round(n)) problems.push(`${where} is ${n}; ${d.key} must be from ${lo} to ${hi}, so ${v} is used`);
+	return v;
+}
+
+/** What the file (already parsed, or undefined when there is none) and the environment say. Never throws. */
+export function parseSettings(raw: unknown, env: Env): Parsed {
+	const problems: string[] = [];
+	const settings: Settings = { ...DEFAULTS };
+	const sources = Object.fromEntries(SETTINGS.map((d) => [d.field, "default"])) as Record<keyof Settings, Source>;
+	if (raw !== undefined && !isObject(raw)) problems.push("openui.json must hold a JSON object, so the defaults are used");
+	for (const d of SETTINGS) {
+		const [section, name] = d.key.split(".");
+		if (isObject(raw)) {
+			const sec = raw[section];
+			if (sec !== undefined && !isObject(sec)) problems.push(`"${section}" in openui.json must be an object, so the defaults for it are used`);
+			else if (isObject(sec) && sec[name] !== undefined) {
+				const v = sec[name];
+				if (typeof v === "number" && Number.isFinite(v)) {
+					settings[d.field] = fit(d, v, `${d.key} in openui.json`, problems);
+					sources[d.field] = "file";
+				} else problems.push(`${d.key} in openui.json must be ${rangeOf(d)}, so ${DEFAULTS[d.field]} is used`);
+			}
+		}
+		const e = env[d.env];
+		if (e !== undefined && e.trim() !== "") {
+			const n = Number(e);
+			if (Number.isFinite(n)) {
+				settings[d.field] = fit(d, n, d.env, problems);
+				sources[d.field] = "env";
+			} else problems.push(`${d.env}="${e}" is not a number, so it is ignored`);
+		}
+	}
+	return { settings, problems: [...new Set(problems)], sources };
+}
+
+export function settingsPath(env: Env = process.env): string {
+	return join(env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent"), "openui.json");
+}
+
+type Read = (path: string, enc: "utf8") => string;
+
+export function loadSettings(env: Env = process.env, read: Read = readFileSync as Read): Parsed & { path: string } {
+	const path = settingsPath(env);
+	let raw: unknown;
+	const extra: string[] = [];
+	try {
+		raw = JSON.parse(read(path, "utf8"));
+	} catch (e) {
+		const code = (e as { code?: string }).code;
+		if (code === "ENOENT") raw = undefined;
+		else if (e instanceof SyntaxError) extra.push(`${path} is not valid JSON, so the defaults are used`);
+		else extra.push(`${path} cannot be read (${code ?? (e as Error).message}), so the defaults are used`);
+	}
+	const parsed = parseSettings(raw, env);
+	return { ...parsed, problems: [...extra, ...parsed.problems], path };
+}
+
+interface Fs {
+	read: Read;
+	write: (path: string, data: string) => void;
+	mkdir: (dir: string) => void;
+}
+const realFs: Fs = { read: readFileSync as Read, write: (p, d) => writeFileSync(p, d), mkdir: (d) => void mkdirSync(d, { recursive: true }) };
+
+/** Set (or, with undefined, remove) one setting, keeping every other key in the file. A file that is not JSON is never overwritten. */
+export function saveSetting(path: string, key: SettingKey, value: number | undefined, fs: Fs = realFs): void {
+	let obj: Record<string, unknown> = {};
+	try {
+		const parsed = JSON.parse(fs.read(path, "utf8"));
+		if (!isObject(parsed)) throw new Error(`${path} is not a JSON object; fix or delete it`);
+		obj = parsed;
+	} catch (e) {
+		const code = (e as { code?: string }).code;
+		if (code !== "ENOENT") {
+			if (e instanceof SyntaxError) throw new Error(`${path} is not valid JSON; fix or delete it`);
+			throw e;
+		}
+	}
+	const [section, name] = key.split(".");
+	const sec = isObject(obj[section]) ? { ...(obj[section] as Record<string, unknown>) } : {};
+	if (value === undefined) delete sec[name];
+	else sec[name] = value;
+	if (Object.keys(sec).length) obj[section] = sec;
+	else delete obj[section];
+	fs.mkdir(dirname(path));
+	fs.write(path, JSON.stringify(obj, null, 2) + "\n");
+}
+
+export interface CommandResult {
+	message: string;
+	level: "info" | "warning" | "error";
+	/** the settings now in force, when the command changed them */
+	settings?: Settings;
+}
+
+/** `/openui-config`: show what is in force, set a setting, or reset one or all. */
+export function runConfigCommand(args: string, env: Env = process.env, fs: Fs = realFs): CommandResult {
+	const words = args.trim().split(/\s+/).filter(Boolean);
+	const path = settingsPath(env);
+	const names = SETTINGS.map((d) => d.key).join(" and ");
+	if (!words.length) {
+		const r = loadSettings(env, fs.read);
+		const lines = SETTINGS.map((d) => `${d.key} = ${r.settings[d.field]} (${r.sources[d.field]}): ${d.what}; ${rangeOf(d)}`);
+		return { level: "info", message: `${lines.join("\n")}\nFile: ${path}. Change one with /openui-config ${SETTINGS[1].key} ${DEFAULTS.scrollStep + 4}, put it back with /openui-config ${SETTINGS[1].key} reset, or reset everything with /openui-config reset.` };
+	}
+	const apply = (changes: Array<[Def, number | undefined]>): CommandResult => {
+		try {
+			for (const [d, v] of changes) saveSetting(path, d.key, v, fs);
+		} catch (e) {
+			return { level: "error", message: (e as Error).message };
+		}
+		const r = loadSettings(env, fs.read);
+		const said = changes.map(([d, v]) => (v === undefined ? `Reset ${d.key} to ${DEFAULTS[d.field]}.` : `Saved ${d.key} = ${v} in ${path}.`)).join(" ");
+		const wins = changes.filter(([d]) => r.sources[d.field] === "env");
+		if (wins.length) return { level: "warning", message: `${said} But ${wins.map(([d]) => d.env).join(" and ")} is set and wins: ${wins.map(([d]) => `${d.key} = ${r.settings[d.field]}`).join(", ")} is in force.`, settings: r.settings };
+		return { level: "info", message: said, settings: r.settings };
+	};
+	if (words[0] === "reset" && words.length === 1) return apply(SETTINGS.map((d) => [d, undefined]));
+	const d = def(words[0]);
+	if (!d) return { level: "error", message: `Unknown setting "${words[0]}". The settings are ${names}: /openui-config ${SETTINGS[0].key} 14, or /openui-config reset.` };
+	const given = words[1];
+	if (given === "reset") return apply([[d, undefined]]);
+	if (given === undefined || !/^\d+$/.test(given)) return { level: "error", message: `${d.key} takes ${rangeOf(d)}${given === undefined ? "" : ` (got "${given}")`}.` };
+	const n = Number(given);
+	if (n < d.range[0] || n > d.range[1]) return { level: "error", message: `${d.key} takes ${rangeOf(d)} (got ${n}).` };
+	return apply([[d, n]]);
+}

package/src/pi/events.ts

@@ -0,0 +1,150 @@
+// What does my terminal app send for a tap, a swipe, a flick? Nobody can see it from outside (pi consumes the bytes), so a widget
+// can record what reaches it: `/openui-events on`, tap and swipe over a widget, `/openui-events show`.
+//
+// It records mouse events, and keys only when they are escape sequences or control keys. What a person types is never written
+// down (a letter is not recorded, a paste is counted but not copied), it switches itself off after five minutes, and the file
+// is bounded.
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+type Env = Record<string, string | undefined>;
+
+export const eventsPath = (env: Env = process.env): string => join(env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent"), "openui-events.log");
+
+/** `press btn=none x=9 y=1`, plus `shift`, `alt`, `ctrl` and `d=<wheel delta>` when there are any. */
+export function describeMouse(ev: any): string {
+	const bits = [`${ev.type} btn=${ev.button} x=${ev.x} y=${ev.y}`];
+	if (ev.shift) bits.push("shift");
+	if (ev.alt) bits.push("alt");
+	if (ev.ctrl) bits.push("ctrl");
+	if (ev.wheelDelta !== undefined) bits.push(`d=${ev.wheelDelta}`);
+	return bits.join(" ");
+}
+
+const escaped = (s: string) =>
+	s.replace(/[\x00-\x1f\x7f]/g, (c) => (c === "\r" ? "\\r" : c === "\n" ? "\\n" : c === "\t" ? "\\t" : `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`));
+
+/** A key worth recording (an escape sequence or a control key), or null for what a person types. A paste is counted, never copied. */
+export function describeKey(data: string): string | null {
+	if (data.startsWith("\x1b[200~")) return `paste (${data.replace(/^\x1b\[200~/, "").replace(/\x1b\[201~$/, "").length} characters, not recorded)`;
+	if (!/^[\x00-\x1f\x7f]/.test(data)) return null;
+	return `key "${escaped(data.length > 24 ? data.slice(0, 24) + "…" : data)}"`;
+}
+
+export interface RecorderOptions {
+	write?: (line: string) => void;
+	path?: string;
+	now?: () => number;
+	minutes?: number;
+	maxLines?: number;
+}
+
+export class Recorder {
+	on = false;
+	count = 0;
+	moves = 0;
+	private startedAt = 0;
+	private readonly opts: RecorderOptions;
+
+	constructor(opts: RecorderOptions = {}) {
+		this.opts = opts;
+	}
+
+	get path(): string {
+		return this.opts.path ?? eventsPath();
+	}
+	private now(): number {
+		return (this.opts.now ?? Date.now)();
+	}
+	/** still recording? Five minutes (or `minutes`) after start it is not. */
+	private live(): boolean {
+		if (this.on && this.now() - this.startedAt > (this.opts.minutes ?? 5) * 60_000) this.on = false;
+		return this.on;
+	}
+	start(): void {
+		this.on = true;
+		this.count = 0;
+		this.moves = 0;
+		this.startedAt = this.now();
+	}
+	stop(): void {
+		this.on = false;
+	}
+	private line(text: string): void {
+		if (!this.live() || this.count >= (this.opts.maxLines ?? 2000)) return;
+		this.count++;
+		const at = new Date(this.now()).toISOString().slice(11, 23);
+		const l = `${at} ${text}\n`;
+		try {
+			if (this.opts.write) this.opts.write(l);
+			else {
+				mkdirSync(dirname(this.path), { recursive: true });
+				appendFileSync(this.path, l);
+			}
+		} catch {
+			/* a diagnostic must never get in the way */
+		}
+	}
+	mouse(ev: any): void {
+		if (!this.live()) return;
+		if (ev?.type === "move") this.moves++; // hover floods a log, and says nothing about a swipe
+		else this.line(describeMouse(ev));
+	}
+	key(data: string): void {
+		if (!this.live()) return;
+		const d = describeKey(data);
+		if (d) this.line(d);
+	}
+	/** what the widget made of the last event */
+	note(text: string): void {
+		this.line(`-> ${text}`);
+	}
+}
+
+export const recorder = new Recorder();
+
+export interface EventsResult {
+	message: string;
+	level: "info" | "warning" | "error";
+}
+
+const TIP = "Tap, swipe and flick over a widget (a mouse event only reaches the widget under it), press an arrow or two, then run /openui-events show.";
+
+/** `/openui-events [on|off|show|clear]` */
+export function runEventsCommand(args: string, r: Recorder = recorder, env: Env = process.env): EventsResult {
+	const word = args.trim().toLowerCase();
+	const path = r.path ?? eventsPath(env);
+	switch (word) {
+		case "":
+			return { level: "info", message: r.on ? `Recording (${r.count} events so far). ${TIP}` : "Off. /openui-events on records what a tap, a swipe or a flick sends, for five minutes." };
+		case "on":
+			r.start();
+			return { level: "info", message: `Recording for five minutes into ${path}. ${TIP}` };
+		case "off":
+			r.stop();
+			return { level: "info", message: `Off. ${r.count} events recorded in ${path}.` };
+		case "clear":
+			try {
+				mkdirSync(dirname(path), { recursive: true });
+				writeFileSync(path, "");
+			} catch (e) {
+				return { level: "error", message: `Cannot clear ${path}: ${(e as Error).message}` };
+			}
+			return { level: "info", message: "Cleared." };
+		case "show": {
+			let text = "";
+			try {
+				text = readFileSync(path, "utf8");
+			} catch {
+				/* nothing yet */
+			}
+			const lines = text.split("\n").filter(Boolean);
+			if (!lines.length) return { level: "info", message: `Nothing recorded yet. ${TIP}` };
+			const tail = lines.slice(-25);
+			return { level: "info", message: `${lines.length} events in ${path} (moves are counted, not logged: ${r.moves}). Last ${tail.length}:\n${tail.join("\n")}` };
+		}
+		default:
+			return { level: "error", message: `Unknown "${args.trim()}". Use /openui-events on, off, show or clear.` };
+	}
+}

package/src/pi/extension.ts

@@ -3,28 +3,32 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { readFileSync } from "node:fs";
-import { compile, LIMITS, reference, type Compiled, type El } from "../lang/library.ts";
+import { fallbackLines } from "../blocks/fallback.ts";
+import { compile, LANG_VERSION, LIMITS, reference, type Compiled, type El } from "../lang/library.ts";
 import { markdownImages } from "../lang/md.ts";
 import { LANG_SAMPLES } from "../lang/samples.ts";
 import { getCapabilities } from "@earendil-works/pi-tui";
+import { loadSettings, runConfigCommand } from "./config.ts";
+import { recorder, runEventsCommand } from "./events.ts";
 import { loadImage } from "./images.ts";
 import { syncWidths } from "./widths.ts";
-import { active, armNewest, confirmDelivery, entryOf, handleKey, hooks, OpenUIWidget, resetAll, toggleNotesNewest } from "./widget.ts";
+import { active, applySettings, armNewest, confirmDelivery, entryOf, handleKey, hooks, OpenUIWidget, resetAll, toggleNotesNewest } from "./widget.ts";
 
 const compiled = new Map<string, Compiled>();
 let compiledChars = 0;
 /** A source is the key, so the cache is bounded by size as well as count: 64 sources at the 100 KB limit would be 6 MB. */
 const CACHE_CHARS = 2_000_000;
-export function compileCached(source: string): Compiled {
-	if (source.length > LIMITS.source) return compile(source); // rejected at once; never kept
-	let c = compiled.get(source);
+export function compileCached(source: string, mode: "strict" | "restore" = "strict", from = 1): Compiled {
+	if (source.length > LIMITS.source) return compile(source, { mode, from }); // rejected at once; never kept
+	const key = `${mode}${mode === "restore" ? from : ""}\u0000${source}`;
+	let c = compiled.get(key);
 	if (!c) {
-		c = compile(source);
+		c = compile(source, { mode, from });
 		if (compiled.size >= 64 || compiledChars + source.length > CACHE_CHARS) {
 			compiled.clear();
 			compiledChars = 0;
 		}
-		compiled.set(source, c);
+		compiled.set(key, c);
 		compiledChars += source.length;
 	}
 	return c;
@@ -57,6 +61,21 @@ export function checkImages(root: El | undefined): string[] {
 	return errs;
 }
 
+/** The language version a stored widget was written under: a whole number from 1, else 1 (older sessions stored none). */
+export const langOf = (details: any): number => (typeof details?.lang === "number" && Number.isInteger(details.lang) && details.lang >= 1 ? details.lang : 1);
+
+/**
+ * A widget read back from a session: compiled in restore mode (an older source keeps drawing), and when even that fails a card with
+ * the reason and the start of the source. Never nothing.
+ */
+function restoredWidget(details: any, id: string, theme: any, mode: "live" | "echo") {
+	const source = String(details?.source ?? "");
+	const lang = langOf(details);
+	const c = compileCached(source, "restore", lang);
+	if (!c.ok || !c.root) return new Text(fallbackLines(source, c.errors, lang).map((l) => theme.fg("warning", l)).join("\n"), 0, 0);
+	return new OpenUIWidget(id, c.root, theme, mode, c.notes);
+}
+
 export default function (pi: ExtensionAPI) {
 	syncWidths(); // our grid must agree with this pi about which characters take two cells
 	hooks.sendLive = (text) => pi.sendUserMessage(text, { deliverAs: "followUp" });
@@ -90,7 +109,7 @@ export default function (pi: ExtensionAPI) {
 			const noPics = hasImage && getCapabilities().images !== "kitty";
 			const note = [...c.warnings, ...(noPics ? ["this terminal cannot show pictures, so each Image is drawn as a labelled frame with its file details"] : [])];
 			const noteText = note.length ? ` Notes: ${note.join("; ")}.` : "";
-			return { content: [{ type: "text" as const, text: `Widget drawn. The user can see and click it in the terminal; do not repeat its contents.${noteText}` }], details: { kind: "widget", source: params.source } };
+			return { content: [{ type: "text" as const, text: `Widget drawn. The user can see and click it in the terminal; do not repeat its contents.${noteText}` }], details: { kind: "widget", source: params.source, lang: LANG_VERSION } };
 		},
 		renderCall(args: any, theme: any) {
 			const n = typeof args?.source === "string" ? args.source.split("\n").length : 0;
@@ -104,26 +123,22 @@ export default function (pi: ExtensionAPI) {
 				return new Text(lines.map((l) => theme.fg("error", l)).join("\n"), 0, 0);
 			}
 			if (result?.details?.kind !== "widget") return new Text(theme.fg("dim", "component reference loaded"), 0, 0);
-			const c = compileCached(String(result.details.source ?? ""));
-			if (!c.ok || !c.root) return new Text(theme.fg("error", "widget could not be restored"), 0, 0);
-			return new OpenUIWidget(ctx.toolCallId, c.root, theme, "live");
+			return restoredWidget(result.details, ctx.toolCallId, theme, "live");
 		},
 	});
 
 	pi.registerMessageRenderer("openui-widget", (message: any, _o: any, theme: any) => {
-		const c = compileCached(String(message.details?.source ?? ""));
-		if (!c.ok || !c.root) return undefined;
-		return new OpenUIWidget(String(message.details.id), c.root, theme, message.details.mode === "live" ? "live" : "echo");
+		return restoredWidget(message.details, String(message.details?.id ?? "w-unknown"), theme, message.details?.mode === "live" ? "live" : "echo");
 	});
 
 	const draw = (source: string, title: string, ctx: any) => {
 		const c = compileCached(source);
 		if (!c.ok) return ctx.ui.notify(`${title}: ${c.errors.slice(0, 3).join(" | ")}`, "error");
-		pi.sendMessage({ customType: "openui-widget", content: `[widget: ${title}]`, display: true, details: { id: `w-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`, source, mode: "echo" } });
+		pi.sendMessage({ customType: "openui-widget", content: `[widget: ${title}]`, display: true, details: { id: `w-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`, source, mode: "echo", lang: LANG_VERSION } });
 	};
 
 	pi.registerCommand("openui-gallery", {
-		description: "Draw one example per OpenUI component (or a key prefix: dashboard, table, tabs, choice, line, pie, radar, image, dag, erd, infra, sequence, geo ...). Clicks echo locally.",
+		description: "Draw one example per OpenUI component, or those whose key starts with a prefix: dashboard, table, tabs, choice, line, pie, radar, image, dag, erd, infra, sequence, geo ... `wide` draws the examples that do not fit a phone (long tables, code, tabs, diagrams). Clicks echo locally.",
 		handler: async (args: string, ctx: any) => {
 			const which = args.trim() || "all";
 			const picked = LANG_SAMPLES.filter((s) => which === "all" || s.key.startsWith(which));
@@ -145,6 +160,23 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerCommand("openui-config", {
+		description: "Show or change pi-openui settings: /openui-config, /openui-config table.minColumnWidth 14, /openui-config reset",
+		handler: async (args: string, ctx: any) => {
+			const r = runConfigCommand(args);
+			if (r.settings) applySettings(r.settings);
+			ctx.ui.notify(r.message, r.level);
+		},
+	});
+
+	pi.registerCommand("openui-events", {
+		description: "See what your terminal sends for a tap, a swipe or a flick over a widget: /openui-events on, try them, /openui-events show (off, clear)",
+		handler: async (args: string, ctx: any) => {
+			const r = runEventsCommand(args);
+			ctx.ui.notify(r.message, r.level);
+		},
+	});
+
 	pi.registerCommand("openui-notes", {
 		description: "Write notes on the newest widget: click an element (or Tab to it and press Enter), type, Enter to save. Then add them to your message.",
 		handler: async (_a: string, ctx: any) => {
@@ -167,10 +199,18 @@ export default function (pi: ExtensionAPI) {
 		confirmDelivery(words);
 	});
 
+	const told = new Set<string>();
 	let unsub: (() => void) | undefined;
 	pi.on("session_start", async (_e: any, ctx: any) => {
 		if (!ctx.hasUI) return;
 		unsub?.();
+		// the user's settings file: read once per session, and a problem in it is said once
+		const loaded = loadSettings();
+		applySettings(loaded.settings);
+		for (const p of loaded.problems) if (!told.has(p)) {
+			told.add(p);
+			ctx.ui.notify(`openui: ${p}`, "warning");
+		}
 		hooks.queued = () => {
 			try {
 				return !!ctx.hasPendingMessages();
@@ -178,7 +218,10 @@ export default function (pi: ExtensionAPI) {
 				return false; // a context from a replaced session
 			}
 		};
-		unsub = ctx.ui.onTerminalInput((data: string) => (handleKey(data) ? { consume: true } : undefined));
+		unsub = ctx.ui.onTerminalInput((data: string) => {
+			recorder.key(data); // only escape sequences and control keys, and only while /openui-events is on
+			return handleKey(data) ? { consume: true } : undefined;
+		});
 		// the note editor is pi's own multi-line editor: Enter saves, Shift+Enter adds a line, Esc cancels
 		hooks.prompt = (title: string, initial: string) => ctx.ui.editor(title, initial);
 		hooks.toEditor = (text: string) => ctx.ui.pasteToEditor(text);
@@ -190,7 +233,9 @@ export default function (pi: ExtensionAPI) {
 					const e = entryOf(active.id);
 					const keys = e?.state.noteMode
 						? "notes: click or Enter writes a note  arrows/Tab move  Shift+Enter picks the parent  Esc leaves"
-						: e?.state.focus
+						: e?.state.focus && e.block?.targets.find((t: any) => t.id === e.state.focus)?.kind === "pan"
+							? "left/right arrows scroll, Shift or PageUp/PageDown a page  Tab next  Esc leave"
+							: e?.state.focus
 							? "arrows move  Tab next  Enter activate  Esc close/leave"
 							: "Tab or arrows select  Enter activate  Esc leave";
 					return [truncateToWidth(theme.fg("accent", " openui ") + theme.fg("dim", keys), w)];