pi-openui 0.1.2 → 0.3.0

package/src/pi/extension.ts

@@ -3,27 +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 { active, armNewest, entryOf, handleKey, hooks, OpenUIWidget, resetAll, toggleNotesNewest } from "./widget.ts";
+import { syncWidths } from "./widths.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;
@@ -56,7 +61,23 @@ 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" });
 	hooks.sendEcho = (text) => pi.sendMessage({ customType: "openui-click", content: `[widget click → assistant] ${text}`, display: true });
 
@@ -64,14 +85,14 @@ export default function (pi: ExtensionAPI) {
 		name: "render_widget",
 		label: "render_widget",
 		description:
-			"Draw an interactive widget in the terminal: dashboards, tables, charts (bar, line, area, pie, radar), diagrams (DAG, ER, infrastructure map, sequence), maps, tabs, buttons and choices. Pass OpenUI Lang as `source`. Call with reference=true once to get the component signatures. Clicking a Button or Choice sends its text back to you as the user's next message.",
+			"Draw an interactive widget in the terminal: dashboards, tables, charts (bar, line, area, pie, radar), diagrams (DAG, ER, infrastructure map, sequence), maps, tabs, buttons and choices. Pass OpenUI Lang as `source`. Call with reference=true once to get the component signatures. A Button click sends its text back to you as the user's next message. Choice answers are staged and arrive together as one message when the user presses Send answers.",
 		promptSnippet: "render_widget: draw an interactive terminal widget (dashboards, charts, diagrams) from OpenUI Lang",
 		promptGuidelines: [
 			"Before the first render_widget call in a session, call render_widget with reference=true to read the component signatures. Never guess a signature.",
 			"After render_widget succeeds, reply with at most one short sentence. Do not repeat the widget's data in prose.",
 			"If render_widget returns errors, fix exactly the errors listed and call it again with the full corrected source.",
 			"Use plain text, not a widget, for a single value or a short answer. One widget per reply: use Tabs or Card to organise sections.",
-			"A click on a widget Button or Choice arrives as your next user message: act on it, then render a NEW widget if needed.",
+			"A Button click arrives as your next user message: act on it, then render a NEW widget if needed. Choice answers arrive together as ONE message after the user presses Send answers, so ask all your questions in one widget (a Card or Tabs), then act on the answers.",
 		],
 		parameters: Type.Object({
 			source: Type.Optional(Type.String({ description: "OpenUI Lang source: root = Stack([...]) first, one statement per line" })),
@@ -88,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;
@@ -102,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, 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));
@@ -143,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) => {
@@ -157,11 +191,37 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	// pi reports every user message it takes, whoever sent it: that is how a widget learns its answers were delivered
+	pi.on("message_start", async (event: any) => {
+		const m = event?.message;
+		if (m?.role !== "user") return;
+		const words = typeof m.content === "string" ? m.content : Array.isArray(m.content) ? m.content.filter((p: any) => p?.type === "text").map((p: any) => p.text).join("") : "";
+		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?.();
-		unsub = ctx.ui.onTerminalInput((data: string) => (handleKey(data) ? { consume: true } : undefined));
+		// 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();
+			} catch {
+				return false; // a context from a replaced session
+			}
+		};
+		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);
@@ -173,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)];

package/src/pi/widget.ts

@@ -2,14 +2,18 @@
 import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 import { drawBubble } from "../blocks/bubble.ts";
 import { BADGE } from "../blocks/core.ts";
-import { activate, describe, nextTarget, reveal, targetAt, type Env, type NavKey } from "../blocks/interact.ts";
+import { activate, describe, nextTarget, panKey, readingOrder, reveal, targetAt, type Env, type NavKey } from "../blocks/interact.ts";
+import { otherLength, setOther } from "../blocks/choice.ts";
 import { buildMessage, cleanNote, NOTE_LIMITS, widgetTitle } from "../blocks/notes.ts";
+import { Recognizer } from "../blocks/gesture.ts";
 import { renderTree } from "../blocks/render.ts";
 import { newState, type Block, type Note, type Target, type WState } from "../blocks/types.ts";
 import { cell, padRow, textCells } from "../blocks/util.ts";
 import { rowsToLines, textWidth, truncateText, type Cell } from "../diagram/canvas.ts";
 import { createPalette } from "../diagram/palette.ts";
