pi-openui 0.1.2 → 0.3.0

package/src/lang/samples.ts

@@ -64,11 +64,20 @@ note = Callout("spark-3 was rebooted on 21 Oct.", "info")`,
 b = Stack([b1, b2], "row")
 b1 = Button("Restart vllm", @ToAssistant("Restart the vllm service on dgx-spark-1"))
 b2 = Button("Drain node")
-ch = Choice("Which model should serve chat?", ["qwen3-32b", "llama-3.3-70b", "gemma-3-27b"], "Pick one; it is sent to the assistant")
+ch = Choice("Which model should serve chat?", ["qwen3-32b", "llama-3.3-70b", "gemma-3-27b"], "I will use it for the next request")
 fq = Faq([q1, q2, q3], true)
 q1 = FaqItem("What does draining do?", "It stops **new** requests and lets running ones finish.\\n\\n1. queue pauses\\n2. in-flight requests complete\\n3. node is marked *drained*")
 q2 = FaqItem("How do I undo it?", "Run \`uncordon\` on the node: it rejoins the pool immediately.")
 q3 = FaqItem("Why did spark-3 reboot?", "A driver update needed it. See the [runbook](https://example.com/runbook).")`,
+	},
+	{
+		key: "choice-card",
+		title: "Choice: several questions, one Send",
+		source: `root = Stack([plan])
+plan = Card([q1, q2, q3], "Before I restart")
+q1 = Choice("Which node should I restart first?", ["web-1", "web-2"])
+q2 = Choice("Which checks should I run?", ["Disk", "Memory", "Network"], null, true)
+q3 = Choice("Clear the cache on db?", ["Yes", "No"], null, null, false)`,
 	},
 	{
 		key: "markdown",
@@ -224,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.` };
+	}
+}