pi-openui 0.2.0 → 0.3.0

package/src/blocks/util.ts

@@ -133,6 +133,11 @@ export interface BoxOpts {
 
 /** Wrap a block in a rounded box. `inner` is placed with padX columns of padding. Returns the boxed block. */
 export function boxed(inner: Block, opts: BoxOpts): Block {
+	// A title that does not fit its border is not cut: it moves inside as a wrapped heading, above the content.
+	if (opts.title && textWidth(opts.title) > Math.max(1, inner.w + 2 * (opts.padX ?? 1) - 4 - (opts.tag ? textWidth(opts.tag) + 2 : 0))) {
+		const head = wrapText(opts.title, Math.max(1, inner.w), opts.titleRole ?? opts.role).map((r) => padRow(r, inner.w));
+		return boxed({ w: inner.w, rows: [...head, ...inner.rows], targets: shiftTargets(inner.targets, 0, head.length) }, { ...opts, title: undefined });
+	}
 	const padX = opts.padX ?? 1;
 	const w = inner.w + 2 + 2 * padX;
 	const role = opts.role;

package/src/diagram/dag.ts

@@ -129,7 +129,8 @@ function attempt(norm: Norm, dir: "LR" | "TB", cap: number): DiagramResult {
 	return layeredDiagram("dag", { nodes, edges, dashReversed: true }, dir);
 }
 
-const CAPS = [28, 20, 14, 10, 8, 6];
+/** How far labels shrink to fit the pane. Below 14 characters a label is no longer a name, so past this the graph scrolls with whole labels. */
+const CAPS = [28, 20, 14];
 
 export function dag(nodesIn: unknown, edgesIn: unknown, opts: DagOptions = {}): DiagramResult {
 	return budgeted(() => dagLayout(nodesIn, edgesIn, opts));
@@ -159,8 +160,8 @@ function dagLayout(nodesIn: unknown, edgesIn: unknown, opts: DagOptions): Diagra
 		if (longest <= cap) break; // shrinking more changes nothing
 	}
 	if (!chosen) {
-		// nothing fits even with short labels: the view will pan anyway, so keep the labels readable
-		const cap = Math.min(maxLabel, 14);
+		// nothing fits even with short labels: the view will scroll, so scroll to whole labels instead of cutting them as well
+		const cap = maxLabel;
 		const tries = dirs.map((d) => attempt(norm, d, cap));
 		best = tries.reduce((a, b) => (b.width < a.width ? b : a));
 	}

package/src/diagram/erd.ts

@@ -146,7 +146,8 @@ function tableSpec(e: NormErd["entities"][number], fieldCap: number, selfRef: bo
 	};
 }
 
-const CAPS = [60, 40, 30, 22, 16];
+/** How far an entity's lines shrink to fit the pane. Below 30 characters the types and flags are dropped, so past this the diagram scrolls. */
+const CAPS = [60, 40, 30];
 
 export function erd(entitiesIn: unknown, relationsIn: unknown, opts: ErdOptions = {}): DiagramResult {
 	return budgeted(() => erdLayout(entitiesIn, relationsIn, opts));
@@ -178,7 +179,8 @@ function erdLayout(entitiesIn: unknown, relationsIn: unknown, opts: ErdOptions):
 		if (chosen) break;
 	}
 	if (!chosen) {
-		const nodes = norm.entities.map((e, i) => tableSpec(e, 30, norm.selfRefs.has(i)));
+		// it will scroll whatever the fields: keep them whole (the widest cap) rather than cut them as well
+		const nodes = norm.entities.map((e, i) => tableSpec(e, CAPS[0], norm.selfRefs.has(i)));
 		const tries = dirs.map((d) => layeredDiagram("erd", { nodes, edges, portSpacing: 4 }, d));
 		best = tries.reduce((a, b) => (b.width < a.width ? b : a));
 	}

package/src/diagram/infra.ts

@@ -402,11 +402,11 @@ function build(norm: NormInfra, dir: "LR" | "TB", caps: Caps): DiagramResult {
 	};
 }
 
+/** How far labels shrink to fit the pane. Past the last row the map scrolls with whole labels, not 8-character ones. */
 const CAPS: Caps[] = [
 	{ label: 22, detail: 26, link: 18 },
 	{ label: 16, detail: 18, link: 12 },
 	{ label: 12, detail: 12, link: 9 },
-	{ label: 8, detail: 8, link: 6 },
 ];
 
 export function infra(zonesIn: unknown, linksIn: unknown, opts: InfraOptions = {}): DiagramResult {
@@ -434,7 +434,8 @@ function infraLayout(zonesIn: unknown, linksIn: unknown, opts: InfraOptions): Di
 		if (chosen) break;
 	}
 	if (!chosen) {
-		const tries = dirs.map((d) => build(norm, d, CAPS[1]));
+		// it will scroll whatever the labels: use the whole ones (the first, widest caps) rather than cut them as well
+		const tries = dirs.map((d) => build(norm, d, CAPS[0]));
 		best = tries.reduce((a, b) => (b.width < a.width ? b : a));
 	}
 	const res = chosen ?? best!;