-import type { El } from "../lang/library.ts";
+import { LIMITS, type El } from "../lang/library.ts";
+import { DEFAULTS, type Settings } from "./config.ts";
+import { recorder as defaultRecorder, type Recorder } from "./events.ts";
 import { imageService } from "./images.ts";
 
 const GUTTER = 2;
@@ -68,12 +72,33 @@ interface Entry {
 	warnings: string[];
 	notice: string | null;
 	noticeTimer: ReturnType<typeof setTimeout> | null;
+	/** answers handed to pi, waiting for its word that it took them (see watchDelivery) */
+	pending: { text: string; timer: ReturnType<typeof setTimeout> | null } | null;
 	/** the finished lines and what they were drawn from: pi asks for them on every frame, so an unchanged widget answers from here */
 	lines: string[] | null;
 	lineKey: string;
+	/** what the pointer is doing to a clipped block (flicks, the thumb, the tap that follows a flick) */
+	gesture: Recognizer;
+	/** what was changed to draw this widget from an older source (see compile's restore mode); shown as one quiet line */
+	notes: string[];
 }
 
 const entries = new Map<string, Entry>();
+let settings: Settings = { ...DEFAULTS };
+/** what reaches a widget is recorded when /openui-events is on; tests swap it */
+let recorder: Recorder = defaultRecorder;
+export const setRecorder = (r: Recorder): void => void (recorder = r);
+export const currentSettings = (): Settings => settings;
+/** The user's settings changed (the file was read, or /openui-config wrote it): every widget is drawn again. */
+export function applySettings(next: Settings): void {
+	if (next.tableMinCol === settings.tableMinCol && next.scrollStep === settings.scrollStep) return;
+	settings = { ...next };
+	for (const e of entries.values()) {
+		e.version++;
+		e.lines = null;
+	}
+	hooks.requestRender();
+}
 export const active: { id: string | null } = { id: null };
 export const newestId: { id: string | null } = { id: null };
 /** A dialog (the note editor) is open: our key and mouse handlers stand down so its keys are its own. */
