pi-openui 0.2.0 → 0.3.0

package/src/blocks/interact.ts

@@ -1,5 +1,6 @@
 // Interaction logic, independent of any terminal: hit testing, activation, keyboard navigation, pan reveal.
 import { buildMessage, progress, toggleOption } from "./choice.ts";
+import { DEFAULT_FINE_STEP, fineStepPan, stepPan } from "./pan.ts";
 import type { Block, Target, WState } from "./types.ts";
 
 export interface Env {
@@ -18,6 +19,8 @@ const area = (t: Target) => t.rect.w * t.rect.h;
  * items, the notes tray, and tabs (so you can reach content on another tab). Buttons, choices and the like do not fire.
  */
 export function isLive(t: Target, notes: boolean): boolean {
+	if (t.kind === "panarea") return false; // found with panAreaAt, never selected
+	if (t.kind === "pan") return true; // a clipped table needs its bar in notes mode too, to reach the columns a note is about
 	if (!notes) return t.kind !== "item";
 	return t.kind === "item" || t.kind === "tab" || t.kind === "note" || t.kind === "noteadd" || t.kind === "noteclear" || t.kind === "notes";
 }
@@ -29,7 +32,7 @@ export function targetAt(block: Block, x: number, y: number, notes = false): Tar
 	for (const t of block.targets) {
 		if (!isLive(t, notes)) continue;
 		const r = t.rect;
-		const inRect = x >= r.x && y >= r.y && x < r.x + r.w && y < r.y + r.h && r.x + r.w > 0 && r.x < block.w;
+		const inRect = x >= r.x && y >= r.y && x < r.x + r.w && y < r.y + r.h && r.x + r.w > 0 && r.x < block.w && x >= (t.pan?.min ?? 0);
 		const inCells = !!t.cells && t.cells.some(([cx, cy]) => cx === x && cy === y);
 		if (!inRect && !inCells) continue;
 		const score = inCells ? 0 : area(t);
@@ -41,6 +44,40 @@ export function targetAt(block: Block, x: number, y: number, notes = false): Tar
 	return best;
 }
 
+/** One step on a bar: a fine one (`sc.step` cells, anywhere) or a page (three quarters of the pane, to a column edge in a table). */
+function movePan(sc: NonNullable<Target["scroll"]>, cur: number, dir: -1 | 1, page: boolean): number {
+	return page ? stepPan(cur, dir, sc.total, sc.view, sc.edges) : fineStepPan(cur, dir, sc.total, sc.view, sc.step ?? DEFAULT_FINE_STEP);
+}
+
+/**
+ * An arrow key while the pan bar is the focused target: scroll. Either arrow scrolls whichever part of the bar has the focus,
+ * because Left and Right mean left and right, not "activate this button". False when something else is focused, or when the
+ * block is already at that end (the caller then lets the key move the focus as usual). `page` is a page (Shift+arrow, PageUp,
+ * PageDown); without it a fine step.
+ */
+export function panKey(block: Block, state: WState, focusId: string | null, key: "left" | "right", page = false): boolean {
+	const t = focusId ? block.targets.find((x) => x.id === focusId) : undefined;
+	const sc = t?.kind === "pan" ? t.scroll : undefined;
+	if (!sc) return false;
+	const cur = state.pan[sc.key] ?? 0;
+	const next = movePan(sc, cur, key === "left" ? -1 : 1, page);
+	if (next === cur) return false;
+	state.pan[sc.key] = next;
+	return true;
+}
+
+/** The pan area under a point: what a wheel or a drag over a clipped block should move. The smallest one when they nest. */
+export function panAreaAt(block: Block, x: number, y: number): Target | null {
+	let best: Target | null = null;
+	for (const t of block.targets) {
+		if (t.kind !== "panarea") continue;
+		const r = t.rect;
+		if (x < r.x || y < r.y || x >= r.x + r.w || y >= r.y + r.h) continue;
+		if (!best || area(t) < area(best)) best = t;
+	}
+	return best;
+}
+
 export function readingOrder(block: Block, notes = false): Target[] {
 	return block.targets.filter((t) => isLive(t, notes)).sort((a, b) => a.rect.y - b.rect.y || a.rect.x - b.rect.x || a.id.localeCompare(b.id));
 }
@@ -197,11 +234,21 @@ export function activate(t: Target, state: WState, env: Env): boolean {
 			if (t.copy !== undefined) env.copy(t.copy);
 			state.copied = t.id;
 			return true;
+		case "pan": {
+			// the arrows step; the track is for the pointer (the widget places the thumb where it was pressed)
+			const sc = t.scroll;
+			if (!sc || sc.part === "track") return false;
+			const cur = state.pan[sc.key] ?? 0;
+			const next = movePan(sc, cur, sc.part === "left" || sc.part === "pageleft" ? -1 : 1, sc.part === "pageleft" || sc.part === "pageright");
+			if (next === cur) return false;
+			state.pan[sc.key] = next;
+			return true;
+		}
 		case "node":
 		case "image":
 		case "tip": {
 			const tip = t.tip;
-			if (!tip || !(tip.detail || tip.code || tip.link)) return false;
+			if (!tip || !(tip.detail || tip.code || tip.link || tip.full !== undefined)) return false;
 			state.tip = state.tip === t.id ? null : t.id;
 			return true;
 		}
@@ -215,7 +262,8 @@ export function reveal(t: Target, state: WState): boolean {
 	if (!p) return false;
 	const cur = state.pan[p.key] ?? 0;
 	let next = cur;
-	if (p.x < cur) next = Math.max(0, p.x - 2);
+	const left = p.min ?? 0; // columns kept in place at the left cover the first `min` cells of the view
+	if (p.x < cur + left) next = Math.max(0, p.x - left - 2);
 	else if (p.x + p.w > cur + p.view) next = Math.min(p.total - p.view, p.x + p.w - p.view + 2);
 	if (next === cur) return false;
 	state.pan[p.key] = next;
@@ -250,6 +298,9 @@ export function describe(t: Target): string {
 		case "image":
 			bits.push(t.label);
 			break;
+		case "pan":
+			bits.push(t.label, t.scroll?.part === "track" ? "click to jump, or drag" : t.scroll?.part === "pageleft" || t.scroll?.part === "pageright" ? "a page at a time" : `${t.scroll?.step ?? DEFAULT_FINE_STEP} cells at a time`);
+			break;
 		case "item":
 			bits.push(t.label, "Enter to write a note");
 			break;
@@ -270,5 +321,6 @@ export function describe(t: Target): string {
 	}
 	if (t.tip?.hint) bits.push(t.tip.hint);
 	if (t.tip && (t.tip.detail || t.tip.code || t.tip.link)) bits.push("Enter for details");
+	else if (t.tip?.full !== undefined) bits.push("tap to read all"); // short: this line is cut at the width of the pane
 	return bits.filter(Boolean).join("  ·  ");
 }

package/src/blocks/markdown.ts

@@ -2,7 +2,9 @@ import { textWidth } from "../diagram/canvas.ts";
 import { imageLine } from "../lang/md.ts";
 import { codeBlock } from "./code.ts";
 import { image } from "./core.ts";
-import { tableBlock } from "./table.ts";
+import { panBlock } from "./panblock.ts";
+import { withTips, type Anchor } from "./core.ts";
+import { cutCells, tableBlock, tablePan } from "./table.ts";
 import type { Block, Ctx } from "./types.ts";
 import { cell, fromRows, vstack, wrapRuns, textCells, type Run, padRow } from "./util.ts";
 
@@ -46,6 +48,7 @@ export function markdownBlock(src: string, width: number, ctx?: Ctx, path = ""):
 	const blocks: Block[] = [];
 	let i = 0;
 	let pictures = 0;
+	let wide = 0; // code fences and tables: each scrolls on its own
 	const para: string[] = [];
 	const flush = () => {
 		if (!para.length) return;
@@ -61,7 +64,7 @@ export function markdownBlock(src: string, width: number, ctx?: Ctx, path = ""):
 			i++;
 			while (i < lines.length && !/^\s*```\s*$/.test(lines[i])) body.push(lines[i++]);
 			i++;
-			blocks.push(codeBlock(body.join("\n"), fence[1] || undefined, undefined, width, null, false));
+			blocks.push(codeBlock(body.join("\n"), fence[1] || undefined, undefined, width, null, false, ctx ? { ctx, key: `pan:${path}.w${wide++}` } : undefined));
 			continue;
 		}
 		const pic = ctx ? imageLine(ln) : null;
@@ -100,7 +103,14 @@ export function markdownBlock(src: string, width: number, ctx?: Ctx, path = ""):
 			i += 2;
 			const body: string[][] = [];
 			while (i < lines.length && lines[i].includes("|") && lines[i].trim()) body.push(cells(lines[i++]));
-			blocks.push(tableBlock(head, body, width).block);
+			if (ctx) {
+				const t = tableBlock(head, body, width, { minCol: ctx.services.settings?.tableMinCol ?? 12 });
+				const id = `${path}.w${wide++}`;
+				const shown = panBlock(t.block, width, `pan:${id}`, ctx, tablePan(t, width));
+				// a cell cut to fit can be read whole, as in a Table (only where there is a context to hold targets)
+				const anchors = new Map<string, Anchor>(cutCells(t, head, body).map((c) => [c.key, { rect: c.rect, full: c.full, label: c.label }]));
+				blocks.push(anchors.size ? withTips({ type: "MarkdownTable", props: {}, line: 0 }, shown, anchors, id, ctx, width) : shown);
+			} else blocks.push(tableBlock(head, body, width).block);
 			continue;
 		}
 		const li = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/.exec(ln);

package/src/blocks/pan.ts

@@ -0,0 +1,139 @@
+// Panning a block that is wider than its pane: the maths, and the one-row bar that tells the reader it can be scrolled.
+// Pure: no widget, no terminal, no pi.
+import type { Cell, Rect } from "../diagram/canvas.ts";
+import { cell, textCells } from "./util.ts";
+
+/** One step of a tap or a key: three quarters of the view, so a little of what was on screen stays as a landmark. */
+export const panStep = (view: number): number => Math.max(1, Math.floor((view * 3) / 4));
+
+/** The offset kept inside 0..total-view. A block that fits has nothing to pan. */
+export function clampPan(pan: number, total: number, view: number): number {
+	const max = Math.max(0, Math.floor(total) - Math.floor(view));
+	return Math.max(0, Math.min(Math.round(pan), max));
+}
+
+/** Where the thumb sits in a track `track` cells long: as long as the view is of the whole, at least one cell. */
+export function thumbCells(track: number, pan: number, total: number, view: number): { start: number; len: number } {
+	if (track <= 0) return { start: 0, len: 0 };
+	if (total <= view) return { start: 0, len: track };
+	const len = Math.max(1, Math.min(track, Math.round((track * view) / total)));
+	const max = total - view;
+	const start = Math.round(((track - len) * clampPan(pan, total, view)) / max);
+	return { start: Math.max(0, Math.min(track - len, start)), len };
+}
+
+/** The offset that puts the middle of the thumb under cell `x` (a tap or a drag on the track). */
+export function panFromTrack(x: number, track: { x: number; w: number }, total: number, view: number): number {
+	const { len } = thumbCells(track.w, 0, total, view);
+	const room = track.w - len;
+	if (room <= 0 || total <= view) return 0;
+	const start = Math.max(0, Math.min(room, x - track.x - len / 2));
+	return clampPan((start / room) * (total - view), total, view);
+}
+
+/**
+ * One tap on an arrow. Plain: `panStep` either way. With `edges` (the left edges of a table's columns, in block cells): the
+ * farthest edge within one step, so a column is never left cut in half after a tap, and a left tap undoes a right tap.
+ */
+export function stepPan(pan: number, dir: -1 | 1, total: number, view: number, edges?: number[]): number {
+	const step = panStep(view);
+	let to = pan + dir * step;
+	if (edges?.length) {
+		const hit = dir === 1 ? edges.filter((e) => e > pan && e <= pan + step) : edges.filter((e) => e < pan && e >= pan - step);
+		if (hit.length) to = dir === 1 ? Math.max(...hit) : Math.min(...hit);
+	}
+	return clampPan(to, total, view);
+}
+
+/** Cells one tap on a fine arrow moves, unless the user's `scroll.step` says otherwise (src/pi/config.ts). */
+export const DEFAULT_FINE_STEP = 8;
+
+/** One tap on a fine arrow: exactly `cells`, clamped. No snapping: this is for reading along. */
+export function fineStepPan(pan: number, dir: -1 | 1, total: number, view: number, cells: number): number {
+	return clampPan(pan + dir * Math.max(1, Math.round(cells)), total, view);
+}
+
+export interface BarLayout {
+	/** the outer arrows, a page at a time; absent when the bar is too narrow for them */
+	pageLeft?: Rect;
+	/** the inner arrows, a few cells at a time */
+	left: Rect;
+	track: Rect;
+	right: Rect;
+	pageRight?: Rect;
+	/** the range shown, e.g. `1–63/175`; empty when the bar is too narrow for it */
+	label: string;
+}
+
+const ARROW = 3; // a finger needs more than one cell: ` ‹ `
+const MIN_TRACK = 6;
+
+/** ` « ‹ ████░░░░ 1–63/175 › » `: page arrows outside, fine arrows inside, the track and the range between. */
+export function barLayout(width: number, pan: number, total: number, view: number): BarLayout {
+	const paged = width - 4 * ARROW >= MIN_TRACK;
+	const side = paged ? 2 * ARROW : ARROW;
+	const mid = Math.max(0, width - 2 * side);
+	let label = `${pan + 1}–${Math.min(total, pan + view)}/${total}`;
+	let track = mid - (label.length + 2);
+	if (track < MIN_TRACK) {
+		label = "";
+		track = mid;
+	}
+	const at = (x: number): Rect => ({ x, y: 0, w: ARROW, h: 1 });
+	return {
+		...(paged ? { pageLeft: at(0), pageRight: at(width - ARROW) } : {}),
+		left: at(paged ? ARROW : 0),
+		right: at(width - side),
+		track: { x: side, y: 0, w: Math.max(0, track), h: 1 },
+		label,
+	};
+}
+
+/** ` « ‹ ████░░░░░░░░ 1–63/175  › » `: exactly `width` cells. An arrow that cannot move is dim. */
+export function barRow(width: number, pan: number, total: number, view: number): Cell[] {
+	const l = barLayout(width, pan, total, view);
+	const canLeft = pan > 0;
+	const canRight = pan < total - view;
+	const t = thumbCells(l.track.w, pan, total, view);
+	const arrow = (glyph: string, on: boolean): Cell[] => [cell(" "), cell(glyph, on ? "btn" : "text.muted"), cell(" ")];
+	const row: Cell[] = [...(l.pageLeft ? arrow("«", canLeft) : []), ...arrow("‹", canLeft)];
+	for (let i = 0; i < l.track.w; i++) row.push(i >= t.start && i < t.start + t.len ? cell("█", "btn") : cell("░", "text.muted"));
+	if (l.label) row.push(cell(" "), ...textCells(l.label, "text.muted"), cell(" "));
+	const right: Cell[] = [...arrow("›", canRight), ...(l.pageRight ? arrow("»", canRight) : [])];
+	while (row.length < width - right.length) row.push(cell(" "));
+	return [...row, ...right].slice(0, width);
+}
+
+/** Pinned columns never take more than this share of the pane: a pinned part that fills it would leave nothing to scroll. */
+export const PIN_SHARE = 0.5;
+export const pinBudget = (view: number): number => Math.floor(view * PIN_SHARE);
+
+/** How many cells at the left stay put while the rest scrolls: `frozen` when it is within the budget, else none. */
+export const frozenFor = (frozen: number, view: number): number => (frozen > 0 && frozen <= pinBudget(view) ? frozen : 0);
+
+/**
+ * Move an anchor (a rect and perhaps a badge position) to where its column is after the block was scrolled by `dx` with `frozen`
+ * columns kept in place. What is behind the frozen part is cut off, so a badge or a hit area never lands on the frozen column;
+ * what is entirely behind it keeps a rect one cell wide at the edge with no width (nothing to hit, nothing to draw).
+ */
+export function shiftAnchor<T extends { rect: Rect; badge?: [number, number] }>(a: T, dx: number, frozen: number): void {
+	const r = a.rect;
+	if (!dx) return;
+	if (!frozen) {
+		a.rect = { ...r, x: r.x - dx };
+		if (a.badge) a.badge = [a.badge[0] - dx, a.badge[1]];
+		return;
+	}
+	if (r.x < frozen) {
+		if (r.x + r.w > frozen) a.rect = { ...r, w: r.w - dx }; // a row across the frozen part: its far end moves
+		return; // in the frozen part: stays
+	}
+	let x = r.x - dx;
+	let w = r.w;
+	if (x < frozen) {
+		w -= frozen - x;
+		x = frozen;
+	}
+	a.rect = { ...r, x, w: Math.max(0, w) };
+	if (a.badge) a.badge = a.badge[0] - dx >= frozen && w > 0 ? [a.badge[0] - dx, a.badge[1]] : undefined;
+}

package/src/blocks/panblock.ts

@@ -0,0 +1,44 @@
+// The one place a block wider than its pane is cropped, scrolled and given its pan bar (see pan.ts for the maths).
+import type { Ctx, Block, Target } from "./types.ts";
+import { barLayout, barRow, clampPan, DEFAULT_FINE_STEP, frozenFor } from "./pan.ts";
+import { cell, padRow } from "./util.ts";
+
+/**
+ * Crop a block wider than `width` to a window starting at the saved pan offset, and put a pan bar under it: the one place that
+ * says "there is more" and the buttons that move it. A block that fits is returned as it is, with no bar.
+ * `opts.edges` are the left edges of a table's columns, so a tap lands on a column. `opts.frozen` is how many cells at the left
+ * stay in place while the rest scrolls (a table's first column), when that is at most 40% of the view.
+ */
+export function panBlock(inner: Block, width: number, key: string, ctx: Ctx, opts: { edges?: number[]; frozen?: number } = {}): Block {
+	if (inner.w <= width) {
+		delete ctx.state.pan[key]; // it fits now (the pane grew): nothing is left to scroll, and a later narrow pane starts at the left
+		return inner;
+	}
+	const pan = clampPan(ctx.state.pan[key] ?? 0, inner.w, width);
+	ctx.state.pan[key] = pan;
+	const F = frozenFor(opts.frozen ?? 0, width);
+	const rows = inner.rows.map((r) => {
+		const full = padRow(r, inner.w);
+		// the window starts after the frozen cells: at pan 0 this is the plain crop
+		const seg = full.slice(F + pan, pan + width);
+		if (seg.length && seg[0].ch === "") seg[0] = cell(" ");
+		if (seg.length && pan + width < inner.w && seg[seg.length - 1].ch !== "" && full[pan + width]?.ch === "") seg[seg.length - 1] = cell(" ");
+		return F ? full.slice(0, F).concat(seg) : seg;
+	});
+	const targets: Target[] = inner.targets.map((t) => {
+		if (F && t.rect.x < F) return t; // in the frozen part, or a row across it: always where it is
+		return { ...t, rect: { ...t.rect, x: t.rect.x - pan }, pan: { key, x: t.rect.x, w: t.rect.w, view: width, total: inner.w, ...(F ? { min: F } : {}) } };
+	});
+	const y = rows.length;
+	const bar = barLayout(width, pan, inner.w, width);
+	const step = ctx.services.settings?.scrollStep ?? DEFAULT_FINE_STEP;
+	type Part = "left" | "right" | "pageleft" | "pageright" | "track";
+	const scroll = (part: Part) => ({ key, part, total: inner.w, view: width, edges: opts.edges, step });
+	const part = (id: Part, label: string, r: { x: number; w: number }): Target => ({ id: `bar:${key}:${id}`, kind: "pan", rect: { x: r.x, y, w: r.w, h: 1 }, label, scroll: scroll(id) });
+	if (bar.pageLeft) targets.push(part("pageleft", "page left", bar.pageLeft));
+	targets.push(part("left", "scroll left", bar.left), part("track", "scroll", bar.track), part("right", "scroll right", bar.right));
+	if (bar.pageRight) targets.push(part("pageright", "page right", bar.pageRight));
+	// the area carries the numbers a wheel or a drag needs (`part` means nothing here)
+	targets.push({ id: `area:${key}`, kind: "panarea", rect: { x: 0, y: 0, w: width, h: y + 1 }, label: "", scroll: scroll("track") });
+	return { w: width, rows: [...rows, barRow(width, pan, inner.w, width)], targets };
+}

package/src/blocks/render.ts

@@ -9,7 +9,8 @@ import { markdownBlock } from "./markdown.ts";
 import { sequence } from "./sequence.ts";
 import { collectChoices } from "./choice.ts";
 import { decorateNotes, widgetTitle } from "./notes.ts";
-import { tableBlock } from "./table.ts";
+import { frozenFor, shiftAnchor } from "./pan.ts";
+import { cutCells, pinIndexes, tableBlock, tablePan } from "./table.ts";
 import type { Block, Ctx, Services, WState } from "./types.ts";
 import { blank, textBlock, vstack } from "./util.ts";
 
@@ -34,9 +35,17 @@ export function renderTree(root: El, width: number, state: WState, services: Ser
 	return { block, warnings };
 }
 
+/**
+ * The net under every component. Each one shortens its own text or scrolls on its own, so nothing is wider than its pane today; a
+ * component that is wider anyway (a new one, a layout that cannot give) gets the pan bar here, never a silent cut by the widget.
+ */
+export function guardWidth(block: Block, width: number, path: string, ctx: Ctx): Block {
+	return block.w > width ? panBlock(block, width, `pan:${path}~`, ctx) : block;
+}
+
 export function renderEl(el: El, width: number, path: string, ctx: Ctx): Block {
 	try {
-		const block = renderInner(el, width, path, ctx);
+		const block = guardWidth(renderInner(el, width, path, ctx), width, path, ctx);
 		addWholeItem(el, block, path, ctx);
 		return block;
 	} catch (e) {
@@ -68,7 +77,7 @@ function renderInner(el: El, width: number, path: string, ctx: Ctx): Block {
 			return markdownBlock(String(p.text ?? ""), width, ctx, path);
 		case "CodeBlock": {
 			const id = `copy:${path}`;
-			return codeBlock(String(p.code ?? ""), p.language, p.title, width, id, ctx.state.copied === id);
+			return codeBlock(String(p.code ?? ""), p.language, p.title, width, id, ctx.state.copied === id, { ctx, key: `pan:${path}` });
 		}
 		case "Metric": {
 			const m = metric(el, width, path);
@@ -79,23 +88,23 @@ function renderInner(el: El, width: number, path: string, ctx: Ctx): Block {
 			return withTips(el, m.block, m.anchors, path, ctx, width);
 		}
 		case "Table": {
-			const t = tableBlock(p.columns ?? [], p.rows ?? [], width);
-			const anchors = new Map<string, Anchor>();
 			const cols: string[] = (p.columns ?? []).map(String);
+			const t = tableBlock(p.columns ?? [], p.rows ?? [], width, { minCol: ctx.services.settings?.tableMinCol ?? 12, pin: pinIndexes(p.pin, cols) });
+			const anchors = new Map<string, Anchor>();
 			const pad = (c: { x: number; w: number }, y: number): [number, number] => [c.x + c.w, y];
 			const lastCol = t.anchors.cols[t.anchors.cols.length - 1];
 			t.anchors.rows.forEach((r, i) => anchors.set(`row:${i + 1}`, { rect: r, badge: lastCol ? pad(lastCol, r.y) : undefined }));
-			t.anchors.cols.forEach((r, i) => anchors.set(`col:${cols[i]}`, { rect: r, badge: pad(r, r.y) }));
-			t.anchors.cells.forEach((rs, ri) => rs.forEach((r, ci) => anchors.set(`cell:${ri + 1}.${cols[ci]}`, { rect: r, badge: pad(r, r.y) })));
-			const key = `pan:${path}`;
-			const pb = panBlock(t.block, width, key, ctx);
-			const dx = pb === t.block ? 0 : ctx.state.pan[key] ?? 0;
-			if (dx) {
-				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]];
-				}
+			// the columns may be drawn in another order (pinned ones first): the names follow them
+			t.anchors.cols.forEach((r, i) => anchors.set(`col:${cols[t.order[i]]}`, { rect: r, badge: pad(r, r.y) }));
+			t.anchors.cells.forEach((rs, ri) => rs.forEach((r, ci) => anchors.set(`cell:${ri + 1}.${cols[t.order[ci]]}`, { rect: r, badge: pad(r, r.y) })));
+			// a cell that was cut to fit can be read whole: it gets a target (and a panel) of its own
+			for (const c of cutCells(t, cols, p.rows ?? [])) {
+				const a = anchors.get(c.key);
+				if (a) Object.assign(a, { full: c.full, label: c.label });
 			}
+			const key = `pan:${path}`;
+			const pb = panBlock(t.block, width, key, ctx, tablePan(t, width));
+			if (pb !== t.block) for (const [, a] of anchors) shiftAnchor(a, ctx.state.pan[key] ?? 0, frozenFor(t.frozen, width));
 			return withTips(el, pb, anchors, path, ctx, width);
 		}
 		case "BarChart": {
@@ -135,8 +144,7 @@ function renderInner(el: El, width: number, path: string, ctx: Ctx): Block {
 			const s = sequence(el, width, path);
 			const b = panBlock(s.block, width, `pan:${path}`, ctx);
 			if (b !== s.block) {
-				const pan = b.targets[0]?.pan;
-				const dx = pan ? pan.x - b.targets[0].rect.x : 0;
+				const dx = ctx.state.pan[`pan:${path}`] ?? 0;
 				for (const [, a] of s.anchors) {
 					a.rect = { ...a.rect, x: a.rect.x - dx };
 					if (a.badge) a.badge = [a.badge[0] - dx, a.badge[1]];

package/src/blocks/sequence.ts

@@ -86,14 +86,14 @@ export function sequence(el: El, width: number, path: string): { block: Block; a
 		return { heads, x, total, margin };
 	};
 	let lay = layout(48, 22);
-	for (const [cap, hc] of [[36, 22], [28, 18], [20, 14], [14, 10], [10, 8]] as const) {
+	for (const [cap, hc] of [[36, 22], [28, 18], [20, 14]] as const) {
 		if (lay.total <= width) break;
 		lay = layout(cap, hc);
 	}
-	const cap = lay.total <= width ? 48 : 10;
-	void cap;
+	// nothing fits even with the shortest labels: it will scroll, so scroll to whole labels instead of cutting them as well
+	if (lay.total > width) lay = layout(48, 22);
 	const { heads, x, total } = lay;
-	const msgCap = lay.total <= width ? 48 : 10;
+	const msgCap = 48;
 	// rows
 	const H0 = 3;
 	let y = H0;

package/src/blocks/table.ts

@@ -1,5 +1,6 @@
 import { textWidth, truncateText, type Cell, type Rect } from "../diagram/canvas.ts";
 import type { Block } from "./types.ts";
+import { frozenFor, pinBudget } from "./pan.ts";
 import { cell, fromRows, padRow, textCells } from "./util.ts";
 
 export interface TableAnchors {
@@ -10,23 +11,81 @@ export interface TableAnchors {
 
 const NUMERIC = /^[-+]?[\d.,]+\s*(%|ms|s|kb|mb|gb|tb|x)?$/i;
 
-export function tableBlock(columns: string[], rows: Array<Array<string | number>>, width: number): { block: Block; anchors: TableAnchors } {
+/**
+ * `opts.minCol` is the user's minimum column width. With it, a table that does not fit shrinks its widest columns only down to
+ * min(natural, minCol); if even that does not fit, every column takes its natural width and the block is wider than the pane (the
+ * caller scrolls it): a table that scrolls cuts nothing, whatever a cell holds. Without it (a markdown table, which has nowhere to scroll) the old rule stands: columns shrink
+ * to three characters and no further. `edges` are the left borders of the columns, so a scroll step can land on one.
+ *
+ * `opts.pin` lists the columns (indexes) that stay in place while the table scrolls; left out, nothing is pinned and the whole table
+ * scrolls. Only a table that is wider than the pane has pinned columns, and then they are drawn first, in the order they have in the
+ * table (`order` says which column is where). They take at most half the pane (`pinBudget`): they are considered in the order
+ * listed, and one that does not fit is skipped. It is never squeezed: a pinned column that lost text could not be scrolled to.
+ * `frozen` is their width with their borders, 0 when nothing is pinned.
+ */
+export interface TableBlock {
+	block: Block;
+	anchors: TableAnchors;
+	edges: number[];
+	frozen: number;
+	order: number[];
+	/** per body row and drawn column: the cell was cut to fit (it ends in an ellipsis). Only a table that fits by squeezing cuts anything. */
+	cut: boolean[][];
+	/** per drawn column: the header was cut */
+	headCut: boolean[];
+}
+
+export function tableBlock(columns: string[], rows: Array<Array<string | number>>, width: number, opts: { minCol?: number; pin?: number[] } = {}): TableBlock {
 	const n = Math.max(1, columns.length);
 	const str = (v: string | number) => String(v ?? "").replace(/\s+/g, " ").trim();
-	const data = rows.map((r) => columns.map((_, i) => str(r[i] ?? "")));
-	const heads = columns.map(str);
-	const numeric = heads.map((_, i) => data.length > 0 && data.every((r) => r[i] === "" || NUMERIC.test(r[i])));
-	const nat = heads.map((h, i) => Math.max(textWidth(h), ...data.map((r) => textWidth(r[i])), 1));
+	const data0 = rows.map((r) => columns.map((_, i) => str(r[i] ?? "")));
+	const heads0 = columns.map(str);
+	const numeric0 = heads0.map((_, i) => data0.length > 0 && data0.every((r) => r[i] === "" || NUMERIC.test(r[i])));
+	const nat = heads0.map((h, i) => Math.max(textWidth(h), ...data0.map((r) => textWidth(r[i])), 1));
 	const avail = Math.max(n, width - (3 * n + 1));
-	const w = nat.slice();
-	let sum = w.reduce((a, b) => a + b, 0);
-	while (sum > avail) {
-		let k = 0;
-		for (let i = 1; i < n; i++) if (w[i] > w[k]) k = i;
-		if (w[k] <= 3) break;
-		w[k]--;
-		sum--;
+	const sum = (a: number[]) => a.reduce((x, y) => x + y, 0);
+	const minCol = opts.minCol ?? 3;
+	const floors = nat.map((x) => Math.min(x, minCol));
+	let w = nat.slice();
+	let order = heads0.map((_, i) => i);
+	let frozen = 0;
+	if (sum(w) > avail) {
+		if (sum(floors) <= avail || opts.minCol === undefined) {
+			// shrink the widest column, one character at a time, never below its floor
+			let total = sum(w);
+			while (total > avail) {
+				let k = -1;
+				for (let i = 0; i < n; i++) if (w[i] > floors[i] && (k < 0 || w[i] > w[k])) k = i;
+				if (k < 0) break;
+				w[k]--;
+				total--;
+			}
+		} else {
+			// the floors do not fit either: every column at its natural width, the table is wider than the pane and scrolls, and what
+			// the model asked to pin is pinned if there is room for it
+			w = nat.slice();
+			const budget = pinBudget(width);
+			const chosen: number[] = [];
+			let used = 1; // the left border
+			for (const i of opts.pin ?? []) {
+				if (!Number.isInteger(i) || i < 0 || i >= n || chosen.includes(i)) continue;
+				if (used + w[i] + 3 > budget) continue; // not squeezed: text that is cut here could never be scrolled to
+				used += w[i] + 3;
+				chosen.push(i);
+			}
+			if (chosen.length && chosen.length < n) {
+				chosen.sort((a, b) => a - b);
+				order = [...chosen, ...order.filter((i) => !chosen.includes(i))];
+				frozen = used;
+			}
+		}
 	}
+	// from here on the columns are in the order they are drawn
+	const by = <T>(a: T[]): T[] => order.map((i) => a[i]);
+	const heads = by(heads0);
+	const data = data0.map(by);
+	const numeric = by(numeric0);
+	w = by(w);
 	const total = w.reduce((a, b) => a + b, 0) + 3 * n + 1;
 	const line = (l: string, m: string, r: string): Cell[] => {
 		const out: Cell[] = [cell(l, "table.border")];
@@ -66,5 +125,54 @@ export function tableBlock(columns: string[], rows: Array<Array<string | number>
 		rows: data.map((_, ri) => ({ x: 0, y: 3 + ri, w: total, h: 1 })),
 		cells: data.map((_, ri) => w.map((cw, i) => ({ x: colX[i], y: 3 + ri, w: cw, h: 1 }))),
 	};
-	return { block: fromRows(total, out.map((r) => padRow(r, total))), anchors };
+	return {
+		block: fromRows(total, out.map((r) => padRow(r, total))),
+		anchors,
+		edges: colX.map((x) => x - 2),
+		frozen,
+		order,
+		cut: data.map((r) => r.map((v, i) => textWidth(v) > w[i])),
+		headCut: heads.map((h, i) => textWidth(h) > w[i]),
+	};
+}
+
+/**
+ * How `panBlock` should scroll a table. With the first column frozen the window starts F cells after the offset, so an offset that
+ * puts a column border there is the border's position minus F (and the start, 0, stays a place to stop). Without that a step lands
+ * in the middle of a column.
+ */
+export function tablePan(t: { edges: number[]; frozen: number }, width: number): { edges: number[]; frozen: number } {
+	const F = frozenFor(t.frozen, width);
+	return { edges: F ? [0, ...t.edges.map((e) => e - F).filter((e) => e > 0)] : t.edges, frozen: t.frozen };
+}
+
+/**
+ * The columns a Table's `pin` names, as indexes: by header, the way the table draws it (spacing collapsed). Undefined when the
+ * model did not say (the first column is pinned then); a name that matches nothing is left out.
+ */
+export function pinIndexes(pin: unknown, columns: string[]): number[] | undefined {
+	if (!Array.isArray(pin)) return undefined;
+	const norm = (v: unknown) => String(v ?? "").replace(/\s+/g, " ").trim();
+	const heads = columns.map(norm);
+	return pin.map((name) => heads.indexOf(norm(name))).filter((i) => i >= 0);
+}
+
+/**
+ * The cells a table cut to fit, each with what it takes to read it whole: the anchor key a tooltip would use (`cell:3.Notes`,
+ * `col:Notes`), where it is drawn, its full text as it was written, and a short name for the hover line. For a Table and a
+ * Markdown table alike.
+ */
+export function cutCells(t: TableBlock, columns: string[], rows: Array<Array<string | number>>): Array<{ key: string; rect: Rect; full: string; label: string }> {
+	const out: Array<{ key: string; rect: Rect; full: string; label: string }> = [];
+	const head = columns.map((c) => String(c ?? ""));
+	t.headCut.forEach((cut, ci) => {
+		if (cut) out.push({ key: `col:${head[t.order[ci]]}`, rect: t.anchors.cols[ci], full: head[t.order[ci]].trim(), label: `column ${head[t.order[ci]].replace(/\s+/g, " ").trim()}` });
+	});
+	t.cut.forEach((row, ri) =>
+		row.forEach((cut, ci) => {
+			const col = t.order[ci];
+			if (cut) out.push({ key: `cell:${ri + 1}.${head[col]}`, rect: t.anchors.cells[ri][ci], full: String(rows[ri]?.[col] ?? "").trim(), label: `${head[col].replace(/\s+/g, " ").trim()}, row ${ri + 1}` });
+		}),
+	);
+	return out;
 }

package/src/blocks/types.ts

@@ -10,6 +10,8 @@ export interface Tip {
 	tone?: string;
 	link?: string;
 	linkLabel?: string;
+	/** the whole text of a cell that was cut to fit the pane: the panel shows it as plain text, under whatever else the tip says */
+	full?: string;
 }
 
 export type TargetKind =
@@ -33,7 +35,11 @@ export type TargetKind =
 	| "noteadd"
 	| "noteclear"
 	/** the footer chip that turns notes mode on and off */
-	| "notes";
+	| "notes"
+	/** a part of the pan bar under a block that is wider than its pane: the left arrow, the right arrow or the track */
+	| "pan"
+	/** the area of a clipped block, body and bar. Never reachable: the widget asks which one is under a wheel or a drag */
+	| "panarea";
 
 /** What a note says about the element it is attached to. All words are already cleaned for a message the user will send. */
 export interface ItemInfo {
@@ -87,7 +93,11 @@ export interface Target {
 	/** for kind "image": where the picture goes and how big it is, in cells */
 	image?: { key: string; cols: number; rows: number };
 	/** a diagram that may be wider than its view: focusing this target should reveal it */
-	pan?: { key: string; x: number; w: number; view: number; total: number };
+	/** `min` is where the scrolling part begins when the first columns are frozen: what is left of it is behind them */
+	pan?: { key: string; x: number; w: number; view: number; total: number; min?: number };
+	/** for kind "pan": which part of which bar this is, and what it needs to move the offset */
+	/** `left`/`right` are the fine arrows (`step` cells), `pageleft`/`pageright` the page arrows (three quarters of the pane, to a column edge) */
+	scroll?: { key: string; part: "left" | "right" | "pageleft" | "pageright" | "track"; total: number; view: number; edges?: number[]; step?: number };
 }
 
 export interface Block {
@@ -129,6 +139,8 @@ export interface ImageService {
 
 export interface Services {
 	images?: ImageService;
+	/** the user's settings (src/pi/config.ts); the defaults when absent */
+	settings?: { tableMinCol: number; scrollStep: number };
 }
 
 export interface Ctx {