package/src/lang/docs.ts

@@ -29,7 +29,10 @@ export const DOCS: Record<string, ComponentDoc> = {
 	Stack: {
 		group: "Layout and text",
 		summary: "Lays its children out in a column (the default) or a row. Every widget starts with `root = Stack([...])`.",
-		shots: [{ file: "stack", caption: "A row of tiles, then a row of buttons that wraps when it runs out of width" }],
+		shots: [
+			{ file: "stack", caption: "A row of tiles, then a row of buttons that wraps when it runs out of width" },
+			{ file: "tiles-wrap", caption: "On a phone-width pane (52 columns) the same idea: tiles and buttons wrap onto more rows, every label whole" },
+		],
 		use: ["The root of every widget.", "A row of metric tiles or buttons.", "Grouping a few components with a chosen gap."],
 		avoid: "Do not put a Stack inside a Stack just to add space: use `gap`.",
 		args: {
@@ -46,7 +49,7 @@ b = Metric("Middle", "2")
 c = Metric("Right", "3")`,
 		tips: [
 			"In a row, buttons, metric tiles and short text keep their natural width; every other child shares what is left equally.",
-			"A row that is wider than the terminal shrinks its widest children first, never below 6 columns.",
+			"A row of buttons, tiles and short text that does not fit the terminal wraps onto more rows instead of squeezing them. A row with a child that shares the space (a Card, a Table) keeps its children side by side and shrinks the widest first, never below 6 columns.",
 			"Inside Tabs, wrap a tab's content in one Stack: items placed directly in a tab touch each other.",
 		],
 		related: ["Card", "Tabs", "Text"],
@@ -71,9 +74,12 @@ t3 = Text("Updated 2 minutes ago", "muted")`,
 	Card: {
 		group: "Layout and text",
 		summary: "A bordered panel with an optional title in the top border.",
-		shots: [{ file: "card", caption: "A card with a nested card" }],
+		shots: [
+			{ file: "card", caption: "A card with a nested card" },
+			{ file: "card-wide", caption: "A title too long for the border moves inside as a heading; a callout breaks a long word instead of cutting it" },
+		],
 		use: ["Giving a chart or table a heading and a frame.", "Separating sections inside one widget."],
-		args: { "Card.children": "The components inside. They are laid out as a column with the default gap.", "Card.title": "Shown in the top border. Cut with an ellipsis if it does not fit." },
+		args: { "Card.children": "The components inside. They are laid out as a column with the default gap.", "Card.title": "Shown in the top border. If it does not fit there it moves inside the card as a wrapped heading." },
 		example: `root = Stack([c])
 c = Card([chart], "Load by node")
 chart = BarChart(["a", "b", "c"], [3, 5, 2])`,
@@ -118,6 +124,9 @@ b = Metric("p95 latency", "180 ms", "+22 ms", "warn")`,
 			{ file: "table", caption: "Numbers right-aligned, long text truncated with an ellipsis" },
 			{ file: "table-tooltip", caption: "Hovering the row with a tooltip shows its hint in a bubble" },
 			{ file: "table-panel", caption: "Clicking it, or pressing Enter, opens the detail panel" },
+			{ file: "table-cut", caption: "On a narrow pane a few columns fit by squeezing: the cells that were cut end in an ellipsis" },
+			{ file: "table-read-full", caption: "Tapping a cut cell (or Tab to it and Enter) opens it whole under the table, as plain text" },
+			{ file: "pan-table", caption: "Many columns do not fit: the table scrolls under a bar, and the columns the model pinned (Host and State here) stay in place" },
 		],
 		use: ["Comparing a handful of items across several fields.", "A list of results with a status column."],
 		avoid: "More than about 12 rows: summarise, or split across Tabs.",
@@ -125,14 +134,17 @@ b = Metric("p95 latency", "180 ms", "+22 ms", "warn")`,
 			"Table.columns": "The header strings.",
 			"Table.rows": "An array of rows. Each row has exactly one cell per column, a string or a number. A mismatch is a validation error that names the row.",
 			"Table.tooltips": "Targets: `row:3` (1-based, not counting the header), `col:status`, or `cell:3.status`. Duplicate header names make `col:` and `cell:` ambiguous.",
+			"Table.pin": "The 4th argument: header names of the columns that stay in place while a table wider than the terminal scrolls sideways, such as `[\"Host\"]` (write `null` for tooltips you do not have: `Table(cols, rows, null, [\"Host\"])`). Left out, nothing is pinned and the whole table scrolls. Pin only the one or two narrow columns that identify each row: pinned columns take at most half the width, and one that would not fit is not pinned (the table then scrolls whole). A name that is not a column is a validation error that lists the columns. On a table that fits, nothing changes.",
 		},
 		example: `root = Stack([t])
 t = Table(["Node", "State", "GPU %"], [["spark-1", "serving", 91], ["spark-2", "draining", 84]], [tip])
 tip = Tooltip("row:2", "Rebooting for a driver update")`,
-		interaction: ["A tooltip target shows a `◆` in the cell padding after its text.", "Hover, or Tab to the row, for the bubble; click or Enter for the panel."],
+		interaction: ["A tooltip target shows a `◆` in the cell padding after its text.", "Hover, or Tab to the row, for the bubble; click or Enter for the panel.", "A cell that was cut to fit ends in `…`. Click it, or Tab to it and press Enter, to open it whole under the table as plain text; click it again or press Esc to close it. A cut cell that also has a tooltip shows the whole text in the tooltip's panel."],
 		tips: [
-			"When the table is wider than the terminal the widest columns shrink first, to a minimum of 3 characters.",
-			"A table that still does not fit becomes a scrollable window; moving focus to a target scrolls it into view.",
+			"When the table is wider than the terminal the widest columns shrink first, but never below the minimum column width (12 characters unless the user changes it: see Settings in the README).",
+			"A table that still does not fit becomes a window that scrolls sideways under a pan bar. Nothing is pinned unless you list it in `pin`: pin the one or two narrow columns that identify each row (a host, an id, a date) when a row is hard to read without them, and leave `pin` out otherwise. Pinned columns never take more than half the width: they are tried in the order you list them, and one that would not fit is skipped (never squeezed), so a long column is not pinned by accident and nothing in the table is ever out of reach.",
+			"While a wide table scrolls, its pinned columns are drawn first, in the order they have in the table, then the others. A table that fits is drawn in the order you wrote.",
+			"You cannot see the width of the user's terminal, so do not shorten text to make a table fit: a column is squeezed only to the user's minimum width (and a cell cut by that squeeze ends in an ellipsis; the reader can tap it to read it whole); a table that needs more than that scrolls instead, and then no cell is cut.",
 		],
 		related: ["Markdown", "Metric", "Tooltip"],
 	},
@@ -143,12 +155,13 @@ tip = Tooltip("row:2", "Rebooting for a driver update")`,
 		shots: [
 			{ file: "tabs", caption: "The first tab is open when the widget is drawn" },
 			{ file: "tabs-nodes", caption: "After clicking Nodes" },
+			{ file: "tabs-wrap", caption: "On a narrow pane (44 columns) a strip that does not fit wraps onto more rows; every label stays whole and tappable" },
 		],
 		use: ["Alternate views of one subject: overview, nodes, notes.", "The same snippet in several languages."],
 		avoid: "Steps that must be read in order, or content the reader must see at once: a tab that is not selected is hidden.",
 		args: {
 			"Tabs.items": "One TabItem per tab. The first is open at the start.",
-			"TabItem.label": "The text in the strip. Cut to 22 characters, and shorter when the strip does not fit.",
+			"TabItem.label": "The text in the strip. When the labels do not fit the terminal the strip wraps onto more rows; a label wider than the whole terminal is the only one that is cut.",
 			"TabItem.content": "The components in the tab. Wrap them in a single Stack: `[panel]`.",
 		},
 		example: `root = Stack([tabs])
@@ -255,6 +268,7 @@ b = FaqItem("How do I undo it?", "Run \`uncordon\`.")`,
 		shots: [
 			{ file: "markdown", caption: "Headings, emphasis, lists, a quote, a table, a rule and a link" },
 			{ file: "markdown-image", caption: "A picture inside the text, written as a line of its own, with its caption underneath" },
+			{ file: "markdown-wide", caption: "At 60 columns a code fence and a table that are wider than the pane scroll on their own, each under its own bar" },
 		],
 		use: ["Release notes, explanations, anything with structure.", "A README-style view: text with pictures in it."],
 		args: { "Markdown.text": "Markdown. Use `\\n` for newlines. Supported: `#`-`######` headings, **bold**, *italic*, `code`, ~~strike~~, `[text](https://example.com)`, lists (nested), `>` quotes, tables, fenced code, `---`, and a picture: a line that is only `![alt](path \"caption\")`." },
@@ -270,7 +284,10 @@ m = Markdown("# Notes\\n\\nThis adds **streaming** and \`--fast\` mode.\\n\\n- f
 	CodeBlock: {
 		group: "Rich content",
 		summary: "Syntax-highlighted code in a frame, with a copy button.",
-		shots: [{ file: "code", caption: "Highlighting for JavaScript, SQL, YAML, JSON, bash, Go and Rust" }],
+		shots: [
+			{ file: "code", caption: "Highlighting for JavaScript, SQL, YAML, JSON, bash, Go and Rust" },
+			{ file: "code-pan", caption: "A line wider than the pane is not cut: the code scrolls inside its box, under a bar, and [copy] still copies all of it" },
+		],
 		use: ["Commands to run, config to paste, a query."],
 		args: {
 			"CodeBlock.code": "The source. Use `\\n` for new lines. Tabs become two spaces; more than 200 lines are cut.",
@@ -280,7 +297,7 @@ m = Markdown("# Notes\\n\\nThis adds **streaming** and \`--fast\` mode.\\n\\n- f
 		example: `root = Stack([c])
 c = CodeBlock("kubectl rollout restart deploy/api\\nkubectl rollout status deploy/api", "bash", "restart.sh")`,
 		interaction: ["Click `[copy]` (or Tab to it and press Enter) to put the exact code on the clipboard with an OSC 52 escape. The label changes to `✓ copied` for two seconds."],
-		tips: ["Long lines are cut with an ellipsis, not wrapped, so the code stays aligned. The copy still has the full line.", "The clipboard needs a terminal that accepts OSC 52 (most modern ones do)."],
+		tips: ["Long lines are not wrapped (the code stays aligned) and not cut: when a line is wider than the box the code scrolls sideways inside it, under a pan bar. Lines are cut at 240 columns. The copy has every line in full.", "The clipboard needs a terminal that accepts OSC 52 (most modern ones do)."],
 		related: ["Markdown"],
 	},
 	Image: {
@@ -458,6 +475,7 @@ b = GeoPoint("Frankfurt", 50.11, 8.68, "warn")`,
 		shots: [
 			{ file: "dag", caption: "A CI run with every status: done, failed, running, skipped and pending" },
 			{ file: "dag-tooltip", caption: "A focused node: bold accent border, hint bubble, and the tooltip panel below" },
+			{ file: "dag-wide", caption: "Long step names on a 60-column pane: the labels shrink a little, then the graph scrolls with whole labels" },
 		],
 		use: ["A pipeline where each step has a state.", "A fan-out and fan-in.", "Which job waits for which."],
 		avoid: "Database tables (Erd) or a plain list of steps (Table).",
@@ -468,7 +486,7 @@ b = GeoPoint("Frankfurt", 50.11, 8.68, "warn")`,
 			"Dag.title": "A bold line above the graph.",
 			"Dag.tooltips": "Target: a node id.",
 			"DagNode.id": "Unique in the graph. Edges refer to it.",
-			"DagNode.label": "The text in the box. Shortened with an ellipsis when space is tight.",
+			"DagNode.label": "The text in the box. Shortened to 14 characters at the least to fit the terminal; if it still does not fit, the graph scrolls sideways with whole labels (28 characters at most).",
 			"DagNode.status": "`done` ✓, `running` ◔, `failed` ✗, `pending` ○ or `skipped` ⊘ (also a dashed box). Omit it for a plain box. A legend names the statuses in use.",
 		},
 		example: `root = Stack([flow])
@@ -480,7 +498,7 @@ c = DagNode("deploy", "Deploy", "pending")`,
 		tips: [
 			"A cycle is allowed: the edge that closes it is drawn dashed, pointing back.",
 			"Every edge has its own wire, wires cross only at right angles (`┼`), and the layout is checked by decoding the picture back into edges. An edge that truly cannot be routed is left out and listed under the graph as `a -> b (not drawn)`.",
-			"Wider than the terminal: labels shrink first, then the direction switches, then the view scrolls sideways.",
+			"Wider than the terminal: labels shrink first (never below 14 characters), then the direction switches, then the view scrolls sideways with whole labels.",
 		],
 		related: ["Erd", "InfraMap", "SequenceDiagram"],
 	},
@@ -520,7 +538,10 @@ r = Relation("users", "projects", "1:N", "owns")`,
 		group: "Diagrams and maps",
 		summary: "Zones holding nodes (servers, databases, queues), with labelled arrows showing which talks to which.",
 		helpers: ["InfraZone", "InfraNode", "InfraLink"],
-		shots: [{ file: "infra", caption: "Three zones, with a degraded worker and a dashed link" }],
+		shots: [
+			{ file: "infra", caption: "Three zones, with a degraded worker and a dashed link" },
+			{ file: "infra-wide", caption: "A four-zone map on a 60-column pane: whole labels, the first zone in view, the rest a swipe or a tap on » away" },
+		],
 		use: ["How a system fits together.", "Where a fault is: nodes carry a status."],
 		avoid: "More than about 4 zones and 12 nodes: split it in two.",
 		args: {
@@ -556,7 +577,10 @@ l = InfraLink("lb", "api", "HTTP")`,
 		group: "Diagrams and maps",
 		summary: "Calls between participants: columns left to right, steps top to bottom, with notes and alt/loop frames.",
 		helpers: ["SeqParticipant", "SeqMessage", "SeqNote", "SeqGroup"],
-		shots: [{ file: "sequence", caption: "An alt/else frame, a note, a self-call and activation bars" }],
+		shots: [
+			{ file: "sequence", caption: "An alt/else frame, a note, a self-call and activation bars" },
+			{ file: "sequence-wide", caption: "Five participants and long labels on a 60-column pane: it scrolls, labels whole" },
+		],
 		use: ["The order of calls in a request.", "Who calls whom, and what comes back."],
 		avoid: "More than about 5 participants or 20 steps: split it.",
 		args: {

package/src/lang/library.ts

@@ -104,7 +104,7 @@ export const SPECS: CompSpec[] = [
 	{ name: "Text", params: [p("text", S, false, LIMITS.text), p("variant", e("title", "heading", "body", "muted", "code"), true)], desc: "A line or paragraph of text (default body)." },
 	{ name: "Card", params: [p("children", kids), p("title", S, true)], desc: "Bordered panel with an optional title." },
 	{ name: "Metric", params: [p("label", S), p("value", S), p("delta", S, true), p("tone", e("good", "warn", "bad", "neutral"), true), p("tooltips", tips, true)], desc: "KPI tile. value and delta are strings. tone colours the delta." },
-	{ name: "Table", params: [p("columns", { arr: S, max: LIMITS.tableCols }), p("rows", { arr: { arr: "cell", max: LIMITS.tableCols }, max: LIMITS.tableRows }), p("tooltips", tips, true)], desc: "Data table. rows is an array of rows, each the same length as columns (strings or numbers)." },
+	{ name: "Table", params: [p("columns", { arr: S, max: LIMITS.tableCols }), p("rows", { arr: { arr: "cell", max: LIMITS.tableCols }, max: LIMITS.tableRows }), p("tooltips", tips, true), p("pin", { arr: S, max: LIMITS.tableCols }, true)], desc: "Data table. rows is an array of rows, each the same length as columns (strings or numbers). pin (4th argument, a list of header names) keeps those columns in place while a table wider than the reader's screen scrolls sideways. Nothing is pinned unless you list it: leave pin out when the rows are readable without a fixed column. Pin only the one or two narrow columns that identify each row (a name, an id). Pinned columns take at most half the width, and one that would not fit is not pinned: the table then just scrolls whole." },
 	{ name: "BarChart", params: [p("labels", { arr: S, max: LIMITS.bars }), p("values", { arr: "number", max: LIMITS.bars }), p("title", S, true), p("unit", S, true), p("tooltips", tips, true)], desc: "Bar chart of one series. labels and values are parallel arrays. unit is a suffix such as %." },
 	{ name: "Callout", params: [p("text", S), p("tone", e("info", "success", "warn", "error"), true)], desc: "Highlighted note." },
 	{ name: "Button", params: [p("label", S), p("action", "action", true)], desc: "Clickable button. Without an action it sends its label to the assistant." },
@@ -221,9 +221,71 @@ export interface Compiled {
 	ok: boolean;
 	errors: string[];
 	warnings: string[];
+	/** what `restore` mode changed to make an older source draw (values cut to a limit, arguments ignored, ...). Always empty in strict mode. */
+	notes: string[];
 	root?: El;
 }
 
+/**
+ * The version of OpenUI Lang this code reads. A widget written by an earlier version of the language is version 1 or whatever was
+ * stored with it. Bump it when a change would stop an older source from compiling (a removed or renamed component or argument, a
+ * positional argument inserted, a required one added, a lower limit), and add an alias or a migration below. AGENTS.md has the rule.
+ */
+export const LANG_VERSION = 1;
+
+/** An old component name and what it is called now. Applied only when an old source is read again (`restore`), never to what the model writes. */
+export const ALIASES: Record<string, string> = {};
+
+/** Rewrites a source written under version `from` into one the next version reads. Run in order, only in `restore` mode. */
+export const MIGRATIONS: Array<{ from: number; run(source: string): string }> = [];
+
+export interface CompileOpts {
+	/** `strict` (default) is for what the model writes: every mistake is an error it can fix. `restore` is for a source read again from a session. */
+	mode?: "strict" | "restore";
+	/** the language version the source was written under (default 1) */
+	from?: number;
+	/** tests pass their own; the real tables above are the default */
+	migrations?: typeof MIGRATIONS;
+	aliases?: typeof ALIASES;
+}
+
+/** Rename `Old(` to `New(` outside string literals. */
+function renameCalls(source: string, aliases: Record<string, string>): string {
+	const names = Object.keys(aliases);
+	if (!names.length) return source;
+	let out = "";
+	let i = 0;
+	while (i < source.length) {
+		const ch = source[i];
+		if (ch === '"') {
+			let j = i + 1;
+			while (j < source.length && source[j] !== '"') j += source[j] === "\\" ? 2 : 1;
+			out += source.slice(i, j + 1);
+			i = j + 1;
+			continue;
+		}
+		const m = /^[A-Za-z_][A-Za-z0-9_]*/.exec(source.slice(i, i + 80));
+		if (m) {
+			const word = m[0];
+			const after = source.slice(i + word.length).match(/^\s*\(/);
+			out += after && Object.prototype.hasOwnProperty.call(aliases, word) ? aliases[word] : word;
+			i += word.length;
+			continue;
+		}
+		out += ch;
+		i++;
+	}
+	return out;
+}
+
+/** An older source brought up to date: migrations for the versions after the one it was written under, then renamed components. */
+function upgrade(source: string, opts: CompileOpts): string {
+	const from = opts.from ?? 1;
+	let text = source;
+	for (const m of [...(opts.migrations ?? MIGRATIONS)].sort((a, b) => a.from - b.from)) if (m.from >= from) text = m.run(text);
+	return renameCalls(text, opts.aliases ?? ALIASES);
+}
+
 export function showType(t: T): string {
 	if (typeof t === "string") return t === "child" ? "component" : t === "cell" ? "string | number" : t;
 	if ("enum" in t) return t.enum.map((x) => JSON.stringify(x)).join(" | ");
@@ -235,28 +297,32 @@ export function showType(t: T): string {
 }
 
 /** Reads and checks a program. Never throws: whatever goes wrong comes back as an error the model can read. */
-export function compile(source: string): Compiled {
+export function compile(source: string, opts: CompileOpts = {}): Compiled {
 	try {
-		const text = String(source ?? "");
-		if (text.length > LIMITS.source) return { ok: false, errors: [`the source is ${Math.round(text.length / 1000)} KB; the limit is ${LIMITS.source / 1000} KB. Show less data, or split it into several widgets`], warnings: [] };
-		const c = compileProgram(text);
+		const restoring = opts.mode === "restore";
+		let text = String(source ?? "");
+		if (text.length > LIMITS.source) return { ok: false, errors: [`the source is ${Math.round(text.length / 1000)} KB; the limit is ${LIMITS.source / 1000} KB. Show less data, or split it into several widgets`], warnings: [], notes: [] };
+		if (restoring) text = upgrade(text, opts);
+		const c = compileProgram(text, restoring);
 		if (c.errors.length > LIMITS.errors) {
 			const more = c.errors.length - LIMITS.errors;
 			return { ...c, errors: [...c.errors.slice(0, LIMITS.errors), `... and ${more} more error${more === 1 ? "" : "s"}; fix these first`], root: undefined, ok: false };
 		}
 		return c;
 	} catch (e) {
-		return { ok: false, errors: [`the widget could not be read: ${(e as Error).message}. Make it smaller and less nested`], warnings: [] };
+		return { ok: false, errors: [`the widget could not be read: ${(e as Error).message}. Make it smaller and less nested`], warnings: [], notes: [] };
 	}
 }
 
-function compileProgram(source: string): Compiled {
+function compileProgram(source: string, restore = false): Compiled {
 	const prog = parseProgram(source);
 	const errors = [...prog.errors];
 	const warnings: string[] = [];
+	/** restore mode: what was changed to make an older source draw. In strict mode the same things are errors. */
+	const notes: string[] = [];
 	if (!prog.statements.has("root")) {
 		errors.push("define the entry point: root = Stack([...]) (put it on the first line)");
-		return { ok: false, errors, warnings };
+		return { ok: false, errors, warnings, notes };
 	}
 	if (prog.order[0] !== "root") warnings.push("root is not the first statement; put it first so the shell appears immediately");
 
@@ -317,8 +383,15 @@ function compileProgram(source: string): Compiled {
 		}
 	};
 
-	const tooLong = (v: string, max: number, ctx: string, line: number) => {
-		if (v.length > max) errors.push(`${where(line)}${ctx} is ${v.length} characters; the limit is ${max}. Shorten it`);
+	/** A string within its limit. Over it: an error for the model, or (restoring an older widget) the string cut to the limit, with a note. */
+	const fitString = (v: string, max: number, ctx: string, line: number): string => {
+		if (v.length <= max) return v;
+		if (restore) {
+			notes.push(`${where(line)}${ctx} is ${v.length} characters; the limit is ${max}, so it was cut to ${max}`);
+			return v.slice(0, max);
+		}
+		errors.push(`${where(line)}${ctx} is ${v.length} characters; the limit is ${max}. Shorten it`);
+		return v;
 	};
 	const resolve = (x: Expr, t: T, ctx: string, maxChars: number = LIMITS.string): any => {
 		const d0 = x;
@@ -333,16 +406,14 @@ function compileProgram(source: string): Compiled {
 				switch (t) {
 					case "string":
 						if (d.k !== "str") return bad("a string");
-						tooLong(d.v, maxChars, ctx, d.line);
-						return d.v;
+						return fitString(d.v, maxChars, ctx, d.line);
 					case "number":
 						return d.k === "num" ? d.v : bad("a number");
 					case "boolean":
 						return d.k === "bool" ? d.v : bad("true or false");
 					case "cell":
 						if (d.k !== "str" && d.k !== "num") return bad("a string or a number");
-						if (d.k === "str") tooLong(d.v, LIMITS.cell, ctx, d.line);
-						return d.v;
+						return d.k === "str" ? fitString(d.v, LIMITS.cell, ctx, d.line) : d.v;
 					case "any":
 						return plain(d);
 					case "action": {
@@ -395,7 +466,13 @@ function compileProgram(source: string): Compiled {
 				if (d.k !== "arr") return bad("an array [...]");
 				const out = d.items.map((it, i) => resolve(it, t.arr, `${ctx}[${i + 1}]`)).filter((v) => v !== undefined);
 				if (t.min !== undefined && d.items.length < t.min) errors.push(`${where(d.line)}${ctx} needs at least ${t.min} item(s)`);
-				if (t.max !== undefined && d.items.length > t.max) errors.push(`${where(d.line)}${ctx} allows at most ${t.max} item(s), got ${d.items.length}`);
+				if (t.max !== undefined && d.items.length > t.max) {
+					if (restore) {
+						notes.push(`${where(d.line)}${ctx} allows at most ${t.max} item(s), got ${d.items.length}; the extra ones were dropped`);
+						return out.slice(0, t.max);
+					}
+					errors.push(`${where(d.line)}${ctx} allows at most ${t.max} item(s), got ${d.items.length}`);
+				}
 				return out;
 			}
 			// { comp: [...] }
@@ -437,7 +514,10 @@ function compileProgram(source: string): Compiled {
 		}
 	};
 	const buildInner = (call: Extract<Expr, { k: "call" }>, spec: CompSpec): El | undefined => {
-		if (call.args.length > spec.params.length) errors.push(`${where(call.line)}${spec.name} takes at most ${spec.params.length} argument(s), got ${call.args.length}`);
+		if (call.args.length > spec.params.length) {
+			if (restore) notes.push(`${where(call.line)}${spec.name} takes at most ${spec.params.length} argument(s), got ${call.args.length}; the extra ones were ignored`);
+			else errors.push(`${where(call.line)}${spec.name} takes at most ${spec.params.length} argument(s), got ${call.args.length}`);
+		}
 		const props: Record<string, any> = {};
 		spec.params.forEach((param, i) => {
 			const arg = call.args[i];
@@ -503,6 +583,23 @@ function compileProgram(source: string): Compiled {
 					pr.rows.forEach((r: any[], i: number) => {
 						if (r.length !== pr.columns.length) err(`row ${i + 1} has ${r.length} cells but there are ${pr.columns.length} columns`);
 					});
+				if (Array.isArray(pr.pin) && Array.isArray(pr.columns)) {
+					// headers are compared the way the table draws them: spacing collapsed
+					const header = (c: unknown) => String(c ?? "").replace(/\s+/g, " ").trim();
+					const heads = pr.columns.map(header);
+					const kept: string[] = [];
+					for (const name of pr.pin as string[]) {
+						const h = header(name);
+						if (!heads.includes(h)) {
+							if (restore) notes.push(`${where(el.line)}Table: pin "${h}" is not a column, so it was dropped`);
+							else err(`pin "${h}" is not a column. Columns: ${heads.join(", ")}`);
+						} else if (kept.includes(h)) {
+							if (restore) notes.push(`${where(el.line)}Table: pin lists "${h}" twice, so the second was dropped`);
+							else err(`pin lists "${h}" twice`);
+						} else kept.push(h);
+					}
+					if (restore) pr.pin = kept;
+				}
 				break;
 			case "BarChart":
 			case "PieChart":
@@ -590,10 +687,15 @@ function compileProgram(source: string): Compiled {
 	const rootEl = resolve(rootStmt.expr, "child", "root");
 	visiting.pop();
 	if (rootEl && rootEl.type !== "Stack") errors.push(`${where(rootStmt.line)}root must be a Stack(...), not ${rootEl.type}`);
-	for (const name of prog.order) if (!used.has(name)) errors.push(`${where(prog.statements.get(name)!.line)}"${name}" is defined but not reachable from root, so it would not render. Add it to its parent's children or items array`);
+	for (const name of prog.order) {
+		if (used.has(name)) continue;
+		const line = where(prog.statements.get(name)!.line);
+		if (restore) notes.push(`${line}"${name}" is defined but not reachable from root, so it is not drawn`);
+		else errors.push(`${line}"${name}" is defined but not reachable from root, so it would not render. Add it to its parent's children or items array`);
+	}
 	const seen = new Set<string>();
 	const uniq = errors.filter((m) => (seen.has(m) ? false : (seen.add(m), true)));
-	return { ok: uniq.length === 0 && !!rootEl, errors: uniq, warnings, root: uniq.length === 0 ? rootEl : undefined };
+	return { ok: uniq.length === 0 && !!rootEl, errors: uniq, warnings, notes: [...new Set(notes)], root: uniq.length === 0 ? rootEl : undefined };
 }
 
 /** Text for the model: syntax rules, signatures, actions, tooltips, examples. */
@@ -613,7 +715,7 @@ export function reference(): string {
 ${SPECS.map(sig).join("\n")}
 
 ## Tooltips
-\`tooltips: Tooltip[]\` is the LAST argument of Dag, Erd, InfraMap, SequenceDiagram, Table, Metric, BarChart, LineChart, AreaChart, PieChart, RadarChart, GeoMap and Image, so write null for each skipped optional argument before it, e.g. Dag(nodes, edges, null, null, [t1]).
+\`tooltips: Tooltip[]\` is the LAST argument of Dag, Erd, InfraMap, SequenceDiagram, Metric, BarChart, LineChart, AreaChart, PieChart, RadarChart, GeoMap and Image, so write null for each skipped optional argument before it, e.g. Dag(nodes, edges, null, null, [t1]). A Table takes tooltips as its 3rd argument and \`pin\` as its 4th: Table(columns, rows, [t1], ["Host"]), or Table(columns, rows, null, ["Host"]) without tooltips.
 Targets: Dag node id; Erd entity name or entity.column; InfraMap node id, zone:<zone name> or <fromId>><toId>; SequenceDiagram participant id or SeqMessage id; Table row:3, col:status or cell:3.status; Metric its own label; BarChart a bar label; GeoMap a point label or A>B; Image the word image; LineChart and AreaChart an x label (that point) or series:<name>; PieChart a slice label; RadarChart an axis label or series:<name>.
 An element that has a tooltip shows a small ◆ on it. Hovering shows the hint; clicking (or Enter) opens the panel with detail, code and link. Use a tooltip for context the reader may want but should not have to read: why a point spiked, what a slice contains, what a node does.
 hint is the short text shown on hover (140 characters). detail (800), code (40 lines) and link (http/https) open in a panel when the element is clicked.
@@ -627,6 +729,7 @@ Choice(question, options, hint, multiple, other) asks the user. A click only sta
 
 ## Choosing components
 Metric for a number, Table for comparisons, BarChart for one series of categories, LineChart for trends with several series, AreaChart for stacked volume, PieChart for parts of a whole (8 slices at most), RadarChart for comparing entities across metrics, Dag for task graphs and pipelines, Erd for database schemas, InfraMap for how systems connect, SequenceDiagram for call flows, GeoMap for places, Tabs/Card to organise. Series values must have the same length as labels. All data is literal: no queries, no variables. Image shows a real picture in terminals that support it (Kitty, Ghostty, WezTerm, Warp, herdr): src is an absolute file path (png, jpg, gif, webp) or a data: URI.
+The reader's terminal may be narrow (a phone is about 60 columns) and you cannot see its width. A Dag, Erd, InfraMap or SequenceDiagram wider than it, and a Table with many columns, scroll sideways under a bar and nothing in them is cut. A Table with only a few columns is squeezed to fit instead and a long cell ends in an ellipsis (the reader can tap it to read it whole), so still keep table cells short and put long text in Text or Markdown. A Table pins nothing unless you ask: when it has many columns and a row is hard to read without its first one, list the one or two narrow columns that identify each row (a name, an id) in \`pin\`, e.g. Table(columns, rows, null, ["Host"]). They stay in place while the rest scrolls. Do not pin a long column or one that is not needed to tell the rows apart: pinned columns take at most half the width, one that would not fit is not pinned, and the table scrolls whole without it.
 
 ## Example
 root = Stack([title, kpis, load, go])