pi-openui 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 ## Unreleased
 
+## 0.3.0 (2026-11-14)
+
+- **A cell that was cut to fit can be read whole.** A table with a few columns is squeezed to fit and a long cell ends in `…`; now
+  that cell is a target. Click it, or Tab to it and press Enter, and it opens under the table as plain text (line breaks kept,
+  nothing read as Markdown); click again or Esc closes it. A cut header too, and Markdown tables the same. If the agent gave that
+  cell a tooltip, the tooltip's panel opens with the whole text added. A table that scrolls cuts nothing, so it has none of these.
+- **`/openui-gallery wide`** draws eleven examples of things that do not fit a phone: a wide table with a pinned column, long cells,
+  code with a long line, tabs and tiles that wrap, a wide InfraMap, a Dag, an ERD, a sequence diagram, Markdown with a wide fence
+  and table, and a card with a long title. `docs/gallery-narrow.txt` is the same set as text at 60 columns, `docs/gallery.txt` is
+  current again (it was not regenerated for the pan bar), and `npm run gallery:files` writes both; a test fails when they are stale.
+  `node scripts/langgallery.ts <prefix>` now matches by prefix, as the command does.
+- **New screenshots** for the pan bar, pinned columns, cut and opened cells, code, tabs, tiles, an InfraMap, a Dag and a sequence
+  diagram at phone width, on the pages of the components they show.
+
+- **A table's columns can be pinned.** `Table(columns, rows, tooltips, pin)`: `pin` (new, 4th argument, optional) lists header names
+  that stay in place while a table wider than the pane scrolls, e.g. `Table(cols, rows, null, ["Host", "State"])`. The agent decides:
+  left out, nothing is pinned and the whole table scrolls. Pinned columns never take more than half the pane: they are tried in the
+  order listed and one that does not fit is skipped, never squeezed, so no text is ever out of reach. While the table scrolls they
+  are drawn first, in the order they have in the table; a table that fits is drawn as it was written. A name that is not a column is
+  a validation error that lists the columns. Every source written before this still compiles and draws as it did. The reference the
+  agent reads says when to pin (one or two narrow columns that identify each row) and when not to.
+- **Scrolling in two sizes.** The pan bar is now ` «  ‹ ████░░░ 1–53/87 ›  » `. `‹ ›` move a few cells (`scroll.step`, 8 by default),
+  `« »` a page (three quarters of the pane, to a column edge in a table). Left and Right on a focused bar are fine steps; Shift+arrow,
+  PageUp and PageDown are pages. Dragging the bar's thumb is still cell-precise. A bar too narrow for four arrows keeps the fine pair.
+- **`scroll.step` in the settings file**, with `PI_OPENUI_SCROLL_STEP` and `/openui-config scroll.step <1-40>`. `/openui-config reset`
+  now puts every setting back; `/openui-config <setting> reset` puts one back.
+- **The language cannot be broken by accident any more.** `test/compat/signatures.json` records every component and argument the
+  language has had; a test fails if an argument is inserted, moved, removed or made required, if a list or choice accepts less, or if a
+  limit goes down. New arguments go at the end and are optional. `AGENTS.md` says so.
+
+- **A pan bar says when a widget is wider than the pane.** Tables, Dag, Erd, InfraMap and SequenceDiagram that do not fit now show
+  `‹ ███░░░░░░ 1–53/87 ›` under them (only when something is cut off). Tap or click `‹` and `›`, click or drag the bar, swipe
+  sideways or use a horizontal wheel where your terminal app sends one, Shift+wheel, or Tab to the bar and press Left and Right
+  (also in notes mode). The plain wheel still scrolls the transcript. The old text hint `select a node to pan` is gone.
+- **Tables keep a minimum column width.** A column is squeezed only down to 12 characters (not three) before the table scrolls
+  sideways. Markdown tables are unchanged. Tables that fit are unchanged.
+- **A settings file.** `~/.pi/agent/openui.json` (`{ "table": { "minColumnWidth": 12 } }`, 4 to 40),
+  `PI_OPENUI_TABLE_MIN_COL`, and `/openui-config` to look at it, set it or `reset` it.
+- **Old sessions keep working.** A session stores a widget's source and draws it again, so everything above reaches widgets from
+  earlier versions at once. New widgets store the language version (`details.lang`). A source that no longer compiles under today's
+  strict rules is now read leniently (a value over a limit is cut, extra arguments are ignored, a statement nothing uses is
+  ignored) with one quiet line saying it was redrawn with changes, and one that still cannot be read shows the reason and the start
+  of its source instead of a blank. `AGENTS.md` now says language changes must be additive, and `test/compat/` keeps sources as older
+  versions wrote them so a change that breaks one fails the tests.
+- **Pan rather than cut.** On a narrow pane text used to be shortened with `…` wherever a layout could not give: now it scrolls or wraps
+  instead. Code scrolls inside its box, code fences and tables in Markdown scroll on their own, a row of buttons or metric tiles wraps
+  onto more rows, a tab strip wraps onto more rows, and a title that does not fit a box's border moves inside as a heading. A Dag,
+  InfraMap, Erd or SequenceDiagram that cannot fit scrolls with whole labels instead of 6-character ones (they shrink to 14
+  characters at the least), and a table that scrolls cuts no cell at all (before: at 20 characters). Anything still wider than the pane
+  gets the pan bar. `test/narrow-audit.test.ts` holds every component to it.
+- **A picture's frame says what it is.** If the terminal does not draw the picture (a phone app that reports no cell size, or a second
+  client attached to the same herdr), the frame is no longer an empty box: it names the picture and its size.
+- **`/openui-events`** records what a tap, a swipe or a flick sends to a widget, for five minutes, so what your terminal app really
+  does can be read instead of guessed. It never records what you type.
+- **The agent is told the terminal may be narrow.** The reference `render_widget` returns says a phone is about 60 columns, that
+  wide blocks scroll under a bar, and when to pin a Table's columns.
+- **A tap right after a sideways flick works.** pi-tui does not understand horizontal wheel events and leaves a press unreleased,
+  which made the next tap do nothing; the widget now recognises that tap itself.
+
 ## 0.2.0 (2026-11-02)
 
 - **`Choice` takes several answers and an Other answer, and sends them together.** `Choice(question, options, hint, multiple, other)`.

