yichus 0.2.0 → 0.3.0

package/dist/studio-page/dom.js

@@ -0,0 +1,22 @@
+// Elements built from data. Strings become text nodes and attribute values
+// are set as attributes, so no value is ever read as markup.
+const SVG = 'http://www.w3.org/2000/svg';
+
+function build(element, attrs, children) {
+  for (const [name, value] of Object.entries(attrs ?? {})) {
+    if (value === false || value === null || value === undefined) continue;
+    if (name.startsWith('on') && typeof value === 'function') element.addEventListener(name.slice(2), value);
+    else element.setAttribute(name, value === true ? '' : String(value));
+  }
+  element.append(...children.flat(Infinity).filter(child => child !== false && child !== null && child !== undefined).map(child =>
+    child instanceof Node ? child : String(child)));
+  return element;
+}
+
+export const el = (tag, attrs, ...children) => build(document.createElement(tag), attrs, children);
+export const svg = (tag, attrs, ...children) => build(document.createElementNS(SVG, tag), attrs, children);
+
+// A visible frame around output the tool computed. Narrative and how-to-read
+// text belongs outside it, so a reader can tell the two apart.
+export const toolOutput = (label, ...children) => el('figure', { class: 'tool-output' },
+  el('figcaption', { class: 'tool-output-label' }, el('span', {}, 'Yichus output'), label), ...children);

package/dist/studio-page/label-fit.js

@@ -96,6 +96,13 @@ export function wrapText(s, size, room, mono = true, weight = 400, italic = fals
   return lines.map(l => (w(l) <= room ? l : clipText(l, size, room, mono, weight, italic, family)));
 }
 
+/** The narrowest room `wrapText` breaks `s` into without clipping: its widest
+ * piece, a word or, for a word that is broken, a part of one. */
+export function widestPiece(s, size, mono = true, weight = 400, italic = false, family = null) {
+  const w = t => textWidth(t, size, mono, weight, italic, family);
+  return Math.max(0, ...String(s).match(WORDS).filter(Boolean).flatMap(p => p.match(PARTS).filter(Boolean)).map(p => w(p.trimEnd())));
+}
+
 // A row of labels that hangs from one thing (a route: its line and its name)
 // says so: the thing's shapes carry data-anchor="<kind>:<id>", and each label
 // of the row sits in a data-bound group with the same value. Each bound

package/dist/studio-page/layer-diagram.js

