tablewalk 0.0.1

package/dist/client/diagram.js

@@ -0,0 +1,885 @@
+/**
+ * The entity diagram.
+ *
+ * Scoped to one table's neighbourhood rather than the whole schema, because a
+ * whole-schema diagram of anything real is a hairball nobody reads. The
+ * layout axis is direction, which is the same axis the tool navigates on:
+ * what this table points at on the left, the table itself in the middle, what
+ * points back at it on the right. That makes the picture answer the same
+ * question the record view answers, in one glance instead of one click.
+ */
+import { state, el, svgEl, findTable, go, labelColumn, tableView } from './core.js';
+import { picker } from './picker.js';
+import { schemaExportControl } from './schemaexport.js';
+
+
+const NODE_W = 216;
+const HEAD_H = 30;
+const FIELD_H = 17;
+const NODE_PAD = 5;
+const ROW_GAP = 18;
+const COL_GAP = 156;
+
+/**
+ * How many columns a node shows before it has to be asked for more.
+ *
+ * A node is a label with context, not a table definition. Five is enough to
+ * carry the key, the references and the column that says what the row is —
+ * which is what the diagram is being read for — while keeping a neighbour
+ * roughly the height of the focus table rather than a column of forty names
+ * that pushes everything else off the canvas.
+ */
+const PREVIEW_FIELDS = 5;
+
+/** Characters an edge label can carry before it would reach a node. */
+const EDGE_LABEL_BUDGET = 22;
+
+/** Nodes the reader has opened, by table id. Survives a re-render. */
+const expanded = new Set();
+
+/**
+ * The columns worth showing first.
+ *
+ * Ordered by what identifies and connects rather than by declaration order:
+ * the key says which row, the foreign keys say what it hangs off, and the
+ * label column says what it is. A preview that happened to show `notes` and
+ * `external_ref` would be five rows of nothing.
+ */
+function orderedColumns(table) {
+  const label = labelColumn(table);
+  const rank = (c) => {
+    if (c.primaryKey) return 0;
+    if (c.references) return 1;
+    if (c.name === label) return 2;
+    return 3;
+  };
+  return [...table.columns]
+    .map((c, i) => ({ c, i }))
+    .sort((a, b) => rank(a.c) - rank(b.c) || a.i - b.i)
+    .map(({ c }) => c);
+}
+
+/**
+ * Type names, shortened to fit beside a column name.
+ *
+ * Postgres spells its timestamps `timestamp with time zone`, which at the
+ * width of a node runs straight through the column name to its left. The
+ * abbreviations are the ones Postgres itself accepts as aliases, so this
+ * shortens the spelling without renaming the type; anything unrecognised is
+ * truncated rather than guessed at.
+ */
+const TYPE_ALIAS = new Map([
+  ['timestamp with time zone', 'timestamptz'],
+  ['timestamp without time zone', 'timestamp'],
+  ['time with time zone', 'timetz'],
+  ['time without time zone', 'time'],
+  ['character varying', 'varchar'],
+  ['character', 'char'],
+  ['double precision', 'float8'],
+  ['integer', 'int'],
+  ['boolean', 'bool'],
+]);
+
+/** Characters that fit before name and type would touch. */
+const NAME_BUDGET = 18;
+const TYPE_BUDGET = 12;
+
+const clip = (text, max) => (text.length > max ? `${text.slice(0, max - 1)}\u2026` : text);
+
+function shortType(type) {
+  if (!type) return '';
+  const lower = type.toLowerCase();
+  const alias = TYPE_ALIAS.get(lower)
+    ?? TYPE_ALIAS.get(lower.replace(/\(.*\)$/, '').trim());
+  return clip(alias ?? type, TYPE_BUDGET);
+}
+
+function nodeHeight(tableId, preview = PREVIEW_FIELDS) {
+  const table = findTable(tableId);
+  if (!table?.columns.length) return HEAD_H;
+  const total = table.columns.length;
+  const shown = expanded.has(tableId) ? total : Math.min(preview, total);
+  const more = shown < total || expanded.has(tableId) ? 1 : 0;
+  if (!shown && !more) return HEAD_H;
+  return HEAD_H + NODE_PAD + (shown + more) * FIELD_H + NODE_PAD;
+}
+
+/**
+ * Wrap an SVG in a viewport that can be panned and zoomed.
+ *
+ * A sixty-six table schema is about four thousand pixels wide. Scaled to fit
+ * a panel it is a picture of a schema rather than a readable one — every
+ * table name too small to read, which is the one thing a diagram has to do.
+ *
+ * So the picture keeps its natural size and the window moves over it: drag to
+ * pan, wheel or pinch to zoom, and a control to fit the whole thing when you
+ * want the shape rather than the detail. The transform lives on a single
+ * group so panning is one attribute write per frame rather than a re-layout.
+ *
+ * @param {SVGElement} svg      sized to its natural width and height
+ * @param {SVGElement} content  the group everything was drawn into
+ * @param {{width: number, height: number}} size  the drawing's natural size
+ * @param {{x: number, y: number}} [focus]  a point worth opening centred on
+ */
+function panZoom(svg, content, size, focus) {
+  const viewport = el('div', { class: 'diagram-viewport' });
+  /* No viewBox.
+
+     A viewBox is itself a scale — it fits the drawing to the element — so
+     leaving one in place meant every zoom factor was multiplied by it, and
+     "fit" landed at 43% of an already-shrunk picture. Filling the element and
+     letting the single transform on the content group do all the scaling
+     makes one user unit one CSS pixel, which is what makes 1:1 mean 1:1. */
+  svg.removeAttribute('viewBox');
+  svg.style.width = '100%';
+  svg.style.height = '100%';
+
+  let scale = 1;
+  let x = 0;
+  let y = 0;
+
+  const MIN = 0.15;
+  const MAX = 3;
+
+  const apply = () => {
+    content.setAttribute('transform', `translate(${x} ${y}) scale(${scale})`);
+    readout.textContent = `${Math.round(scale * 100)}%`;
+  };
+
+  /* Zoom about a point, so the thing under the cursor stays under it. Zooming
+     about the origin instead makes the diagram appear to run away from you
+     the moment you are not looking at its top-left corner. */
+  const zoomAt = (factor, px, py) => {
+    const next = Math.min(MAX, Math.max(MIN, scale * factor));
+    if (next === scale) return;
+    x = px - ((px - x) * next) / scale;
+    y = py - ((py - y) * next) / scale;
+    scale = next;
+    apply();
+  };
+
+  const fit = () => {
+    const box = viewport.getBoundingClientRect();
+    if (!box.width) return false;
+    /* Never enlarges. Fitting is about getting the whole thing on screen, and
+       a three-table diagram blown up to 300% to fill the box is not a better
+       answer to "show me all of it" — it is the same answer, shouting. Below
+       100% it shrinks as far as it must. */
+    scale = Math.min(1, Math.max(MIN, Math.min(
+      (box.width - 24) / size.width,
+      (box.height - 24) / size.height,
+    )));
+    // Centred on both axes: a wide, short schema fitted by width leaves the
+    // drawing pinned to the top of a mostly empty box, which reads as broken
+    // rather than as fitted.
+    x = (box.width - size.width * scale) / 2;
+    y = (box.height - size.height * scale) / 2;
+    apply();
+    return true;
+  };
+
+  const reset = () => {
+    const box = viewport.getBoundingClientRect();
+    scale = 1;
+    /* Centred, not parked in the corner. At 1:1 a diagram smaller than its
+       panel should sit in the middle of it; one larger than the panel opens
+       on its middle, which is where the focus table is. */
+    x = Math.min(12, (box.width - size.width) / 2);
+    y = Math.min(12, (box.height - size.height) / 2);
+    apply();
+  };
+
+  const readout = el('span', { class: 'zoom-readout', text: '100%' });
+  const controls = el('div', { class: 'zoom-controls' }, [
+    el('button', { type: 'button', class: 'ghost', title: 'Zoom out', 'aria-label': 'Zoom out', text: '\u2212',
+      onclick: () => { const b = viewport.getBoundingClientRect(); zoomAt(1 / 1.25, b.width / 2, b.height / 2); } }),
+    readout,
+    el('button', { type: 'button', class: 'ghost', title: 'Zoom in', 'aria-label': 'Zoom in', text: '+',
+      onclick: () => { const b = viewport.getBoundingClientRect(); zoomAt(1.25, b.width / 2, b.height / 2); } }),
+    el('button', { type: 'button', class: 'ghost', text: 'Fit', title: 'Fit the whole diagram', onclick: fit }),
+    el('button', { type: 'button', class: 'ghost', text: '1:1', title: 'Actual size', onclick: reset }),
+  ]);
+
+  /* Wheel zooms rather than scrolls. The diagram fills its viewport, so a
+     wheel here is a gesture aimed at the picture, not at the page — and a
+     trackpad pinch arrives as a ctrl-wheel, which this handles identically.
+     Shift+wheel pans sideways, matching what every other canvas does. */
+  viewport.addEventListener('wheel', (e) => {
+    e.preventDefault();
+    const box = viewport.getBoundingClientRect();
+    const px = e.clientX - box.left;
+    const py = e.clientY - box.top;
+    if (e.shiftKey && !e.ctrlKey) {
+      x -= e.deltaY || e.deltaX;
+      apply();
+      return;
+    }
+    zoomAt(Math.exp(-e.deltaY / 400), px, py);
+  }, { passive: false });
+
+  /* Dragging the background pans; dragging starts only where there is no node
+     under the pointer, so clicking a table still navigates. */
+  let dragging = null;
+  viewport.addEventListener('pointerdown', (e) => {
+    if (e.button !== 0) return;
+    /* The controls sit inside the viewport, so a press on one would otherwise
+       start a pan and capture the pointer — which swallowed the click before
+       the button ever saw it, and made Fit look broken. */
+    if (e.target.closest('.node-head, .node-more, .zoom-controls')) return;
+    dragging = { px: e.clientX, py: e.clientY, x, y };
+    viewport.setPointerCapture(e.pointerId);
+    viewport.classList.add('dragging');
+  });
+  viewport.addEventListener('pointermove', (e) => {
+    if (!dragging) return;
+    x = dragging.x + (e.clientX - dragging.px);
+    y = dragging.y + (e.clientY - dragging.py);
+    apply();
+  });
+  const endDrag = () => {
+    dragging = null;
+    viewport.classList.remove('dragging');
+  };
+  viewport.addEventListener('pointerup', endDrag);
+  viewport.addEventListener('pointercancel', endDrag);
+
+  viewport.append(svg, controls);
+
+  /* How the diagram opens: fitted when fitting is readable, centred on the
+     focus when it is not.
+
+     Fit was the unconditional opening move, and on a table with seventeen
+     relationships it landed at 27% — a postage stamp in a sea of margin,
+     with every name too small to read. The whole point of the picture is the
+     names. So when fitting would shrink below the point of legibility, the
+     diagram opens at full size centred on the table it is about instead:
+     readable immediately, with Fit one click away for the shape. A drawing
+     with no focus point — the whole-schema view — still opens fitted,
+     because there is no one table to centre on. */
+  const READABLE = 0.5;
+  const open = () => {
+    const box = viewport.getBoundingClientRect();
+    if (!box.width) return false;
+    const fitted = Math.min((box.width - 24) / size.width, (box.height - 24) / size.height);
+    if (!focus || fitted >= READABLE) return fit();
+    scale = 1;
+    x = box.width / 2 - focus.x;
+    y = box.height / 2 - focus.y;
+    apply();
+    return true;
+  };
+
+  /* Opening needs a measured viewport, which does not exist until the node is
+     in the document — and a single rAF is not a guarantee of that, which is
+     how a repainted diagram ended up parked at the top-left corner of an
+     otherwise empty box. The observer waits for a real size and then gets out
+     of the way, so a later resize does not throw away the reader's panning. */
+  if (!open()) {
+    const watch = new ResizeObserver(() => { if (open()) watch.disconnect(); });
+    watch.observe(viewport);
+  }
+  return viewport;
+}
+
+export function diagram(tableId) {
+  const host = el('div', { class: 'diagram' });
+  const paint = () => host.replaceChildren(...neighbourhood(tableId, paint));
+  paint();
+  return host;
+}
+
+/**
+ * @param {string} tableId
+ * @param {() => void} repaint  called when a node is expanded or collapsed
+ */
+function neighbourhood(tableId, repaint) {
+  const focus = findTable(tableId);
+  if (!focus) return [el('p', { class: 'note', text: 'Unknown table.' })];
+
+  const out = state.schema.foreignKeys.filter((fk) => fk.from.table === tableId && fk.to.table !== tableId);
+  const back = state.schema.foreignKeys.filter((fk) => fk.to.table === tableId && fk.from.table !== tableId);
+  const self = state.schema.foreignKeys.filter((fk) => fk.from.table === tableId && fk.to.table === tableId);
+
+  // Several keys can join the same pair of tables; one node per table, with
+  // the columns collected onto the edge, keeps the picture readable.
+  const group = (keys, side) => {
+    const byTable = new Map();
+    for (const fk of keys) {
+      const other = side === 'out' ? fk.to.table : fk.from.table;
+      const entry = byTable.get(other) ?? { table: other, columns: [] };
+      entry.columns.push(fk.from.columns.join(', '));
+      byTable.set(other, entry);
+    }
+    return [...byTable.values()];
+  };
+
+  const left = group(out, 'out');
+  const right = group(back, 'in');
+
+  if (!left.length && !right.length && !self.length) {
+    return [el('p', { class: 'note', text: `${tableId} has no foreign keys in either direction.` })];
+  }
+
+  /* Laid out from measured heights rather than a fixed row pitch.
+
+     Once a node can be opened, two nodes in the same column are no longer the
+     same height, and a constant pitch either overlaps the tall ones or leaves
+     a gap the size of the tallest under every short one. Each column is
+     stacked by accumulating real heights and then centred as a block. */
+  const stack = (nodes) => {
+    const heights = nodes.map((n) => nodeHeight(n.table));
+    const total = heights.reduce((a, b) => a + b, 0) + Math.max(0, nodes.length - 1) * ROW_GAP;
+    let offset = 0;
+    const tops = heights.map((h) => {
+      const at = offset;
+      offset += h + ROW_GAP;
+      return at;
+    });
+    return { total, tops };
+  };
+
+  const l = stack(left);
+  const r = stack(right);
+  const focusHeight = nodeHeight(tableId);
+  const selfRoom = self.length ? 46 : 0;
+
+  const extent = Math.max(l.total, r.total, focusHeight);
+  const height = extent + selfRoom + 30;
+  const columns = 1 + (left.length ? 1 : 0) + (right.length ? 1 : 0);
+  const width = NODE_W * columns + COL_GAP * (columns - 1);
+
+  const top = (blockTotal) => selfRoom + 15 + (extent - blockTotal) / 2;
+  const leftX = 0;
+  const midX = left.length ? NODE_W + COL_GAP : 0;
+  const rightX = midX + NODE_W + COL_GAP;
+  const focusTop = top(focusHeight);
+  // Edges meet a node at its header, which stays put as the body grows.
+  const focusAnchor = focusTop + HEAD_H / 2;
+
+  const svg = svgEl('svg', {
+    viewBox: `0 0 ${width} ${height}`,
+    style: `width:${width}px; max-width:100%`,
+    role: 'img',
+    'aria-label': `Foreign key neighbourhood of ${tableId}`,
+  });
+
+  const defs = svgEl('defs', {}, svgEl('marker', {
+    id: 'arrow', viewBox: '0 0 8 8', refX: 7, refY: 4,
+    markerWidth: 7, markerHeight: 7, orient: 'auto-start-reverse',
+  }, svgEl('path', { d: 'M0,0 L8,4 L0,8 z', class: 'edge-head' })));
+  // Everything is drawn into one group, which is what pan and zoom move.
+  const content = svgEl('g');
+  svg.append(defs, content);
+
+  left.forEach((node, i) => {
+    const nodeTop = top(l.total) + l.tops[i];
+    content.append(edge(leftX + NODE_W, nodeTop + HEAD_H / 2, midX, focusAnchor, node.columns.join(' · '), 'out'));
+    content.append(nodeBox(node.table, leftX, nodeTop, 'out', repaint));
+  });
+  right.forEach((node, i) => {
+    const nodeTop = top(r.total) + r.tops[i];
+    content.append(edge(rightX, nodeTop + HEAD_H / 2, midX + NODE_W, focusAnchor, node.columns.join(' · '), 'in'));
+    content.append(nodeBox(node.table, rightX, nodeTop, 'in', repaint));
+  });
+
+  if (self.length) {
+    // A self-reference has nowhere else to go, so it loops above the node.
+    const y = focusTop;
+    content.append(svgEl('path', {
+      class: 'edge',
+      'marker-end': 'url(#arrow)',
+      d: `M${midX + NODE_W * 0.3},${y} C${midX + NODE_W * 0.1},${y - 34} ${midX + NODE_W * 0.9},${y - 34} ${midX + NODE_W * 0.7},${y}`,
+    }));
+    content.append(svgEl('text', {
+      x: midX + NODE_W / 2, y: y - 22, class: 'edge-label', 'text-anchor': 'middle',
+    }, document.createTextNode(self.map((fk) => fk.from.columns.join(', ')).join(' · '))));
+  }
+
+  content.append(nodeBox(tableId, midX, focusTop, 'focus', repaint));
+
+  const legend = el('p', { class: 'diagram-legend' }, [
+    el('span', { class: 'legend-out', text: 'points at →' }),
+    el('span', { text: `  ${focus.name}  ` }),
+    el('span', { class: 'legend-in', text: '← pointed at by' }),
+  ]);
+
+  /* One table and its neighbours is a selection like any other, and the one
+     people most often want to paste into a ticket. */
+  const drawn = new Set([tableId, ...out.map((fk) => fk.to.table), ...back.map((fk) => fk.from.table)]);
+
+  return [
+    el('div', { class: 'diagram-head' }, [
+      el('h2', { class: 'diagram-title', text: `${focus.name} and what it touches` }),
+      schemaExportControl({ only: drawn, picture: () => ({ svg, size: { width, height } }) }),
+    ]),
+    panZoom(svg, content, { width, height }, { x: midX + NODE_W / 2, y: focusAnchor }),
+    legend,
+  ];
+}
+
+/**
+ * One table, as a header and a list of its columns.
+ *
+ * The header navigates and the body does not, which is the distinction that
+ * lets the node be both a link and something you can read. Opening a node to
+ * see its columns should not also leave the page you opened it from.
+ */
+function nodeBox(tableId, x, y, role, repaint, { preview = PREVIEW_FIELDS, attrs = {} } = {}) {
+  const table = findTable(tableId);
+  const height = nodeHeight(tableId, preview);
+  const g = svgEl('g', { class: `node node-${role}`, ...attrs });
+
+  g.append(svgEl('rect', { x, y, width: NODE_W, height, rx: 5 }));
+
+  const head = svgEl('g', {
+    class: 'node-head',
+    // Clicking a node walks there, so the diagram is navigation and not just
+    // a picture of the schema.
+    onclick: () => go(tableView(tableId), role === 'focus' ? 'replace' : 'reset'),
+    role: 'button',
+    tabindex: 0,
+    onkeydown: (e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); go(tableView(tableId), 'reset'); } },
+  });
+  head.append(svgEl('rect', { x, y, width: NODE_W, height: HEAD_H, rx: 5, class: 'node-head-hit' }));
+  head.append(svgEl('title', {}, document.createTextNode(
+    table ? `${tableId} — ${table.columns.length} columns` : tableId,
+  )));
+  const label = tableId.length > 22 ? `${tableId.slice(0, 21)}…` : tableId;
+  head.append(svgEl('text', { x: x + 10, y: y + HEAD_H / 2 + 4 }, document.createTextNode(label)));
+  g.append(head);
+
+  if (!table?.columns.length) return g;
+
+  const ordered = orderedColumns(table);
+  const open = expanded.has(tableId);
+  const shown = open ? ordered : ordered.slice(0, preview);
+  const hidden = ordered.length - shown.length;
+
+  if (shown.length) {
+    g.append(svgEl('line', {
+      class: 'node-rule', x1: x, x2: x + NODE_W, y1: y + HEAD_H, y2: y + HEAD_H,
+    }));
+  }
+
+  shown.forEach((col, i) => {
+    const cy = y + HEAD_H + NODE_PAD + i * FIELD_H + FIELD_H - 5;
+    const mark = col.primaryKey ? '\u25c6' : col.references ? '\u2192' : '';
+    const field = svgEl('text', {
+      x: x + 10, y: cy,
+      class: `node-field${col.primaryKey ? ' is-key' : ''}${col.references ? ' is-ref' : ''}`,
+    }, document.createTextNode(`${mark ? `${mark} ` : ''}${clip(col.name, NAME_BUDGET)}`));
+    // The full name and type stay reachable even when both are shortened.
+    field.append(svgEl('title', {}, document.createTextNode(`${col.name} ${col.type ?? ''}`.trim())));
+    g.append(field);
+    g.append(svgEl('text', {
+      x: x + NODE_W - 10, y: cy, class: 'node-type', 'text-anchor': 'end',
+    }, document.createTextNode(shortType(col.type))));
+  });
+
+  /* The toggle only exists when there is something behind it. A node whose
+     five columns are all of its columns is already fully shown, and "+0 more"
+     would be a control that does nothing. */
+  if (hidden > 0 || open) {
+    const cy = y + HEAD_H + NODE_PAD + shown.length * FIELD_H + FIELD_H - 5;
+    const toggle = () => {
+      if (open) expanded.delete(tableId); else expanded.add(tableId);
+      repaint();
+    };
+    const more = svgEl('g', {
+      class: 'node-more',
+      role: 'button',
+      tabindex: 0,
+      onclick: (e) => { e.stopPropagation(); toggle(); },
+      onkeydown: (e) => {
+        if (e.key !== 'Enter' && e.key !== ' ') return;
+        e.preventDefault();
+        toggle();
+      },
+    });
+    more.append(svgEl('rect', {
+      x, y: cy - FIELD_H + 4, width: NODE_W, height: FIELD_H, class: 'node-more-hit',
+    }));
+    more.append(svgEl('text', { x: x + 10, y: cy }, document.createTextNode(
+      open ? '\u2212 show less' : `+ ${hidden} ${shown.length ? 'more' : 'columns'}`,
+    )));
+    g.append(more);
+  }
+
+  return g;
+}
+
+function edge(x1, y1, x2, y2, label, side = 'out') {
+  const g = svgEl('g');
+  const mid = (x1 + x2) / 2;
+  g.append(svgEl('path', {
+    class: 'edge',
+    'marker-end': 'url(#arrow)',
+    d: `M${x1},${y1} C${mid},${y1} ${mid},${y2} ${x2},${y2}`,
+  }));
+  if (label) {
+    /* Horizontally centred in the gap between the two columns, vertically
+       parked on its own node's row.
+       
+       The vertical part is what keeps five labels apart: every edge converges
+       on the focus table, so labels placed at the curve's midpoint converge
+       too and none of them is readable. The horizontal part is what keeps
+       them off the boxes — anchored beside its source node instead, a long
+       column name ran the width of the gap and printed itself over the focus
+       table's first field. */
+    const text = svgEl('text', {
+      x: mid,
+      y: y1 - 6,
+      class: 'edge-label',
+      'text-anchor': 'middle',
+    }, document.createTextNode(label.length > EDGE_LABEL_BUDGET
+      ? `${label.slice(0, EDGE_LABEL_BUDGET - 1)}\u2026`
+      : label));
+    // Truncated labels keep the full list of columns on hover.
+    text.append(svgEl('title', {}, document.createTextNode(label)));
+    g.append(text);
+  }
+  return g;
+}
+
+/* ---------- the whole schema ----------
+
+   A different problem from the neighbourhood view. Every table at once is a
+   hairball unless the layout says something, so this one ranks tables by
+   dependency depth: tables that reference nothing sit in the first column,
+   tables that reference only those in the second, and so on. Reading left to
+   right is reading the order you would have to insert rows in.
+
+   That ordering is also the useful one for the questions people bring to a
+   schema they do not know — where does this start, what is a leaf, what is
+   the join table in the middle. Alphabetical would tell you nothing. */
+
+const S_COL_GAP = 96;
+const S_ROW_GAP = 18;
+
+/**
+ * Above this many tables, nodes start as headers only.
+ *
+ * The column list is what makes a node readable; on a schema of two hundred
+ * tables it is also what makes the picture a mile tall before anyone has
+ * asked a question. Past the threshold every node keeps its "+ n columns"
+ * toggle, so the detail is one click away rather than absent.
+ */
+const DENSE_SCHEMA = 24;
+
+/** Longest chain of references out of each table, capped against cycles. */
+function dependencyDepth(tables, keys) {
+  const out = new Map(tables.map((t) => [t.id, []]));
+  for (const fk of keys) {
+    if (fk.from.table === fk.to.table) continue; // a self-reference adds no depth
+    out.get(fk.from.table)?.push(fk.to.table);
+  }
+  const depth = new Map();
+  const visiting = new Set();
+  const walk = (id) => {
+    if (depth.has(id)) return depth.get(id);
+    // A cycle has no well-defined depth; breaking it at 0 keeps the layout
+    // stable instead of recursing forever on a legitimate circular schema.
+    if (visiting.has(id)) return 0;
+    visiting.add(id);
+    const targets = out.get(id) ?? [];
+    const d = targets.length ? 1 + Math.max(...targets.map(walk)) : 0;
+    visiting.delete(id);
+    depth.set(id, d);
+    return d;
+  };
+  for (const t of tables) walk(t.id);
+  return depth;
+}
+
+/**
+ * Tables the reader has pinned the diagram to. Empty means the whole schema.
+ *
+ * Kept outside the render so a repaint — expanding a node, say — does not
+ * throw the focus away.
+ */
+const focused = new Set();
+
+/** How many of a dense schema's tables the overview opens with. */
+const HUB_TABLES = 12;
+
+/* Whether the reader has asked for the whole picture despite its density.
+   Session state like `focused`: a repaint must not forget the answer. */
+let showEverything = false;
+
+/**
+ * The most-connected tables — the ones the rest of the schema hangs off.
+ *
+ * A sixty-five table schema drawn whole is a hundred and forty edges through
+ * one box of string: technically complete and readable by nobody, sitting
+ * under a prose summary that has already told the story better. So a dense
+ * schema opens on its hubs — the tables most foreign keys touch — which is
+ * the diagram that has an actual shape. Everything else is one click away:
+ * name a table to focus on it, or ask for all of it.
+ */
+function hubTables(tables, foreignKeys) {
+  const degree = new Map();
+  const bump = (id) => degree.set(id, (degree.get(id) ?? 0) + 1);
+  for (const fk of foreignKeys) {
+    bump(fk.from.table);
+    if (fk.to.table !== fk.from.table) bump(fk.to.table);
+  }
+  return [...tables]
+    // Name as the tiebreak, so the same schema always opens on the same picture.
+    .sort((a, b) => (degree.get(b.id) ?? 0) - (degree.get(a.id) ?? 0) || a.id.localeCompare(b.id))
+    .slice(0, HUB_TABLES);
+}
+
+export function schemaDiagram() {
+  const host = el('div', { class: 'diagram diagram-schema' });
+  const paint = () => host.replaceChildren(...wholeSchema(paint));
+  paint();
+  return host;
+}
+
+/**
+ * Narrow the diagram to some tables and whatever touches them.
+ *
+ * Sixty-six tables laid out at once is a true picture and an unusable one:
+ * the question people actually arrive with is "what does `sales_order` touch",
+ * and the honest answer is a diagram of eight tables, not of the schema with
+ * eight of them highlighted. One hop out rather than the full transitive
+ * closure, because two hops from anything in a schema like this is most of
+ * the schema again.
+ */
+function inScope(tables, foreignKeys) {
+  if (!focused.size) return tables;
+  const keep = new Set(focused);
+  for (const fk of foreignKeys) {
+    if (focused.has(fk.from.table)) keep.add(fk.to.table);
+    if (focused.has(fk.to.table)) keep.add(fk.from.table);
+  }
+  return tables.filter((t) => keep.has(t.id));
+}
+
+function focusBar(all, repaint) {
+  const add = (id) => {
+    if (!all.some((t) => t.id === id)) return;
+    focused.add(id);
+    repaint();
+  };
+
+  const chips = [...focused].map((id) => {
+    const table = all.find((t) => t.id === id);
+    return el('button', {
+      type: 'button', class: 'diagram-chip',
+      title: `Stop limiting to ${table?.name ?? id}`,
+      onclick: () => { focused.delete(id); repaint(); },
+    }, [
+      el('span', { text: table?.name ?? id }),
+      el('span', { class: 'chip-x', 'aria-hidden': 'true', text: '\u00d7' }),
+    ]);
+  });
+
+  /* Chips to the left of the field, not the right.
+
+     The field is the thing you come back to, and a field that slides left
+     every time a chip appears means aiming at a moving target — you add
+     `customer`, go to click the box again, and it is no longer where you
+     just were. Anchored to the right edge with the chips growing leftwards,
+     it never moves. */
+  return el('div', { class: 'diagram-focus' }, [
+    ...chips,
+    focused.size
+      ? el('button', {
+          type: 'button', class: 'ghost diagram-clear', text: 'Show all',
+          onclick: () => { focused.clear(); repaint(); },
+        })
+      : null,
+    picker({
+      items: all
+        .filter((t) => !focused.has(t.id))
+        .map((t) => ({
+          value: t.id,
+          label: t.name,
+          detail: `${t.columns.length} col${t.columns.length === 1 ? '' : 's'}`,
+        })),
+      onPick: add,
+      ariaLabel: 'Limit the diagram to these tables',
+      // Short enough to fit the field at any zoom. The instruction the long
+      // version carried is the field's own behaviour: focus it and the list
+      // of tables is right there.
+      placeholder: focused.size ? 'Add another table…' : 'Show only…',
+    }),
+  ].filter(Boolean));
+}
+
+function wholeSchema(repaint) {
+  const { tables: allTables, foreignKeys: allKeys } = state.schema;
+  if (!allTables.length) return [el('p', { class: 'note', text: 'This database has no tables.' })];
+
+  /* Dense and unfocused opens on the hubs, not the hairball. A chip in the
+     focus bar always wins — the reader named a table, so that is the
+     picture — and "Show all" is remembered for the session. */
+  const trimmed = !focused.size && !showEverything && allTables.length > DENSE_SCHEMA;
+  const tables = trimmed ? hubTables(allTables, allKeys) : inScope(allTables, allKeys);
+  const visible = new Set(tables.map((t) => t.id));
+  // Keys to tables that are out of scope would draw edges into empty space.
+  const foreignKeys = allKeys.filter((fk) => visible.has(fk.from.table) && visible.has(fk.to.table));
+
+  const preview = tables.length > DENSE_SCHEMA ? 0 : PREVIEW_FIELDS;
+
+  const depth = dependencyDepth(tables, foreignKeys);
+  const columns = new Map();
+  for (const t of tables) {
+    const d = depth.get(t.id) ?? 0;
+    if (!columns.has(d)) columns.set(d, []);
+    columns.get(d).push(t);
+  }
+  const order = [...columns.keys()].sort((a, b) => a - b);
+  for (const d of order) columns.get(d).sort((a, b) => a.id.localeCompare(b.id));
+
+  /* Every node is measured before anything is placed, because a node that has
+     been opened is taller than its neighbours and a fixed row pitch would
+     either overlap them or leave a gap the size of the tallest under each. */
+  const heights = new Map(tables.map((t) => [t.id, nodeHeight(t.id, preview)]));
+  const columnTotal = (list) =>
+    list.reduce((sum, t) => sum + heights.get(t.id), 0) + Math.max(0, list.length - 1) * S_ROW_GAP;
+
+  const tallest = Math.max(...order.map((d) => columnTotal(columns.get(d))));
+  const width = order.length * NODE_W + (order.length - 1) * S_COL_GAP;
+  const height = tallest + 24;
+
+  /* Positions are computed first so the edges can be drawn underneath every
+     node — otherwise a line crosses a box and the box looks struck through.
+     `y` is the header's centre, which is where edges meet a node. */
+  const pos = new Map();
+  order.forEach((d, col) => {
+    const list = columns.get(d);
+    let top = 12 + (tallest - columnTotal(list)) / 2;
+    for (const t of list) {
+      pos.set(t.id, { x: col * (NODE_W + S_COL_GAP), top, y: top + HEAD_H / 2 });
+      top += heights.get(t.id) + S_ROW_GAP;
+    }
+  });
+
+  const svg = svgEl('svg', {
+    viewBox: `0 0 ${width} ${height}`,
+    style: `width:${width}px; max-width:100%`,
+    role: 'img',
+    'aria-label': `Entity diagram of ${state.schema.label}`,
+  });
+  svg.append(svgEl('defs', {}, svgEl('marker', {
+    id: 'arrow-s', viewBox: '0 0 8 8', refX: 7, refY: 4,
+    markerWidth: 6, markerHeight: 6, orient: 'auto-start-reverse',
+  }, svgEl('path', { d: 'M0,0 L8,4 L0,8 z', class: 'edge-head' }))));
+  const content = svgEl('g');
+  svg.append(content);
+
+  const edges = svgEl('g', { class: 'schema-edges' });
+  for (const fk of foreignKeys) {
+    const from = pos.get(fk.from.table);
+    const to = pos.get(fk.to.table);
+    if (!from || !to) continue;
+    if (fk.from.table === fk.to.table) {
+      const x = from.x + NODE_W / 2;
+      const y = from.top;
+      edges.append(svgEl('path', {
+        class: 'edge', 'marker-end': 'url(#arrow-s)',
+        d: `M${x - 18},${y} C${x - 24},${y - 22} ${x + 24},${y - 22} ${x + 18},${y}`,
+        'data-from': fk.from.table, 'data-to': fk.to.table,
+      }));
+      continue;
+    }
+    // Leaving from whichever side faces the target keeps lines from doubling
+    // back across their own node.
+    const leftToRight = to.x >= from.x;
+    const x1 = leftToRight ? from.x + NODE_W : from.x;
+    const x2 = leftToRight ? to.x : to.x + NODE_W;
+    const mid = (x1 + x2) / 2;
+    edges.append(svgEl('path', {
+      class: 'edge', 'marker-end': 'url(#arrow-s)',
+      d: `M${x1},${from.y} C${mid},${from.y} ${mid},${to.y} ${x2},${to.y}`,
+      'data-from': fk.from.table, 'data-to': fk.to.table,
+    }));
+  }
+  content.append(edges);
+
+  for (const table of tables) {
+    const p = pos.get(table.id);
+    content.append(nodeBox(table.id, p.x, p.top, table.isView ? 'view' : 'out', repaint, {
+      preview,
+      attrs: {
+        'data-table': table.id,
+        /* Hovering a table dims everything it is not connected to. On a
+           schema with a hundred tables that is the difference between a
+           picture and an answer. */
+        onmouseenter: () => highlight(svg, table.id),
+        onmouseleave: () => highlight(svg, null),
+      },
+    }));
+  }
+
+  const counts = el('p', { class: 'diagram-legend' }, [
+    el('span', {
+      text: trimmed
+        ? `the ${tables.length} most-connected of ${allTables.length} tables · ${foreignKeys.length} foreign keys between them · `
+        : focused.size
+          ? `${tables.length} of ${allTables.length} tables · ${foreignKeys.length} foreign keys · `
+          : `${tables.length} tables · ${foreignKeys.length} foreign keys · `,
+    }),
+    el('span', { text: `${order.length} level${order.length === 1 ? '' : 's'} deep, left to right in reference order` }),
+    /* The way out of the trim, next to the sentence that admits to it — and
+       the way back, because "Show all" on a dense schema is a decision worth
+       being able to reverse without knowing which tables the hubs were. */
+    trimmed
+      ? el('button', {
+          type: 'button', class: 'ghost diagram-scope', text: `Show all ${allTables.length}`,
+          onclick: () => { showEverything = true; repaint(); },
+        })
+      : null,
+    !trimmed && !focused.size && showEverything && allTables.length > DENSE_SCHEMA
+      ? el('button', {
+          type: 'button', class: 'ghost diagram-scope', text: `Show the ${Math.min(HUB_TABLES, allTables.length)} hubs`,
+          onclick: () => { showEverything = false; repaint(); },
+        })
+      : null,
+  ].filter(Boolean));
+
+  const orphans = tables.filter((t) => !foreignKeys.some((fk) => fk.from.table === t.id || fk.to.table === t.id));
+  const note = orphans.length
+    ? el('p', { class: 'diagram-legend', text: `${orphans.length} table${orphans.length === 1 ? '' : 's'} with no foreign keys at all: ${orphans.slice(0, 6).map((t) => t.name).join(', ')}${orphans.length > 6 ? '…' : ''}` })
+    : null;
+
+  return [
+    el('div', { class: 'diagram-head' }, [
+      el('h2', { class: 'diagram-title', text: state.schema.label }),
+      focusBar(allTables, repaint),
+      /* `visible`, not `focused`: the diagram draws one hop past the chips,
+         and an export that quietly dropped that ring would not be the picture
+         anyone was looking at. */
+      schemaExportControl({
+        only: focused.size || trimmed ? visible : undefined,
+        picture: () => ({ svg, size: { width, height } }),
+      }),
+    ]),
+    panZoom(svg, content, { width, height }),
+    counts,
+    note,
+  ].filter(Boolean);
+}
+
+/** Dim everything not connected to `tableId`; pass null to clear. */
+function highlight(svg, tableId) {
+  const connected = new Set();
+  if (tableId) {
+    connected.add(tableId);
+    for (const fk of state.schema.foreignKeys) {
+      if (fk.from.table === tableId) connected.add(fk.to.table);
+      if (fk.to.table === tableId) connected.add(fk.from.table);
+    }
+  }
+  svg.classList.toggle('has-focus', Boolean(tableId));
+  for (const node of svg.querySelectorAll('.node')) {
+    node.classList.toggle('dim', Boolean(tableId) && !connected.has(node.dataset.table));
+    node.classList.toggle('lit', Boolean(tableId) && node.dataset.table === tableId);
+  }
+  for (const edge of svg.querySelectorAll('.schema-edges path')) {
+    const on = !tableId || edge.dataset.from === tableId || edge.dataset.to === tableId;
+    edge.classList.toggle('dim', !on);
+  }
+}