package/README.md

@@ -62,8 +62,11 @@ update pi shows this package's [changelog](CHANGELOG.md). Maintainers: see [docs
 |---|---|
 | Let the agent draw | Ask for a dashboard, a chart, a diagram, a table. It calls `render_widget`. |
 | One example of every component | `/openui-gallery`, or one kind: `/openui-gallery dag`, `erd`, `infra`, `sequence`, `geo`, `pie`, `line`, `image`, `table`, `tabs`, `markdown`, `choice` |
+| The examples that do not fit a phone | `/openui-gallery wide`: a wide table, long cells, long code, tabs, tiles, diagrams. Try it in a narrow pane |
 | Draw a file | `/openui-file path/to/widget.oui` |
 | Use the keyboard without the mouse | `/openui-focus` |
+| Change a setting | `/openui-config`, for example `/openui-config table.minColumnWidth 14` |
+| See what a swipe or tap sends | `/openui-events on`, try it over a widget, `/openui-events show` |
 | Write notes on a widget | Click `[ notes ]` under it, or `/openui-notes` |
 
 Gallery clicks are echoed locally and cost nothing. In a widget the agent drew, a Button click is sent to the agent as your
@@ -71,6 +74,41 @@ next message, and the answers to its Choices are sent together, as one message,
 
 The mouse needs pi's default fullscreen mode. Everything also works from the keyboard.
 