@@ -0,0 +1,458 @@
+// A program's packages as a layer diagram: boxes in rows, arrows to the
+// packages each one is built from. The facts are the recorded output of
+// the real engine's layers lens (scripts/diagram-examples.mjs); this file
+// only groups and lays them out and never measures code.
+import { el, svg, toolOutput } from './dom.js';
+import { dimensions, foldGroups, groupPackages, usesElsewhere } from './layer-groups.js';
+import { textWidth, cssFont } from './label-fit.js';
+import { writeSourceLink } from './source-link.js';
+
+const evidenceRoot = new URL('evidence/diagram-examples/', import.meta.url);
+const viewerUrl = new URL('source.html', import.meta.url);
+// The recordings whose source files the site serves (deploy/manifest.json),
+// so the source viewer can open them. Any other recording names its source
+// directory as text.
+const servedSources = new Set(['structure-sqlite', 'structure-rust-analyzer', 'structure-typescript',
+  'structure-cosmic-python', 'structure-redux', 'structure-koa', 'structure-vscode']);
+const counted = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+// An edge is an import: definitions used, or types and constructors only.
+const usage = e => [e.refs ? `${counted(e.refs, 'definition')} used` : '', e.types ? `${counted(e.types, 'type')} used` : ''].filter(Boolean).join(', ');
+const minW = 150, minH = 44, growW = 110, growH = 26, inner = 12, gap = 28, rowGap = 58, labelH = 20, margin = 12;
+// A program with more packages than this opens with its groups folded.
+const foldAbove = 14;
+
+// Box text is measured in the fonts the stylesheet sets (.layer-name,
+// .layer-does, .layer-group > text), so a box is never narrower than its words.
+const mono = () => cssFont('--mono', 'monospace'), ui = () => cssFont('--font-ui', 'sans-serif');
+const nameWidth = name => textWidth(name, 12.5, true, 400, false, mono());
+const doesWidth = (does, io) => textWidth(does, 11, false, io ? 600 : 400, false, ui());
+const boxWidth = (name, does, io) => Math.max(nameWidth(name), doesWidth(does, io)) + 22;
+
+// Rows are levels from the highest down, so every arrow points down. Each
+// group is a column over the rows its members occupy. Columns go left to
+// right in an order that puts each beside the columns it connects to, and
+// each slides left until it meets a column sharing one of its rows (a
+// layout choice, not a fact). Box size grows with how much the rest of
+// the program uses the box.
+function layout(nodes, edges, columns, size) {
+  const levels = [...new Set(nodes.map(n => n.level))].sort((a, b) => b - a);
+  const row = new Map(levels.map((level, i) => [level, i]));
+  const rowOf = new Map(nodes.map(n => [n.name, row.get(n.level)]));
+  const tallest = minH + growH, rowH = tallest + rowGap;
+  const cols = columns.map((members, i) => {
+    const rows = new Map();
+    for (const m of members) rows.set(rowOf.get(m), [...(rows.get(rowOf.get(m)) ?? []), m]);
+    const lineW = ms => ms.reduce((w, m) => w + size.get(m).w, 0) + inner * (ms.length - 1);
+    const width = Math.max(...[...rows.values()].map(lineW)) + (members.length > 1 ? 2 * inner : 0);
+    return { i, members, rows, lineW, width, top: Math.min(...rows.keys()), bottom: Math.max(...rows.keys()) };
+  });
+  const colOf = new Map(cols.flatMap(c => c.members.map(m => [m, c.i])));
+  const neighbours = new Map(nodes.map(n => [n.name, []]));
+  for (const e of edges) { neighbours.get(e.from).push(e.to); neighbours.get(e.to).push(e.from); }
+  let order = cols.map(c => c.i);
+  for (let pass = 0; pass < 6; pass++) {
+    const pos = new Map(order.map((k, i) => [k, i]));
+    const pull = k => {
+      const near = cols[k].members.flatMap(m => neighbours.get(m)).map(n => pos.get(colOf.get(n)));
+      return near.length ? near.reduce((a, b) => a + b, 0) / near.length : pos.get(k);
+    };
+    const score = new Map(order.map(k => [k, pull(k)]));
+    order = [...order].sort((a, b) => score.get(a) - score.get(b) || pos.get(a) - pos.get(b));
+  }
+  // Top rows first; each column is placed under the middle of the boxes
+  // it connects to that are already placed, as far left as that allows.
+  const rank = new Map(order.map((k, i) => [k, i]));
+  const at = new Map(), outlines = [], placed = [];
+  const rowY = r => margin + labelH + r * rowH;
+  // Room at each side for an arrow that goes around a row's outer box.
+  const side = margin + gap;
+  for (const k of [...order].sort((a, b) => cols[a].top - cols[b].top || rank.get(a) - rank.get(b))) {
+    const c = cols[k];
+    const near = c.members.flatMap(m => neighbours.get(m)).filter(n => at.has(n)).map(n => at.get(n).x + at.get(n).w / 2);
+    const want = near.length ? near.reduce((a, b) => a + b, 0) / near.length - c.width / 2 : margin;
+    const left = placed.filter(o => !(c.bottom < o.top || c.top > o.bottom)).reduce((x, o) => Math.max(x, o.right + gap), side);
+    placed.push({ top: c.top, bottom: c.bottom, right: left + c.width });
+    for (const [r, ms] of c.rows) {
+      let x = left + (c.width - c.lineW(ms)) / 2;
+      for (const m of ms) {
+        const { w, h } = size.get(m);
+        at.set(m, { x, y: rowY(r) + (tallest - h) / 2, w, h });
+        x += w + inner;
+      }
+    }
+    if (c.members.length > 1)
+      outlines.push({ i: c.i, x: left, y: rowY(c.top) - 8, width: c.width, height: (c.bottom - c.top) * rowH + tallest + 16 });
+  }
+  const width = Math.max(...placed.map(o => o.right)) + side;
+  const bands = levels.map((_, r) => ({ top: rowY(r) - 8, height: tallest + 16 }));
+  // An arrow that skips rows passes each row between its boxes, never
+  // behind one: it crosses each row straight down the gap nearest the
+  // straight line from its start to its end, and bends only between rows.
+  const spans = new Map();
+  for (const [m, b] of at) {
+    const r = rowOf.get(m);
+    spans.set(r, [...(spans.get(r) ?? []), [b.x - inner / 2, b.x + b.w + inner / 2]].sort((p, q) => p[0] - q[0]));
+  }
+  const pass = (r, want) => {
+    const boxes = spans.get(r) ?? [];
+    if (!boxes.some(([l, h]) => want > l && want < h)) return want;
+    const gaps = [boxes[0][0] - gap / 2, ...boxes.slice(1).map(([l], i) => (boxes[i][1] + l) / 2), Math.min(boxes.at(-1)[1] + gap / 2, width - 4)];
+    return gaps.reduce((a, b) => Math.abs(b - want) < Math.abs(a - want) ? b : a);
+  };
+  const route = (from, to) => {
+    const a = at.get(from), b = at.get(to), ra = rowOf.get(from), rb = rowOf.get(to);
+    const start = [a.x + a.w / 2, a.y + a.h], end = [b.x + b.w / 2, b.y - 4];
+    const via = [];
+    for (let r = ra + 1; r < rb; r++) {
+      const t = (r - ra) / (rb - ra);
+      const x = pass(r, start[0] + (end[0] - start[0]) * t);
+      via.push([x, rowY(r) - 4], [x, rowY(r) + tallest + 4]);
+    }
+    return [start, ...via, end];
+  };
+  return { at, bands, outlines, width, route, height: rowY(levels.length - 1) + tallest + margin + 8 };
+}
+
+// A stack: each level is a layer, highest on top, and everything in a
+// layer is built only from layers below it. A layer's tiles wrap onto
+// more lines when the frame is narrow; a group is a tile holding its
+// packages, a line per level. Spare width on a line goes to the tiles
+// the rest of the program uses most, so a wider tile is used more (a
+// layout choice).
+// a group has no heading (its shared facts are its title), so its members start one pad below its top
+const tileGap = 8, pad = 8, headH = pad, subH = 40, oneH = 46;
+export function stackLayout(layers, width) {
+  const inside = width - 2 * margin;
+  const fill = (items, room) => {
+    const lines = [];
+    for (const item of items) {
+      const line = lines.at(-1);
+      if (line && line.reduce((w, i) => w + i.min + tileGap, item.min) <= room) line.push(item);
+      else lines.push([item]);
+    }
+    return lines.map(line => {
+      const spare = room - line.reduce((w, i) => w + i.min, 0) - tileGap * (line.length - 1);
+      const weight = line.reduce((w, i) => w + i.weight, 0);
+      let x = 0;
+      return line.map(i => { const w = i.min + spare * i.weight / weight, at = { item: i, x, w }; x += w + tileGap; return at; });
+    });
+  };
+  // Inside a group, each level of its members starts a new line, so a
+  // member sits above the members it is built from.
+  const byLevel = members => members.reduce((lines, m) => {
+    if (lines.length && lines.at(-1)[0].level === m.level) lines.at(-1).push(m); else lines.push([m]);
+    return lines;
+  }, []);
+  if (layers.some(tiles => tiles.some(t => t.min > inside))) return null;
+  const tiles = [], bands = [];
+  let y = margin;
+  for (const layer of layers) {
+    const top = y;
+    for (const line of fill(layer, inside)) {
+      const placed = line.map(({ item, x, w }) => {
+        if (!item.members) return { item, x: margin + x, w, h: oneH, subs: [] };
+        const rows = byLevel(item.members).flatMap(level => fill(level, w - 2 * pad));
+        return { item, x: margin + x, w, h: headH + rows.length * (subH + tileGap) + pad - tileGap + 4,
+          subs: rows.flatMap((row, r) => row.map(s => ({ item: s.item, x: margin + x + pad + s.x, y: headH + r * (subH + tileGap), w: s.w, h: subH }))) };
+      });
+      const h = Math.max(...placed.map(t => t.h));
+      for (const t of placed) tiles.push({ ...t, y, h, subs: t.subs.map(s => ({ ...s, y: y + s.y })) });
+      y += h + tileGap;
+    }
+    bands.push({ top: top - 4, height: y - tileGap - top + 8 });
+    y += 10;
+  }
+  return { tiles, bands, width, height: y - 10 + margin };
+}
+
+let mounted = 0;
+function mount(root, name, recorded) {
+  // Radio groups and the arrow marker need names unique on the page.
+  const id = `layers-${++mounted}`;
+  const data = recorded.layers;
+  const sourceDir = recorded.files[0].path.slice(0, recorded.files[0].path.lastIndexOf('/'));
+  const prefix = (() => {
+    const first = data.packages[0].name, cut = first.lastIndexOf('/') + 1;
+    return data.packages.every(p => p.name.startsWith(first.slice(0, cut))) ? first.slice(0, cut) : '';
+  })();
+  const short = name => name.slice(prefix.length);
+  const byName = new Map(data.packages.map(p => [p.name, p]));
+  const packageUses = usesElsewhere(data);
+
+  // Tables a caller hands in are the caller's data passing through, so
+  // the counts name only the package's own tables.
+  const own = (p, tables) => tables.filter(t => !p.handedIn.includes(t));
+  const handed = p => {
+    const reads = p.reads.filter(t => p.handedIn.includes(t)), writes = p.writes.filter(t => p.handedIn.includes(t));
+    return p.handedIn.length ? ` Through tables its callers hand in, it ${[reads.length ? `reads ${reads.join(', ')}` : '', writes.length ? `writes ${writes.join(', ')}` : ''].filter(Boolean).join(' and ')}.` : '';
+  };
+  // One line of IO for a package, or for the packages of a folded group.
+  const summary = ps => {
+    const io = ps.filter(p => p.effects.length > 0);
+    if (io.length === 0) return 'no direct IO';
+    const tables = pick => new Set(io.flatMap(p => own(p, pick(p)))).size;
+    const reads = tables(p => p.reads), writes = tables(p => p.writes), handedIn = new Set(io.flatMap(p => p.handedIn)).size;
+    const parts = [reads ? `reads ${reads}` : '', writes ? `writes ${writes}` : '', handedIn ? `${handedIn} handed in` : ''].filter(Boolean);
+    return parts.length ? `direct IO · ${parts.join(', ')}` : 'direct IO, no tables';
+  };
+
+  // Which groups are folded into one box; a big program starts folded.
+  const foldAll = data.packages.length > foldAbove;
+  // A page may pin how the diagram opens: data-drawing and data-dimension.
+  const opening = (value, allowed, fallback) => {
+    if (value === undefined) return fallback;
+    if (!allowed.includes(value)) throw new Error(`unknown layer diagram setting ${value}`);
+    return value;
+  };
+  let dimension = opening(root.dataset.dimension, Object.keys(dimensions), 'connections');
+  let drawing = opening(root.dataset.drawing, ['stack', 'arrows'], 'stack'), groups, folded, fold, scene, drawn, fitted;
+  const refold = () => { fold = foldGroups(data, groups, i => folded.has(i)); };
+  const regroup = () => {
+    groups = groupPackages(data, dimension);
+    folded = new Set(foldAll ? groups.keys() : []);
+    refold();
+  };
+  regroup();
+  // Start on the entry point at the top, or the folded box holding it.
+  const entry = [...data.packages].sort((a, b) => b.level - a.level || a.name.localeCompare(b.name))[0].name;
+  const chosen = opening(root.dataset.selected, ['none', ...data.packages.map(p => short(p.name))], undefined);
+  let selected = chosen === undefined ? entry : chosen === 'none' ? null : prefix + chosen;
+  const mostUsed = members => [...members].sort((a, b) => packageUses.get(b) - packageUses.get(a) || a.localeCompare(b));
+
+  // A group's label is the facts most of its members share, cut to fit.
+  const factName = { connections: short, types: f => f.slice(f.indexOf('::') + 2), tables: f => f };
+  // Members are listed beside the group, so a connections label names
+  // only the packages outside it that most members link to.
+  const lead = { connections: 'linked to', types: 'types', tables: 'tables' };
+  // all the facts a group's members share (its title and its selection's text)
+  const groupLabel = g => {
+    const names = g.shared.filter(f => !g.members.includes(f)).map(factName[dimension]);
+    return names.length ? `${lead[dimension]} ${names.join(', ')}` : 'linked to each other';
+  };
+
+  // What the picture draws: each folded group as one box named by the
+  // members the rest of the program uses most, and every other package.
+  const build = () => {
+    if (drawing === 'stack') return {
+      nodes: data.packages.map(p => ({ name: p.name, level: p.level, title: short(p.name), does: summary([p]), packages: [p] })),
+      edges: data.packageEdges, uses: packageUses };
+    const nodes = fold.nodes.map(n => {
+      const ps = n.members.map(m => byName.get(m));
+      if (!n.group) return { name: n.name, level: n.level, title: short(n.name), does: summary(ps), packages: ps };
+      const ranked = mostUsed(n.members);
+      return { name: n.name, level: n.level, title: `${short(ranked[0])} +${ranked.length - 1}`,
+        does: `${ps.length} packages · ${summary(ps)}`, packages: ps, group: n.group, index: groups.indexOf(n.group) };
+    });
+    return { nodes, edges: fold.edges, columns: groups.map((g, i) => folded.has(i) && g.members.length > 1 ? [`group:${i}`] : g.members),
+      uses: usesElsewhere(data, fold.nodeOf) };
+  };
+  const node = name => scene.nodes.find(n => n.name === name);
+
+  // The stack folds every group and draws its packages inside it; the
+  // rows are the folded levels, so a group sits on what it is built from.
+  const stackPicture = width => {
+    const tile = p => ({ name: p.name, level: p.level, min: boxWidth(short(p.name), summary([p]), p.effects.length > 0), weight: 1 + Math.sqrt(packageUses.get(p.name)), p });
+    const all = foldGroups(data, groups);
+    const levels = [...new Set(all.nodes.map(n => n.level))].sort((a, b) => b - a);
+    const layers = levels.map((level, layer) => all.nodes.filter(n => n.level === level).map(n => {
+      if (!n.group) return { ...tile(byName.get(n.name)), layer };
+      // Inside a group, packages higher in the program come first.
+      const members = mostUsed(n.members).sort((a, b) => byName.get(b).level - byName.get(a).level).map(m => tile(byName.get(m)));
+      return { name: n.name, group: n.group, members, layer, weight: members.reduce((w, m) => w + m.weight, 0),
+        min: Math.max(...members.map(m => m.min + 2 * pad)) };
+    }).sort((a, b) => b.weight - a.weight || a.name.localeCompare(b.name)));
+    const laid = stackLayout(layers, width);
+    if (!laid) return null;
+    const box = layer => ({ item, x, y, w, h }) => svg('g', { class: 'layer-box', 'data-package': item.name, 'data-layer': layer, 'data-io': String(item.p.effects.length > 0),
+      'data-uses': packageUses.get(item.name), tabindex: 0, role: 'button', 'aria-label': `${short(item.name)}, ${summary([item.p])}, ${counted(packageUses.get(item.name), 'use')} from other packages`, 'data-fit': `box:${item.name}` },
+      svg('rect', { x, y, width: w, height: h, 'data-box': `box:${item.name}` }),
+      svg('text', { class: 'layer-name', x: x + 10, y: y + h / 2 - 3 }, short(item.name)),
+      svg('text', { class: 'layer-does', x: x + 10, y: y + h / 2 + 14 }, summary([item.p])));
+    return svg('svg', { class: 'layer-svg layer-stack', viewBox: `0 0 ${laid.width} ${laid.height}`, width: laid.width, height: laid.height, role: 'group',
+      'aria-label': `Packages of ${recorded.request.args.title} as a stack: each layer is built from the layers below it${dimension === 'none' ? '' : `, grouped by ${dimensions[dimension]}`}` },
+      laid.bands.map((b, i) => svg('rect', { class: 'layer-band', 'data-shade': i % 2, x: 0, y: b.top, width: laid.width, height: b.height })),
+      laid.tiles.map(t => t.item.members
+        ? svg('g', { class: 'layer-group', 'data-members': t.item.group.members.join(' ') },
+          // the shared facts are not drawn as a heading (cut to fit, they read
+          // as noise); they are the outline's title and the selection's text
+          svg('title', {}, `Most of them: ${groupLabel(t.item.group)}`),
+          svg('rect', { x: t.x, y: t.y, width: t.w, height: t.h, rx: 6, 'data-box': `group:${t.item.name}` }),
+          t.subs.map(box(t.item.layer)))
+        : box(t.item.layer)(t)));
+  };
+  const picture = () => {
+    scene = build();
+    if (drawing === 'stack') {
+      // A phone gets a stack a little wider than its frame, scaled down.
+      const stack = stackPicture(Math.max(440, frame.clientWidth - 2));
+      if (stack) return stack;
+      // Too narrow for every tile: fall back to boxes and arrows.
+      drawing = 'arrows';
+      selected = selected && fold.nodeOf.get(packageOf(selected));
+      scene = build();
+    }
+    const most = Math.max(1, ...scene.uses.values());
+    const size = new Map(scene.nodes.map(n => {
+      const t = Math.sqrt(scene.uses.get(n.name) / most);
+      return [n.name, { w: Math.max(minW + growW * t, boxWidth(n.title, n.does, n.packages.some(p => p.effects.length > 0))), h: minH + growH * t }];
+    }));
+    const { at, bands, outlines, width, height, route } = layout(scene.nodes, scene.edges, scene.columns, size);
+    const edges = scene.edges.map(e => {
+      const points = route(e.from, e.to);
+      const d = points.slice(1).reduce((path, [x2, y2], i) => {
+        const [x1, y1] = points[i], bend = Math.max(24, (y2 - y1) / 2);
+        return `${path} C${x1},${y1 + bend} ${x2},${y2 - bend} ${x2},${y2}`;
+      }, `M${points[0][0]},${points[0][1]}`);
+      return svg('path', { class: 'layer-edge', 'data-from': e.from, 'data-to': e.to, d, 'marker-end': `url(#${id}-arrow)` },
+        svg('title', {}, `${node(e.from).title} uses ${usage(e)} of ${node(e.to).title}`));
+    });
+    const boxes = scene.nodes.map(n => {
+      const { x, y, w, h } = at.get(n.name);
+      return svg('g', { class: 'layer-box', 'data-package': n.name, 'data-folded': String(Boolean(n.group)), 'data-io': String(n.packages.some(p => p.effects.length > 0)),
+        'data-uses': scene.uses.get(n.name), tabindex: 0, role: 'button', 'aria-label': `${n.title}, ${n.does}, ${counted(scene.uses.get(n.name), 'use')} from the rest of the program`, 'data-fit': `box:${n.name}` },
+        svg('rect', { x, y, width: w, height: h, 'data-box': `box:${n.name}` }),
+        svg('text', { class: 'layer-name', x: x + 10, y: y + h / 2 - 3 }, n.title),
+        svg('text', { class: 'layer-does', x: x + 10, y: y + h / 2 + 14 }, n.does));
+    });
+    const hulls = outlines.map(o => svg('g', { class: 'layer-group', 'data-members': groups[o.i].members.join(' ') },
+      svg('title', {}, `Most of them: ${groupLabel(groups[o.i])}`),
+      svg('rect', { x: o.x - 4, y: o.y, width: o.width + 8, height: o.height, rx: 6, 'data-box': `group:${o.i}` })));
+    return svg('svg', { class: 'layer-svg', viewBox: `0 0 ${width} ${height}`, width, height, role: 'group',
+      'aria-label': `Packages of ${recorded.request.args.title} in bands by level, ${dimension === 'none' ? 'ungrouped' : `grouped by ${dimensions[dimension]}`}; each arrow points to what a box is built from` },
+      svg('defs', {}, svg('marker', { id: `${id}-arrow`, markerWidth: 8, markerHeight: 8, refX: 6, refY: 4, orient: 'auto', markerUnits: 'userSpaceOnUse' },
+        svg('path', { d: 'M0,0 L7,4 L0,8 z' }))),
+      bands.map((b, i) => svg('rect', { class: 'layer-band', 'data-shade': i % 2, x: 0, y: b.top, width, height: b.height })),
+      hulls,
+      svg('g', { class: 'layer-edges' }, edges),
+      boxes);
+  };
+
+  const frame = el('div', { class: 'layer-scroll' });
+  const detail = el('div', { class: 'layer-detail', 'aria-live': 'polite' });
+  const draw = () => {
+    fitted = frame.clientWidth;
+    drawn = picture();
+    frame.replaceChildren(drawn);
+    for (const input of controls.querySelectorAll('input[name$="-fold"]')) input.disabled = drawing === 'stack';
+    for (const input of controls.querySelectorAll('input[name$="-drawing"]')) input.checked = input.value === drawing;
+    render();
+  };
+  // A stack fits its frame, so it is laid out again when the frame resizes.
+  if ('ResizeObserver' in window) new ResizeObserver(() => { if (drawing === 'stack' && frame.clientWidth !== fitted) draw(); }).observe(frame);
+  const choice = (legend, key, options, current, pick) => el('fieldset', { class: 'layer-choice' }, el('legend', {}, legend),
+    options.map(([value, words]) => el('label', {},
+      el('input', { type: 'radio', name: `${id}-${key}`, value, checked: value === current, onchange: () => { pick(value); draw(); } }), ` ${words}`)));
+  // The selection follows its package: into the box its group folds
+  // into, and out to the most used member when a group opens.
+  const packageOf = name => byName.has(name) ? name : mostUsed(fold.nodes.find(n => n.name === name).members)[0];
+  const refoldKeeping = change => {
+    const was = selected && packageOf(selected);
+    change();
+    refold();
+    selected = was && (drawing === 'stack' ? was : fold.nodeOf.get(was));
+  };
+  const controls = el('div', { class: 'layer-controls' },
+    choice('Draw as', 'drawing', [['stack', 'a stack of layers'], ['arrows', 'boxes and arrows']], drawing, value => {
+      const was = selected && packageOf(selected);
+      drawing = value;
+      selected = was && (drawing === 'stack' ? was : fold.nodeOf.get(was));
+    }),
+    choice('Group packages by', 'grouping', Object.entries(dimensions), dimension, value => refoldKeeping(() => {
+      dimension = value;
+      groups = groupPackages(data, dimension);
+      folded = new Set(foldAll ? groups.keys() : []);
+    })),
+    choice('Show', 'fold', [['folded', 'each group as one box'], ['open', 'every package']], foldAll ? 'folded' : 'open', value => refoldKeeping(() => {
+      folded = new Set(value === 'folded' ? groups.keys() : []);
+    })));
+  const toggleGroup = i => refoldKeeping(() => { if (folded.has(i)) folded.delete(i); else folded.add(i); });
+  root.replaceChildren(
+    controls,
+    toolOutput(`layers lens · ${recorded.request.args.title} · ${data.packages.length} packages`, frame, detail,
+      el('p', { class: 'lens-source' }, ...(servedSources.has(name)
+        ? ['Recorded from the type-checked program. ',
+          el('a', { href: `${viewerUrl}${writeSourceLink(recorded.files.map(f => f.path), 0)}` }, 'Read the source')]
+        : ['Recorded from the type-checked program in ', el('code', {}, sourceDir), '.']), ' · ',
+        el('a', { href: new URL(`${name}-layers.json`, evidenceRoot) }, 'Raw lens output'),
+        data.declarations.length ? ` · Not drawn, declarations only: ${data.declarations.map(short).join(', ')}.` : '')),
+    el('p', { class: 'layer-key' }, 'How to read it: in the stack, each shaded layer is built only from the layers below it, though not always the one just below, and inside a group each package sits above the ones it is built from; select a package to see exactly what it uses. With boxes and arrows, each band is one level and arrows point to what a box is built from. A bigger box or a wider tile is used more by the rest of the program: references to its definitions plus types imported from it. Packages alike on the dimension you pick form a group, outlined with what most of them share, or folded into one box named by the members used most. ',
+      el('span', { class: 'layer-key-io' }, 'Direct IO'),
+      " marks effect sites in that package's own definitions, and the numbers count their tables; tables its callers pass in are counted as handed in, since that data is theirs. A package without direct sites may still call another package's IO. Click a box to select it (",
+      el('span', { class: 'layer-key-selected' }, 'filled'), ') and outline what it ', el('span', { class: 'layer-key-uses' }, 'uses'),
+      ' and what it is ', el('span', { class: 'layer-key-used' }, 'used by'), '.'));
+
+  const joined = parts => parts.flatMap((part, i) => [i ? ', ' : '', part]);
+  const list = (es, pick, kind) => es.length
+    ? joined(es.map(e => [el('span', { class: `layer-${kind}` }, node(pick(e)).title), ` (${usage(e)})`]))
+    : 'nothing in this program';
+  function describe(n) {
+    const outs = scene.edges.filter(e => e.from === n.name), ins = scene.edges.filter(e => e.to === n.name);
+    const links = ['Uses ', list(outs, e => e.to, 'uses'), '.', el('br'), 'Used by ', list(ins, e => e.from, 'used'), '.', el('br'),
+      `${counted(scene.uses.get(n.name), 'use')} from the rest of the program.`];
+    if (n.group) return [el('strong', {}, n.title), `, ${n.packages.length} packages grouped by ${dimensions[dimension]}: `,
+      joined(n.packages.map(p => el('code', {}, short(p.name)))), '. ', `Most of them: ${groupLabel(n.group)}.`, el('br'), ...links, el('br'),
+      el('button', { type: 'button', class: 'layer-fold', onclick: () => { toggleGroup(n.index); draw(); } }, 'Open this group')];
+    const p = n.packages[0], group = groups.find(g => g.members.includes(p.name)), others = group.members.filter(m => m !== p.name).map(short);
+    const iface = p.definitions.filter(d => d.usedOutside).map(d => el('code', {}, d.name));
+    const does = p.effects.length === 0 ? 'No direct effect sites; it may call another package\'s IO.'
+      : `Direct effect sites: ${p.effects.join(', ')}.` + (own(p, p.reads).length ? ` Reads ${own(p, p.reads).join(', ')}.` : '') + (own(p, p.writes).length ? ` Writes ${own(p, p.writes).join(', ')}.` : '')
+        + handed(p);
+    return [el('strong', {}, short(p.name)), `, ${p.definitions.length} definitions. ${does}`, el('br'), ...links, el('br'),
+      iface.length ? ['Definitions other packages use: ', joined(iface), '.'] : 'No other package uses its definitions: it is an entry point.',
+      others.length ? [el('br'), 'Grouped with ', joined(others), ` by ${dimensions[dimension]}. `, drawing === 'stack' ? [] :
+        el('button', { type: 'button', class: 'layer-fold', onclick: () => { toggleGroup(groups.indexOf(group)); draw(); } }, 'Fold this group')] : []];
+  }
+  function render() {
+    drawn.toggleAttribute('data-has-selection', Boolean(selected));
+    for (const g of drawn.querySelectorAll('.layer-box')) {
+      const name = g.dataset.package;
+      g.dataset.relation = name === selected ? 'selected'
+        : scene.edges.some(e => e.from === selected && e.to === name) ? 'uses'
+        : scene.edges.some(e => e.to === selected && e.from === name) ? 'used' : '';
+      g.setAttribute('aria-pressed', String(name === selected));
+    }
+    for (const path of drawn.querySelectorAll('.layer-edge'))
+      path.dataset.relation = path.dataset.from === selected ? 'uses' : path.dataset.to === selected ? 'used' : '';
+    detail.replaceChildren(...(selected ? describe(node(selected))
+      : ['Select a box to see what it uses, what uses it, and what it does itself.']).flat(Infinity));
+  }
+  const chooseBox = g => { selected = selected === g.dataset.package ? null : g.dataset.package; render(); };
+  frame.addEventListener('click', event => { const g = event.target.closest('.layer-box'); if (g) chooseBox(g); });
+  frame.addEventListener('keydown', event => {
+    const g = event.target.closest('.layer-box');
+    if (g && (event.key === 'Enter' || event.key === ' ')) {
+      event.preventDefault();
+      chooseBox(g);
+      frame.querySelector(`.layer-box[data-package="${CSS.escape(g.dataset.package)}"]`)?.focus();
+    }
+  });
+  draw();
+}
+
+// One load per diagram; a retry after a failure starts a new generation
+// so a slow earlier response cannot overwrite a later one.
+for (const root of document.querySelectorAll('[data-layer-diagram]')) {
+  let generation = 0;
+  const load = async () => {
+    const current = ++generation;
+    try {
+      const response = await fetch(new URL(`${root.dataset.layerDiagram}-layers.json`, evidenceRoot));
+      if (current !== generation) return;
+      if (!response.ok) throw new Error(`Layer data request failed (${response.status})`);
+      const data = await response.json();
+      if (current !== generation) return;
+      mount(root, root.dataset.layerDiagram, data);
+    } catch (error) {
+      if (current !== generation) return;
+      const message = document.createElement('p');
+      message.setAttribute('role', 'alert');
+      message.textContent = `The layer diagram could not be loaded: ${error.message}.`;
+      const retry = document.createElement('button');
+      retry.type = 'button';
+      retry.textContent = 'Retry';
+      retry.addEventListener('click', load);
+      root.replaceChildren(message, retry);
+    }
+  };
+  load();
+}