@@ -84,6 +109,10 @@ export const hooks = {
 	requestRender: () => {},
 	sendLive: (_text: string) => {},
 	sendEcho: (_text: string) => {},
+	/** Is pi holding messages for later (the agent is busy and a follow-up is queued)? Then a message it has not shown yet is not lost. */
+	queued: (): boolean => false,
+	/** How long to wait for pi to say it took the answers before giving the widget back. */
+	deliveryMs: 3000,
 	/** Ask the user for the text of a note. Resolves undefined when they cancel. */
 	prompt: async (_title: string, _initial: string): Promise<string | undefined> => undefined,
 	/** Put text in pi's message box without sending it. */
@@ -108,7 +137,7 @@ imageService.onLate = () => {
 function getEntry(id: string, root: El, mode: Mode): Entry {
 	let e = entries.get(id);
 	if (!e) {
-		e = { root, state: newState(), mode, block: null, key: "", version: 0, warnings: [], notice: null, noticeTimer: null, lines: null, lineKey: "" };
+		e = { root, state: newState(), mode, block: null, key: "", version: 0, warnings: [], notice: null, noticeTimer: null, pending: null, lines: null, lineKey: "", gesture: new Recognizer(), notes: [] };
 		entries.set(id, e);
 		newestId.id = id;
 	}
@@ -117,7 +146,11 @@ function getEntry(id: string, root: El, mode: Mode): Entry {
 
 function envFor(id: string, e: Entry): Env {
 	return {
-		send: (t) => (e.mode === "live" ? hooks.sendLive(t) : hooks.sendEcho(t)),
+		send: (t, o) => {
+			if (e.mode !== "live") return hooks.sendEcho(t); // a local echo is delivered when it is shown
+			if (o?.confirm) watchDelivery(id, e, t); // before sending, so a pi that confirms at once finds it waiting
+			hooks.sendLive(t);
+		},
 		copy: (t) => hooks.copy(t),
 		note: (t) => setNotice(id, t),
 	};
@@ -152,6 +185,62 @@ function afterActivate(id: string, e: Entry, t: Target, layoutChanged: boolean)
 	void id;
 }
 
+// ---------- delivery ----------
+
+/**
+ * pi.sendUserMessage returns nothing and swallows its failures (no model selected, no credentials, a compaction in progress), so
+ * "sent" cannot be assumed: a widget that said Sent and locked would leave the user with no way to send again once they have fixed
+ * what pi complained about. The answers are marked as sending until pi reports the user message (message_start, see
+ * confirmDelivery). If it does not within hooks.deliveryMs, and pi is not holding a message for later, the widget is given back
+ * with its answers and says why.
+ */
+function watchDelivery(id: string, e: Entry, text: string): void {
+	if (e.pending?.timer) clearTimeout(e.pending.timer);
+	e.state.sending = true;
+	const pending: NonNullable<Entry["pending"]> = { text, timer: null };
+	e.pending = pending;
+	const check = () => {
+		if (e.pending !== pending) return;
+		let held = false;
+		try {
+			held = hooks.queued();
+		} catch {
+			/* pi's context went stale: treat it as not held */
+		}
+		if (held) return void (pending.timer = later(check)); // the agent is busy: pi has it queued and will show it after the turn
+		e.pending = null;
+		e.state.sent = false;
+		e.state.sending = false;
+		e.version++;
+		setNotice(id, "pi did not take the answers. Fix what it says above, then Send again.");
+		hooks.requestRender();
+	};
+	pending.timer = later(check);
+}
+const later = (f: () => void) => {
+	const t = setTimeout(f, Math.max(1, hooks.deliveryMs));
+	if (typeof (t as any).unref === "function") (t as any).unref();
+	return t;
+};
+
+/**
+ * pi reported a user message with this text: the oldest widget waiting for it has been delivered. One message confirms one widget,
+ * so two widgets that sent the same words are each confirmed by their own message.
+ */
+export function confirmDelivery(text: string): boolean {
+	const want = text.trim();
+	for (const e of entries.values()) {
+		if (!e.pending || e.pending.text.trim() !== want) continue;
+		if (e.pending.timer) clearTimeout(e.pending.timer);
+		e.pending = null;
+		e.state.sending = false;
+		e.version++;
+		hooks.requestRender();
+		return true;
+	}
+	return false;
+}
+
 // ---------- notes ----------
 
 const chipLabel = (s: WState) => (s.noteMode ? "[ notes: on ]" : s.notes.length ? `[ notes ${s.notes.length} ]` : "[ notes ]");
@@ -228,6 +317,29 @@ function clearNotes(id: string, e: Entry) {
 	hooks.requestRender();
 }
 
+// ---------- choices ----------
+
+/**
+ * The Other row of a Choice. The user types their own answer in pi's editor (the one Notes uses), never inside the widget: an
+ * armed widget must not keep letters. Saved text selects Other, empty text unselects it, Esc changes nothing.
+ */
+async function editOther(id: string, e: Entry, t: Target): Promise<void> {
+	const x = t.choice;
+	if (!x || dialog.open || e.state.sent) return;
+	dialog.open = true;
+	let text: string | undefined;
+	try {
+		text = await hooks.prompt(`Your own answer: ${truncateText(x.of.question, 60)}`, e.state.answers[x.of.key]?.text ?? "");
+	} finally {
+		dialog.open = false;
+	}
+	if (text === undefined || e.state.sent) return; // cancelled (the sent check is defence: nothing can send while the editor owns the keys)
+	if (otherLength(text) > LIMITS.other) setNotice(id, `Answer shortened to ${LIMITS.other} characters.`);
+	e.state.answers = setOther(e.state.answers, x.of, text);
+	e.version++;
+	hooks.requestRender();
+}
+
 /** One place for what a click or Enter does, so the mouse and the keyboard cannot drift apart. */
 function perform(id: string, e: Entry, t: Target, shift = false): void {
 	switch (t.kind) {
@@ -249,9 +361,26 @@ function perform(id: string, e: Entry, t: Target, shift = false): void {
 		case "noteclear":
 			clearNotes(id, e);
 			return;
+		case "choice":
+			if (t.choice?.index === "other") {
+				void editOther(id, e, t).catch(() => {
+					// the editor could not open (pi's context went stale): leave the answers as they were
+					setNotice(id, "The editor could not be opened.");
+					hooks.requestRender();
+				});
+				return;
+			}
+			break;
 	}
 	const changed = activate(t, e.state, envFor(id, e));
 	afterActivate(id, e, t, changed);
+	// The button that was pressed is gone from the next picture. Focus must not be left pointing at it: Enter would find nothing
+	// and fall through to the first element of the widget, and that can be a Button that sends a message.
+	if (t.kind === "send" && e.state.sent) {
+		// a locked widget has nothing left to hold the keyboard for: Enter is pi's again, to send the user's own message
+		e.state.focus = null;
+		if (active.id === id) active.id = null;
+	} else if (t.kind === "clear" && e.block) e.state.focus = readingOrder(e.block).find((x) => x.kind === "choice")?.id ?? null;
 }
 
 // ---------- the component ----------
@@ -270,12 +399,12 @@ export class OpenUIWidget {
 	private pal: ReturnType<typeof themePalette> | null = null;
 	private root: El;
 	private mode: Mode;
-	constructor(id: string, root: El, theme: any, mode: Mode) {
+	constructor(id: string, root: El, theme: any, mode: Mode, notes: string[] = []) {
 		this.id = id;
 		this.theme = theme;
 		this.root = root;
 		this.mode = mode;
-		getEntry(id, root, mode);
+		getEntry(id, root, mode).notes = notes;
 	}
 
 	private layout(width: number): Entry {
@@ -283,7 +412,7 @@ export class OpenUIWidget {
 		const e = getEntry(this.id, this.root, this.mode);
 		const key = `${width}:${e.version}`;
 		if (!e.block || e.key !== key) {
-			const r = renderTree(e.root, width, e.state, { images: imageService });
+			const r = renderTree(e.root, width, e.state, { images: imageService, settings });
 			let block = r.block;
 			// a footer row with the notes chip, when there is anything to attach a note to
 			if (block.targets.some((t) => t.kind === "item")) {
@@ -404,6 +533,7 @@ export class OpenUIWidget {
 			imageRows.add(t.rect.y);
 		}
 		for (const w of e.warnings) lines.push(th.fg("warning", `! ${w}`));
+		if (e.notes.length) lines.push(th.fg("dim", `(redrawn by a newer version of the extension: ${e.notes.length} change${e.notes.length === 1 ? "" : "s"}. ${e.notes[0]})`));
 		const armed = active.id === this.id;
 		const edgeFor = (y: number) => (gutter.has(y) ? th.fg("accent", "┃") + " " : armed ? th.fg("accent", "▎") + " " : "  ");
 		return lines.map((l, i) => (imageRows.has(i) ? edgeFor(i) + l : truncateToWidth(edgeFor(i) + l, width)));
@@ -421,24 +551,41 @@ export class OpenUIWidget {
 		const e = entries.get(this.id);
 		if (!e || !e.block || dialog.open) return undefined;
 		const t = targetAt(e.block, ev.x - GUTTER, ev.y, e.state.noteMode);
+		recorder.mouse(ev);
+		const act = e.gesture.feed({ type: ev.type, button: ev.button, x: ev.x - GUTTER, y: ev.y, shift: !!ev.shift, alt: !!ev.alt, wheelDelta: ev.wheelDelta }, e.block, e.state.pan);
+		if (act.kind !== "none") recorder.note(act.kind === "pan" ? `pan to ${act.to}${act.capture ? " (dragging the thumb)" : ""}` : act.kind === "tap" ? `tap at ${act.x},${act.y} (after a flick)` : "a click already handled as a tap");
+		if (act.kind === "pan") {
+			if ((e.state.pan[act.key] ?? 0) !== act.to) {
+				e.state.pan[act.key] = act.to;
+				e.version++;
+			}
+			hooks.requestRender();
+			return act.capture ? { handled: true, render: true, capture: true } : { handled: true, render: true };
+		}
+		if (act.kind === "swallow") return { handled: true };
+		if (act.kind === "tap") return this.click(e, t, ev);
 		if (ev.type === "move") {
 			const id = t?.id ?? null;
 			if (id === e.state.hover) return undefined;
 			e.state.hover = id;
 			return { handled: !!t, render: true };
 		}
-		if (ev.type === "click" && ev.button === "left" && t) {
-			active.id = this.id;
-			e.state.focus = t.id;
-			setNotice(this.id, null);
-			perform(this.id, e, t, !!ev.shift);
-			if (reveal(t, e.state)) e.version++;
-			hooks.requestRender();
-			return { handled: true, render: true };
-		}
+		if (ev.type === "click" && ev.button === "left") return this.click(e, t, ev);
 		return undefined;
 	}
 
+	/** A click, or a tap the recognizer found for pi (see gesture.ts). */
+	private click(e: Entry, t: Target | null, ev: any) {
+		if (!t) return undefined;
+		active.id = this.id;
+		e.state.focus = t.id;
+		setNotice(this.id, null);
+		perform(this.id, e, t, !!ev.shift);
+		if (reveal(t, e.state)) e.version++;
+		hooks.requestRender();
+		return { handled: true, render: true };
+	}
+
 	/** pi calls this when the theme, the cell size or a converter changes: the colours (and a picture's size) are stale. */
 	invalidate() {
 		this.pal = null;
@@ -482,6 +629,13 @@ function keyInner(data: string): boolean {
 		hooks.requestRender();
 		return true;
 	}
+	// the pan bar is focused: Shift+arrow, PageUp and PageDown scroll a page (the plain arrows, below, a fine step)
+	const page = matchesKey(data, Key.shift("left")) || matchesKey(data, Key.pageUp) ? "left" : matchesKey(data, Key.shift("right")) || matchesKey(data, Key.pageDown) ? "right" : null;
+	if (page && panKey(block, e.state, e.state.focus, page, true)) {
+		e.version++;
+		hooks.requestRender();
+		return true;
+	}
 	let nav: NavKey | null = null;
 	if (matchesKey(data, Key.tab)) nav = "next";
 	else if (matchesKey(data, Key.shift("tab"))) nav = "prev";
@@ -490,6 +644,12 @@ function keyInner(data: string): boolean {
 	else if (matchesKey(data, Key.up)) nav = "up";
 	else if (matchesKey(data, Key.down)) nav = "down";
 	if (nav) {
+		// the pan bar is focused: Left and Right scroll instead of moving the focus
+		if ((nav === "left" || nav === "right") && panKey(block, e.state, e.state.focus, nav)) {
+			e.version++;
+			hooks.requestRender();
+			return true;
+		}
 		const t = nextTarget(block, e.state.focus, nav, notes);
 		if (!t) return false;
 		e.state.focus = t.id;
@@ -500,7 +660,15 @@ function keyInner(data: string): boolean {
 		return true;
 	}
 	if (matchesKey(data, Key.enter) || matchesKey(data, Key.shift("enter"))) {
-		const t = block.targets.find((x) => x.id === e.state.focus) ?? nextTarget(block, null, "next", notes);
+		const focused = e.state.focus ? block.targets.find((x) => x.id === e.state.focus) : undefined;
+		if (e.state.focus && !focused) {
+			// the focused element is gone (a button removes itself when it is pressed): never press another one in its place
+			e.state.focus = null;
+			e.state.hover = null;
+			hooks.requestRender();
+			return true;
+		}
+		const t = focused ?? nextTarget(block, null, "next", notes);
 		if (!t) return false;
 		e.state.focus = t.id;
 		e.state.hover = null;
@@ -553,7 +721,10 @@ export function toggleNotesNewest(): boolean {
 
 /** Forget every widget's state (notes, focus, layouts). Called when a session ends: pi processes live for days. */
 export function resetAll() {
-	for (const e of entries.values()) if (e.noticeTimer) clearTimeout(e.noticeTimer);
+	for (const e of entries.values()) {
+		if (e.noticeTimer) clearTimeout(e.noticeTimer);
+		if (e.pending?.timer) clearTimeout(e.pending.timer);
+	}
 	entries.clear();
 	imageService.reset();
 	active.id = null;

package/src/pi/widths.ts

@@ -0,0 +1,16 @@
+// Make our idea of which characters are two cells wide agree with the pi that is running, not only with the pi the committed table
+// (src/diagram/wide.ts) was generated from. Unicode adds emoji with every release, and a character we count as one cell that pi
+// draws as two slides the rest of its row and pushes the right border out of line.
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { setWide } from "../diagram/canvas.ts";
+import { WIDE } from "../diagram/wide.ts";
+import { healWide } from "../diagram/widefix.ts";
+
+/** Ask pi about the blocks where new wide characters appear (see PROBE_SPANS) and use its answers. Never throws: on a failure the committed table stays. */
+export function syncWidths(): void {
+	try {
+		setWide(healWide(WIDE, (cp) => visibleWidth(String.fromCodePoint(cp))));
+	} catch {
+		setWide(WIDE);
+	}
+}