+## Small screens
+
+On a narrow terminal (a phone over SSH or herdr, a small split) a widget that is wider than the pane shows a **pan bar**
+under it, `‹ ███░░░░░░ 1–53/87 ›`, and scrolls sideways. Tap the arrows or the bar, swipe or use a horizontal wheel where the
+terminal app sends one, Shift+wheel, or Tab to the bar and use the arrow keys. `‹ ›` move a few cells at a time, `« »` a page.
+A table scrolls whole; the agent can pin a column or two (never more than half the width) to keep them in view, and a table never
+squeezes a column below a minimum width before it scrolls. A cell that was cut to fit ends in `…`: tap it to read it whole.
+
+![A wide table scrolled sideways: Host and State stayed in place, the bar has fine and page arrows](https://raw.githubusercontent.com/newtonapple/pi-openui/main/docs/screenshots/pan-table-scrolled.png)
+
+![A cell cut to fit, tapped: its whole text under the table](https://raw.githubusercontent.com/newtonapple/pi-openui/main/docs/screenshots/table-read-full.png)
+
+`/openui-gallery wide` draws eleven examples of things that would be cut on a phone, so you can see what each does in your pane. Code scrolls inside its box, rows of buttons and tabs wrap, and
+diagrams scroll with whole labels: nothing is cut with `…` when it can be reached another way. Not sure what your app sends for a
+swipe? `/openui-events on`, try it over a widget, `/openui-events show`. Details are in
+[docs/interaction.md](https://github.com/newtonapple/pi-openui/blob/main/docs/interaction.md#wide-diagrams-and-tables).
+
+## Settings
+
+One file, `~/.pi/agent/openui.json` (or `$PI_CODING_AGENT_DIR/openui.json`):
+
+```json
+{ "table": { "minColumnWidth": 12 }, "scroll": { "step": 8 } }
+```
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `table.minColumnWidth` | `12` (4 to 40) | The narrowest a table column is squeezed to. A table that does not fit at that width scrolls sideways. Lower it to see more columns at once; raise it to read more of each cell. |
+| `scroll.step` | `8` (1 to 40) | Cells one tap on a fine arrow (`‹ ›`) scrolls. The page arrows (`« »`) always go about three quarters of the pane. Lower it if scrolling feels jumpy. |
+
+`PI_OPENUI_TABLE_MIN_COL` and `PI_OPENUI_SCROLL_STEP` override the file. `/openui-config` shows what is in force,
+`/openui-config scroll.step 5` writes the file (handy on a phone) and redraws every widget, `/openui-config scroll.step reset` puts
+one setting back, and `/openui-config reset` puts all of them back. A bad value falls back to the
+default with one notice, and the file is never overwritten if it is not valid JSON.
+
 ## Notes
 
 Pin a comment to one part of a widget, then send all your comments to the agent as a single message. Use it to say "this row
@@ -157,7 +195,8 @@ After you change the code, run `/reload` in pi. The rest:
 npm test                 # a few seconds, no network, no model calls
 npm run docs             # regenerate docs/components/ from the signature table
 npm run screenshots      # regenerate docs/screenshots/, and the two README composites (needs Python with Pillow, and the font)
-npm run gallery          # print every component to the terminal (-- --plain for no colour)
+npm run gallery          # print every component to the terminal (-- --plain for no colour; a key prefix, e.g. `wide`, picks some)
+npm run gallery:files    # regenerate docs/gallery.txt and docs/gallery-narrow.txt (a test fails when they are stale)
 make help                # the release process (check, version, publish, tag, push)
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Pi extension: interactive dashboards, charts, diagrams and maps in the terminal. The agent draws with OpenUI Lang; you click, hover and pin notes.",
   "license": "MIT",
@@ -52,6 +52,7 @@
     "width": "node --import ./test/register-pi.mjs scripts/width-table.ts",
     "screenshots": "node --import ./test/register-pi.mjs scripts/shots.ts && python3 scripts/render_shots.py && python3 scripts/hero.py",
     "docs": "node scripts/gen_docs.ts",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "gallery:files": "node scripts/gen-gallery.ts"
   }
 }

package/src/blocks/code.ts

@@ -1,5 +1,6 @@
 import { textWidth, truncateText, type Cell } from "../diagram/canvas.ts";
-import type { Block, Target } from "./types.ts";
+import type { Block, Ctx, Target } from "./types.ts";
+import { panBlock } from "./panblock.ts";
 import { boxed, cell, fromRows, textCells, vstack } from "./util.ts";
 
 const KW: Record<string, string[]> = {
@@ -84,8 +85,20 @@ export function codeInner(code: string, lang: string | undefined, width: number)
 	return fromRows(width, rows);
 }
 
-export function codeBlock(code: string, lang: string | undefined, title: string | undefined, width: number, copyId: string | null, copied: boolean): Block {
-	const inner = codeInner(code, lang, Math.max(8, width - 4));
+/** The longest line of the code that is drawn, in cells. */
+const longestLine = (code: string) => Math.max(0, ...String(code ?? "").replace(/\t/g, "  ").replace(/\n$/, "").split("\n").slice(0, 200).map((l) => textWidth(l)));
+
+/** A line longer than this is cut: even a scrolling view needs an end. */
+export const MAX_CODE_COLS = 240;
+
+/**
+ * `pan` (a render context and a key for the scroll offset) lets code wider than its box scroll inside it, with a pan bar under the
+ * last line; the box and its copy button stay where they are. Without it (a quote, a tooltip panel) a long line is cut as it was.
+ */
+export function codeBlock(code: string, lang: string | undefined, title: string | undefined, width: number, copyId: string | null, copied: boolean, pan?: { ctx: Ctx; key: string }): Block {
+	const innerW = Math.max(8, width - 4);
+	const longest = longestLine(code);
+	const inner = pan && longest > innerW ? panBlock(codeInner(code, lang, Math.min(longest, MAX_CODE_COLS)), innerW, pan.key, pan.ctx) : codeInner(code, lang, innerW);
 	const label = [title, lang && !title ? lang : title && lang ? lang : ""].filter(Boolean).join(" · ");
 	const tagText = copyId ? (copied ? "✓ copied" : "[copy]") : undefined;
 	const b = boxed(inner, { role: "code.border", title: label || undefined, titleRole: "code.title", tag: tagText, tagRole: copied ? "code.copied" : "btn" });

package/src/blocks/core.ts

@@ -37,7 +37,11 @@ export function stack(el: El, width: number, ctx: Ctx, path: string): Block {
 	const gap = COL_GAP[gapTok] ?? 2;
 	const nat = kids.map(natural);
 	const lines: number[][] = [];
-	if (el.props.wrap) {
+	// A row of fixed-size children (tiles, buttons, short text) that cannot sit side by side wraps instead of being squeezed until
+	// their labels are cut. A row with a child that shares the space (a Card, a Table) keeps its old behaviour.
+	const fixedRow = nat.length > 1 && nat.every((n) => n !== null);
+	const overflows = fixedRow && nat.reduce((a, n) => a + (n ?? 0), 0) + gap * (nat.length - 1) > width;
+	if (el.props.wrap || overflows) {
 		let cur: number[] = [];
 		let used = 0;
 		const share = Math.max(14, Math.floor((width - 2 * gap) / 3));
@@ -198,32 +202,50 @@ export function tabs(el: El, width: number, ctx: Ctx, path: string): Block {
 	const items: El[] = el.props.items ?? [];
 	if (!items.length) return blank(width, 0);
 	const sel = Math.min(Math.max(0, ctx.state.tab[path] ?? 0), items.length - 1);
-	let labels = items.map((it) => truncateText(String(it.props.label ?? ""), 22));
-	const need = () => labels.reduce((a, l) => a + textWidth(l) + 4, 0);
-	let cap = 22;
-	while (need() > width && cap > 4) labels = items.map((it) => truncateText(String(it.props.label ?? ""), --cap));
-	const l0: ReturnType<typeof textCells> = [];
-	const l1: typeof l0 = [];
-	const l2: typeof l0 = [];
-	const targets: Target[] = [];
+	// Labels are never shortened to make the bar fit (a label wider than the whole pane is the one exception). A bar that does not
+	// fit wraps onto more rows, each a little tab bar of its own.
+	const labels = items.map((it) => truncateText(String(it.props.label ?? ""), Math.max(1, width - 4)));
+	const lines: number[][] = [];
+	let cur: number[] = [];
+	let used = 0;
 	labels.forEach((lab, i) => {
-		const iw = textWidth(lab) + 2;
-		const on = i === sel;
-		const role = on ? "tab.on" : "tab.off";
-		const x0 = l1.length;
-		if (on) {
-			l0.push(cell("╭", role), ...Array.from({ length: iw }, () => cell("─", role)), cell("╮", role));
-			l1.push(cell("│", role), cell(" ", role), ...textCells(lab, "tab.label"), cell(" ", role), cell("│", role));
-			l2.push(cell("╯", role), ...Array.from({ length: iw }, () => cell(" ")), cell("╰", role));
-		} else {
-			l0.push(...Array.from({ length: iw + 2 }, () => cell(" ")));
-			l1.push(cell(" "), cell(" "), ...textCells(lab, role), cell(" "), cell(" "));
-			l2.push(...Array.from({ length: iw + 2 }, () => cell("─", "tab.rule")));
+		const w = textWidth(lab) + 4;
+		if (cur.length && used + w > width) {
+			lines.push(cur);
+			cur = [];
+			used = 0;
 		}
-		targets.push({ id: `tab:${path}:${i}`, kind: "tab", rect: { x: x0, y: 1, w: iw + 2, h: 1 }, label: String(items[i].props.label ?? "") });
+		used += w;
+		cur.push(i);
+	});
+	if (cur.length) lines.push(cur);
+	const rows: Cell[][] = [];
+	const targets: Target[] = [];
+	lines.forEach((idxs, k) => {
+		const l0: ReturnType<typeof textCells> = [];
+		const l1: typeof l0 = [];
+		const l2: typeof l0 = [];
+		idxs.forEach((i) => {
+			const lab = labels[i];
+			const iw = textWidth(lab) + 2;
+			const on = i === sel;
+			const role = on ? "tab.on" : "tab.off";
+			const x0 = l1.length;
+			if (on) {
+				l0.push(cell("╭", role), ...Array.from({ length: iw }, () => cell("─", role)), cell("╮", role));
+				l1.push(cell("│", role), cell(" ", role), ...textCells(lab, "tab.label"), cell(" ", role), cell("│", role));
+				l2.push(cell("╯", role), ...Array.from({ length: iw }, () => cell(" ")), cell("╰", role));
+			} else {
+				l0.push(...Array.from({ length: iw + 2 }, () => cell(" ")));
+				l1.push(cell(" "), cell(" "), ...textCells(lab, role), cell(" "), cell(" "));
+				l2.push(...Array.from({ length: iw + 2 }, () => cell("─", "tab.rule")));
+			}
+			targets.push({ id: `tab:${path}:${i}`, kind: "tab", rect: { x: x0, y: 3 * k + 1, w: iw + 2, h: 1 }, label: String(items[i].props.label ?? "") });
+		});
+		while (l2.length < width) l2.push(cell("─", "tab.rule"));
+		rows.push(l0, l1, l2);
 	});
-	while (l2.length < width) l2.push(cell("─", "tab.rule"));
-	const strip = fromRows(width, [l0, l1, l2], targets);
+	const strip = fromRows(width, rows, targets);
 	ctx.tabs.push(String(items[sel].props.label ?? ""));
 	let content: Block;
 	try {
@@ -270,6 +292,16 @@ export function image(el: El, width: number, path: string, ctx: Ctx): { block: B
 	if (placed) {
 		// the picture is drawn over these cells by the host; here they are reserved, framed and clickable
 		const area = blank(placed.cols, placed.rows);
+		// The terminal draws the picture over these cells, so what is written here is only ever seen when it does not: a phone app that
+		// reports no cell size, a second client attached, a terminal without graphics. An empty box looks broken; this says what it is.
+		const say = (y: number, text: string) => {
+			if (y < 0 || y >= placed.rows || placed.cols < 8) return;
+			const cells = textCells(truncateText(text, placed.cols - 2), "text.muted");
+			area.rows[y] = padRow([...Array.from({ length: Math.max(0, Math.floor((placed.cols - cells.length) / 2)) }, () => cell(" ")), ...cells], placed.cols);
+		};
+		const mid = Math.floor((placed.rows - 1) / 2);
+		say(placed.rows >= 4 ? mid - 1 : mid, svc ? svc.describe(src) : name);
+		if (placed.rows >= 4) say(mid + 1, "no picture? terminal can't show it");
 		area.targets.push({ id: `image:${path}`, kind: "image", rect: { x: 0, y: 0, w: placed.cols, h: placed.rows }, label: `${alt}`, image: { key: placed.key, cols: placed.cols, rows: placed.rows } });
 		const cap = p.caption ? fromRows(placed.cols, wrapText(String(p.caption), placed.cols, "text.muted")) : null;
 		block = boxed(cap ? vstack([area, cap], 0, placed.cols) : area, { role: "image.border", title: alt, titleRole: "image.alt", padX: 0 });
@@ -296,6 +328,10 @@ export interface Anchor {
 	badgeForce?: boolean;
 	/** cells besides `rect` that belong to the element (a pie wedge) */
 	cells?: Array<[number, number]>;
+	/** a cell that was cut to fit: its whole text, readable in a panel (no tooltip needed) */
+	full?: string;
+	/** what to call the element in the hover line and the panel's title, when its tooltip key (`cell:3.Notes`) would read badly */
+	label?: string;
 }
 
 /** The mark that says "this element has a tooltip". Present in the user's font (JetBrains Mono), unlike the circled i. */
@@ -339,6 +375,11 @@ export function tipPanel(label: string, tip: Tip, width: number): Block {
 	if (tip.detail) parts.push(markdownBlock(tip.detail, iw));
 	if (tip.code) parts.push(codeInner(tip.code, tip.language, iw));
 	if (tip.link) parts.push(fromRows(iw, [textCells(truncateText(`↗ ${tip.linkLabel ?? tip.link}${tip.linkLabel ? ` — ${tip.link}` : ""}`, iw), "md.link")]));
+	if (tip.full !== undefined) {
+		// plain text, as it was written: not Markdown, and wrapped rather than cut
+		const body = wrapText(tip.full, iw, "");
+		parts.push(parts.length ? vstack([fromRows(iw, [textCells("the whole cell", "tip.hint")]), fromRows(iw, body)], 0, iw) : fromRows(iw, body));
+	}
 	const inner = vstack(parts.length ? parts : [fromRows(iw, [textCells(label, "tip.hint")])], 1, iw);
 	return boxed(inner, { role: `tip.${tip.tone ?? "info"}`, title: label });
 }
@@ -364,8 +405,9 @@ export function addWholeItem(el: El, block: Block, path: string, ctx: Ctx): void
 export function withTips(el: El, block: Block, anchors: Map<string, Anchor>, path: string, ctx: Ctx, avail = block.w): Block {
 	registerItems(el, block, anchors, path, ctx);
 	const tips: El[] = el.props.tooltips ?? [];
-	if (!tips.length) return block;
 	let panel: Block | null = null;
+	const panelWidth = () => Math.min(Math.max(avail, 20), Math.max(block.w, 44));
+	const tipped = new Set<string>();
 	for (const t of tips) {
 		const key = String(t.props.target ?? "");
 		const a = anchors.get(key);
@@ -373,13 +415,22 @@ export function withTips(el: El, block: Block, anchors: Map<string, Anchor>, pat
 			ctx.warnings.push(`${el.type}: tooltip target "${key}" does not match anything in the component`);
 			continue;
 		}
-		const tip: Tip = { hint: t.props.hint, detail: t.props.detail, code: t.props.code, language: t.props.language, tone: t.props.tone, link: t.props.link, linkLabel: t.props.linkLabel };
+		tipped.add(key);
+		const tip: Tip = { hint: t.props.hint, detail: t.props.detail, code: t.props.code, language: t.props.language, tone: t.props.tone, link: t.props.link, linkLabel: t.props.linkLabel, ...(a.full !== undefined ? { full: a.full } : {}) };
 		const existing = a.targetId ? block.targets.find((x) => x.id === a.targetId) : undefined;
 		const id = existing ? existing.id : `tip:${path}:${key}`;
 		if (existing) existing.tip = tip;
 		else block.targets.push({ id, kind: "tip", rect: a.rect, label: key, tip, ...(a.cells ? { cells: a.cells } : {}) });
 		placeBadge(block, a, tip.tone ?? "info");
-		if (ctx.state.tip === id && (tip.detail || tip.code || tip.link)) panel = tipPanel(key, tip, Math.min(Math.max(avail, 20), Math.max(block.w, 44)));
+		if (ctx.state.tip === id && (tip.detail || tip.code || tip.link || tip.full !== undefined)) panel = tipPanel(key, tip, panelWidth());
+	}
+	// a cell that was cut to fit and has no tooltip of its own: a tap reads it whole (no badge: the ellipsis is the cue)
+	for (const [key, a] of anchors) {
+		if (a.full === undefined || tipped.has(key)) continue;
+		const id = `tip:${path}:${key}`;
+		const tip: Tip = { full: a.full };
+		block.targets.push({ id, kind: "tip", rect: a.rect, label: a.label ?? key, tip });
+		if (ctx.state.tip === id) panel = tipPanel(a.label ?? key, tip, panelWidth());
 	}
 	return panel ? vstack([block, panel], 0, Math.max(block.w, panel.w)) : block;
 }

package/src/blocks/diagrams.ts

@@ -7,25 +7,9 @@ import type { DiagramResult } from "../diagram/layeredDiagram.ts";
 import type { El } from "../lang/library.ts";
 import type { Anchor } from "./core.ts";
 import type { Block, Ctx, Target } from "./types.ts";
+import { panBlock } from "./panblock.ts";
 import { cell, fromRows, padRow, textCells, vstack } from "./util.ts";
 
-/** Crop a block wider than `width` to a window starting at the saved pan offset. */
-export function panBlock(inner: Block, width: number, key: string, ctx: Ctx): Block {
-	if (inner.w <= width) return inner;
-	const maxPan = inner.w - width;
-	const pan = Math.min(maxPan, Math.max(0, ctx.state.pan[key] ?? 0));
-	ctx.state.pan[key] = pan;
-	const rows = inner.rows.map((r) => {
-		const seg = padRow(r, inner.w).slice(pan, pan + width);
-		if (seg.length && seg[0].ch === "") seg[0] = cell(" ");
-		if (seg.length && pan + width < inner.w && seg[seg.length - 1].ch !== "" && r[pan + width]?.ch === "") seg[seg.length - 1] = cell(" ");
-		return seg;
-	});
-	const targets: Target[] = inner.targets.map((t) => ({ ...t, rect: { ...t.rect, x: t.rect.x - pan }, pan: { key, x: t.rect.x, w: t.rect.w, view: width, total: inner.w } }));
-	const hint = textCells(`${pan > 0 ? "‹" : " "} columns ${pan + 1}–${pan + width} of ${inner.w} ${pan < maxPan ? "›" : " "}  select a node to pan`, "text.muted");
-	return { w: width, rows: [...rows, padRow(hint, width)], targets };
-}
-
 /**
  * A diagram's layout depends only on the component and the width, but the widget lays out again for a note, a tab, a resize
  * or a late picture. Routing wires is the costly part, so each result is kept with its component (and dropped with it). Nothing
@@ -85,7 +69,7 @@ export function dagBlock(el: El, width: number, path: string, ctx: Ctx): { block
 	const dy = p.title ? 1 : 0;
 	for (const n of res.nodes) anchors.set(n.id, { rect: { ...n.rect, y: n.rect.y + dy }, targetId: `node:${path}:${n.id}` });
 	const block = panBlock(inner, width, `pan:${path}`, ctx);
-	remapAnchors(anchors, inner, block);
+	remapAnchors(anchors, inner, block, ctx.state.pan[`pan:${path}`] ?? 0);
 	return { block, anchors };
 }
 
@@ -105,7 +89,7 @@ export function erdBlock(el: El, width: number, path: string, ctx: Ctx): { block
 		});
 	}
 	const block = panBlock(inner, width, `pan:${path}`, ctx);
-	remapAnchors(anchors, inner, block);
+	remapAnchors(anchors, inner, block, ctx.state.pan[`pan:${path}`] ?? 0);
 	return { block, anchors };
 }
 
@@ -124,19 +108,17 @@ export function infraBlock(el: El, width: number, path: string, ctx: Ctx): { blo
 		if (c) anchors.set(`${e.from}>${e.to}`, { rect: { x: Math.max(0, c[0] - 1), y: c[1] + dy, w: Math.max(3, e.labelCells.length + 2), h: 1 } });
 	}
 	const block = panBlock(inner, width, `pan:${path}`, ctx);
-	remapAnchors(anchors, inner, block);
+	remapAnchors(anchors, inner, block, ctx.state.pan[`pan:${path}`] ?? 0);
 	return { block, anchors };
 }
 
-/** after panning, anchors must follow the targets they point at */
-function remapAnchors(anchors: Map<string, Anchor>, inner: Block, panned: Block) {
-	if (panned === inner) return;
-	const pan = panned.targets[0]?.pan;
-	const dx = pan ? pan.x - panned.targets[0].rect.x : 0;
+/** after panning by `dx`, anchors must follow the targets they point at */
+function remapAnchors(anchors: Map<string, Anchor>, inner: Block, panned: Block, dx: number) {
+	if (panned === inner || !dx) return;
 	for (const [, a] of anchors) {
 		a.rect = { ...a.rect, x: a.rect.x - dx };
 		if (a.badge) a.badge = [a.badge[0] - dx, a.badge[1]];
 	}
 }
 
-export { offsetAnchors, textWidth };
+export { offsetAnchors, panBlock, textWidth };

package/src/blocks/fallback.ts

@@ -0,0 +1,25 @@
+// What a widget shows when its source cannot be drawn again (a language change an old session was never migrated across, or a
+// source from a newer version than this extension). Never a blank: the reader gets the reason and the start of the source.
+// Pure: lines of plain text; the caller colours them.
+
+const SOURCE_LINES = 12;
+const WIDTH = 80;
+
+/** One short line of plain text: control and escape characters are what a stored source must never be allowed to send to a terminal. */
+const tidy = (s: string, max: number): string => {
+	const clean = s.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ");
+	return clean.length > max ? clean.slice(0, max - 1) + "…" : clean;
+};
+
+export function fallbackLines(source: string, errors: string[], lang: number): string[] {
+	const lines = [`This widget could not be drawn again (OpenUI Lang v${lang}).`];
+	if (errors.length) lines.push(`Why: ${tidy(errors[0], WIDTH)}`);
+	const text = String(source ?? "");
+	if (text.trim()) {
+		lines.push("The source it was drawn from:");
+		const all = text.split("\n");
+		for (const l of all.slice(0, SOURCE_LINES)) lines.push(`  ${tidy(l, WIDTH)}`);
+		if (all.length > SOURCE_LINES) lines.push(`  … ${all.length - SOURCE_LINES} more line${all.length - SOURCE_LINES === 1 ? "" : "s"}`);
+	}
+	return lines;
+}

package/src/blocks/gesture.ts

@@ -0,0 +1,112 @@
+// What a pointer does to a block that is wider than its pane. Events in, actions out: no terminal and no pi, so the cases that
+// matter (a sideways flick, a drag on the thumb, a tap after a flick) are tested with plain objects.
+//
+// Why a recognizer at all: pi-tui understands only the vertical wheel. A horizontal one (SGR buttons 66 and 67) reaches a
+// widget as a `press` with button "right" or "none" that is never released, and while pi believes that press is still down
+// it does not turn the next tap into a `click`. The recognizer pans on those presses, remembers that it saw one, and
+// recognises the next tap itself from its press and release. Everything else about taps stays with pi's `click`.
+import { panAreaAt, targetAt } from "./interact.ts";
+import { clampPan, panFromTrack } from "./pan.ts";
+import type { Block, Target } from "./types.ts";
+
+/** The fields of pi's mouse event that are used. Coordinates are local to the block. */
+export interface MouseIn {
+	type: string;
+	button: string;
+	x: number;
+	y: number;
+	shift: boolean;
+	alt: boolean;
+	wheelDelta?: number;
+}
+
+export type Action =
+	| { kind: "pan"; key: string; to: number; capture?: boolean }
+	| { kind: "tap"; x: number; y: number }
+	/** a click that was already handled as a tap */
+	| { kind: "swallow" }
+	| { kind: "none" };
+
+/** Columns for one notch of a wheel or one horizontal flick event. */
+export const WHEEL_COLUMNS = 3;
+
+const NONE: Action = { kind: "none" };
+const same = (a: { x: number; y: number } | null, x: number, y: number) => !!a && a.x === x && a.y === y;
+
+export class Recognizer {
+	/** pi has been sent a press that no release will match (a horizontal flick) */
+	stuck = false;
+	private pressAt: { x: number; y: number } | null = null;
+	private ignoreClickAt: { x: number; y: number } | null = null;
+	/** the track being dragged: where it is and what it scrolls */
+	private drag: { key: string; track: Target["rect"]; total: number; view: number } | null = null;
+
+	reset(): void {
+		this.stuck = false;
+		this.pressAt = null;
+		this.ignoreClickAt = null;
+		this.drag = null;
+	}
+
+	private shift(block: Block, pan: Record<string, number>, ev: MouseIn, columns: number): Action {
+		const sc = panAreaAt(block, ev.x, ev.y)?.scroll;
+		if (!sc) return NONE;
+		return { kind: "pan", key: sc.key, to: clampPan((pan[sc.key] ?? 0) + columns, sc.total, sc.view) };
+	}
+
+	feed(ev: MouseIn, block: Block, pan: Record<string, number>): Action {
+		switch (ev.type) {
+			case "press": {
+				if (ev.button === "none" || ev.button === "right") {
+					// a horizontal wheel: "none" is SGR 67 (right), "right" is SGR 66 (left)
+					const a = this.shift(block, pan, ev, ev.button === "none" ? WHEEL_COLUMNS : -WHEEL_COLUMNS);
+					if (a.kind !== "none") this.stuck = true;
+					return a;
+				}
+				this.ignoreClickAt = null; // a new gesture: the click that followed an earlier tap is long gone
+				if (ev.button !== "left") return NONE;
+				this.pressAt = { x: ev.x, y: ev.y };
+				const t = targetAt(block, ev.x, ev.y);
+				if (t?.kind === "pan" && t.scroll?.part === "track") {
+					this.drag = { key: t.scroll.key, track: t.rect, total: t.scroll.total, view: t.scroll.view };
+					return { kind: "pan", key: t.scroll.key, to: panFromTrack(ev.x, t.rect, t.scroll.total, t.scroll.view), capture: true };
+				}
+				return NONE;
+			}
+			case "drag": {
+				const d = this.drag;
+				if (!d || ev.button !== "left") return NONE;
+				return { kind: "pan", key: d.key, to: panFromTrack(ev.x, d.track, d.total, d.view), capture: true };
+			}
+			case "release": {
+				if (ev.button !== "left") return NONE;
+				this.drag = null;
+				const wasStuck = this.stuck;
+				const press = this.pressAt;
+				this.pressAt = null;
+				this.stuck = false; // pi has seen a release: whatever it was holding is let go
+				if (wasStuck && same(press, ev.x, ev.y)) {
+					this.ignoreClickAt = { x: ev.x, y: ev.y };
+					return { kind: "tap", x: ev.x, y: ev.y };
+				}
+				return NONE;
+			}
+			case "click": {
+				this.stuck = false; // pi sent a click: it is healthy
+				if (same(this.ignoreClickAt, ev.x, ev.y)) {
+					this.ignoreClickAt = null;
+					return { kind: "swallow" };
+				}
+				this.ignoreClickAt = null;
+				return NONE;
+			}
+			case "wheel": {
+				if (!ev.shift && !ev.alt) return NONE; // the plain wheel scrolls the transcript
+				const d = Math.sign(ev.wheelDelta ?? 0);
+				return d ? this.shift(block, pan, ev, d * WHEEL_COLUMNS) : NONE;
+			}
+			default:
+				return NONE;
+		}
+	}
+}