package/dist/studio-page/layer-groups.js

@@ -0,0 +1,129 @@
+// Groups and weights for the layer diagram, computed from the layers
+// lens output alone. Packages are alike on one chosen dimension: the
+// packages they connect to, the types they share, or the tables they
+// touch. Names are only labels here; a group comes from shared facts.
+
+export const dimensions = Object.freeze({
+  connections: 'packages they connect to',
+  types: 'types they share',
+  tables: 'tables they touch',
+  none: 'no grouping',
+});
+
+// Two groups merge while their members are, on average, at least this
+// alike (Jaccard similarity of the chosen facts).
+const together = 0.3;
+
+// What a package has on one dimension, as a set of fact keys. A type is
+// shared by the package that defines it and every package importing it.
+function facts(data, dimension) {
+  const sets = new Map(data.packages.map(p => [p.name, new Set()]));
+  for (const p of data.packages) {
+    const f = sets.get(p.name);
+    if (dimension === 'tables') [...p.reads, ...p.writes].forEach(t => f.add(t));
+    if (dimension === 'connections') f.add(p.name);
+  }
+  for (const e of data.packageEdges) {
+    if (dimension === 'connections') { sets.get(e.from).add(e.to); sets.get(e.to).add(e.from); }
+    if (dimension === 'types') for (const t of e.typeNames) {
+      sets.get(e.from).add(`${e.to}::${t}`);
+      sets.get(e.to).add(`${e.to}::${t}`);
+    }
+  }
+  return sets;
+}
+
+const alike = (a, b) => {
+  if (a.size === 0 || b.size === 0) return 0;
+  let shared = 0;
+  for (const x of a) if (b.has(x)) shared++;
+  return shared / (a.size + b.size - shared);
+};
+
+// Whether folding each group into one node leaves a graph with no cycle.
+function foldsToLayers(data, groups) {
+  const nodeOf = new Map(groups.flatMap((g, i) => g.map(m => [m, i])));
+  const out = groups.map(() => new Set());
+  for (const e of data.packageEdges) if (nodeOf.get(e.from) !== nodeOf.get(e.to)) out[nodeOf.get(e.from)].add(nodeOf.get(e.to));
+  const state = groups.map(() => 0);
+  const acyclic = i => {
+    if (state[i]) return state[i] === 2;
+    state[i] = 1;
+    const ok = [...out[i]].every(acyclic);
+    state[i] = 2;
+    return ok;
+  };
+  return groups.every((_, i) => acyclic(i));
+}
+
+// Average-linkage clustering. Two groups merge only if folding every group
+// into one box still leaves arrows that all point down. Members keep the order they
+// were merged in, so the most alike packages sit next to each other.
+export function groupPackages(data, dimension) {
+  const sets = facts(data, dimension);
+  let groups = data.packages.map(p => [p.name]);
+  // A group of more than half the program would say nothing about it.
+  const half = Math.max(2, Math.floor(data.packages.length / 2));
+  if (dimension === 'none') return groups.map(members => ({ members, shared: [] }));
+  const score = (x, y) => x.reduce((s, a) => s + y.reduce((t, b) => t + alike(sets.get(a), sets.get(b)), 0), 0) / (x.length * y.length);
+  for (;;) {
+    const pairs = [];
+    for (let i = 0; i < groups.length; i++)
+      for (let j = i + 1; j < groups.length; j++) {
+        const s = score(groups[i], groups[j]);
+        if (s >= together) pairs.push({ s, i, j });
+      }
+    const best = pairs.sort((a, b) => b.s - a.s).find(({ i, j }) => groups[i].length + groups[j].length <= half && foldsToLayers(data, groups.map((g, k) => k === i ? [...g, ...groups[j]] : g).filter((_, k) => k !== j)));
+    if (!best) break;
+    groups[best.i] = [...groups[best.i], ...groups[best.j]];
+    groups = groups.filter((_, k) => k !== best.j);
+  }
+  return groups.map(members => ({ members, shared: members.length > 1 ? sharedFacts(members, sets) : [] }));
+}
+
+// The facts at least half the members have, most common first.
+function sharedFacts(members, sets) {
+  const count = new Map();
+  for (const m of members) for (const x of sets.get(m)) count.set(x, (count.get(x) ?? 0) + 1);
+  return [...count].filter(([, n]) => n * 2 >= members.length)
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([x]) => x);
+}
+
+// How much the rest of the program leans on each node (a package, or a
+// folded group): references from definitions outside it to definitions in
+// it, plus each type imported into it from outside.
+export function usesElsewhere(data, nodeOf = new Map(data.packages.map(p => [p.name, p.name]))) {
+  const pkg = id => id.slice(0, id.indexOf('::'));
+  const uses = new Map([...new Set(nodeOf.values())].map(n => [n, 0]));
+  const add = (from, to, n) => { if (nodeOf.get(from) !== nodeOf.get(to)) uses.set(nodeOf.get(to), uses.get(nodeOf.get(to)) + n); };
+  for (const e of data.crossEdges) add(pkg(e.from), pkg(e.to), 1);
+  for (const e of data.packageEdges) add(e.from, e.to, e.typeNames.length);
+  return uses;
+}
+
+// Each folded group of two or more as one node; every other package stays
+// itself. A fold of groups that folds to layers (see groupPackages) has no
+// cycle whichever groups are folded, so a node's level is one more than
+// the highest level it is built from.
+export function foldGroups(data, groups, folded = () => true) {
+  const nodes = groups.flatMap((g, i) => g.members.length > 1 && folded(i)
+    ? [{ name: `group:${i}`, group: g, members: g.members }]
+    : g.members.map(m => ({ name: m, members: [m] })));
+  const nodeOf = new Map(nodes.flatMap(n => n.members.map(m => [m, n.name])));
+  const edges = new Map();
+  for (const e of data.packageEdges) {
+    const from = nodeOf.get(e.from), to = nodeOf.get(e.to);
+    if (from === to) continue;
+    const key = `${from}\n${to}`;
+    const sum = edges.get(key) ?? { from, to, refs: 0, types: 0 };
+    edges.set(key, { ...sum, refs: sum.refs + e.refs, types: sum.types + e.typeNames.length });
+  }
+  const below = new Map(nodes.map(n => [n.name, []]));
+  for (const e of edges.values()) below.get(e.from).push(e.to);
+  const level = new Map();
+  const visit = n => {
+    if (!level.has(n)) level.set(n, below.get(n).reduce((l, m) => Math.max(l, visit(m) + 1), 0));
+    return level.get(n);
+  };
+  return { nodes: nodes.map(n => ({ ...n, level: visit(n.name) })), edges: [...edges.values()], nodeOf };
+}

package/dist/studio-page/source-link.js

@@ -0,0 +1,17 @@
+// The source viewer's link format, `#src=<comma-separated site paths>&tab=<index>`,
+// read and written in one place for every page that opens it. A path is kept
+// only when it resolves to this site, so a shared link never shows another
+// origin's file as one of ours.
+export function readSourceLink(hash, base) {
+  const params = new URLSearchParams(hash.replace(/^#/, ''));
+  const origin = new URL(base).origin;
+  const files = (params.get('src') ?? '').split(',').map((path) => path.trim())
+    .filter((path) => path !== '' && URL.canParse(path, base) && new URL(path, base).origin === origin);
+  const tab = Number(params.get('tab') ?? 0);
+  return { files, tab: Number.isSafeInteger(tab) && tab >= 0 && tab < files.length ? tab : 0 };
+}
+
+// Paths keep their slashes, so a shared link reads `#src=demos/x.bosatsu`.
+export function writeSourceLink(files, tab) {
+  return '#src=' + files.join(',') + '&tab=' + tab;
+}