tablewalk 0.0.1

package/dist/client/composer.js

@@ -0,0 +1,1972 @@
+/**
+ * The view composer: build a multi-table result by picking related tables and
+ * their fields, rather than by writing a join.
+ *
+ * The whole thing is a visual editor for **reference paths** — the dot-walked
+ * chains defined in shared/view.ts. `customer_id.name` means "follow
+ * invoice.customer_id to customer, then take name", and because the foreign
+ * key graph is already in the browser every hop can be proposed rather than
+ * typed. Adding a related table adds paths; ticking a field adds a path;
+ * filtering across a walk is a condition on a path. One idea, three panels.
+ *
+ * It is deliberately not a query builder with a JOIN dropdown. Nobody thinks
+ * "left join customer on customer.id = invoice.customer_id"; they think "and
+ * show me the customer's country". So the suggestions are phrased from the
+ * key — *each invoice has one customer* — and the join is a consequence you
+ * can go and read in the SQL panel if you want to.
+ *
+ * ## Self-attaching
+ *
+ * This module adds its own entry point to the top bar and its own stylesheet,
+ * and hooks navigation through the existing hash scheme rather than through
+ * app.js. Nothing else in the client imports it, which is what lets the whole
+ * feature live in two files.
+ *
+ * ## Where a view lives in the URL
+ *
+ * A composer session is a *tab on a table*, exactly like Rows, Definition and
+ * Diagram — so `/demo/invoice!view:sales-by-country` needs no second URL
+ * format and no change to deeplink.js. The serialisation already carries the
+ * tab; the id after the colon names the saved view, and a bare `!view` is a
+ * fresh composer on that table.
+ *
+ * ## Where a view is stored
+ *
+ * Saved views are per connection in localStorage, like saved filters: they are
+ * one person's working set, and `orders` on staging is not `orders` on
+ * production. Views defined in `tablewalk.json` come from the server, are
+ * marked as such, and cannot be edited from here — a page silently rewriting a
+ * file someone checked into a repo is a surprise nobody asked for.
+ */
+import {
+  $, api, currentEntry, el, findTable, go, labelColumn, loadJson, looksLikeDateColumn,
+  primaryKey, quote, refsFrom, refsTo, saveJson, state, tableView, toast,
+  /* Aliased rather than renamed at every call site: `hopsOut(customer)` reads
+     as a question about one table, where `hopsFrom` reads as half of a call
+     that has lost its schema argument. */
+  hopName as hopLabel, hopsFrom as hopsOut, tableAtPrefix as tableAt,
+} from './core.js';
+import { toHash } from './url.js';
+import { dropdown } from './dropdown.js';
+import { addMenuItem } from './menu.js';
+import { promptFor } from './prompt.js';
+
+/* Mirrors MAX_PATH_DEPTH in shared/view.ts. The cap is not decoration:
+   work_order.parent_id points at work_order, so the path space is infinite
+   and any breadth-first walk of it runs forever. */
+export const MAX_DEPTH = 4;
+
+const STORE = 'tablewalk.composer.v1';
+
+/* ---------- module state ---------- */
+
+/** The overlay, or null when the composer is closed. */
+let root = null;
+/**
+ * What the overlay is currently showing, as `base|viewId`.
+ *
+ * The base table is part of the identity and not an afterthought: two fresh
+ * composers both have an empty view id, so keying on the id alone means
+ * moving from `/db/invoice!view` to `/db/work_order!view` looks like no
+ * change at all and the panel keeps showing the old table.
+ */
+let openFor = null;
+/** The view being edited. */
+let draft = null;
+/** Path prefixes whose table has been added — the joins, in tree form. */
+let opened = new Set();
+/** The prefix added by the last click, so the checklist can point at it. */
+let justAdded = null;
+/** Config-defined views for this connection, fetched once per open. */
+let fromConfig = [];
+/** The last preview response, kept so the SQL toggle needs no round trip. */
+let preview = null;
+let previewError = null;
+let showSql = false;
+/** The text panel, and what has been typed into it but not yet applied. */
+let showText = false;
+let textEdit = null;
+let running = false;
+let runToken = 0;
+
+/* ---------- paths ----------
+
+   The mirror of shared/view.ts these are built on lives in core.js, where the
+   layout builder can reach it too — it used to walk the same prefixes with a
+   copy of its own, and disagreed with this one about whether a constraint
+   name is a legal path segment. */
+
+/** A path's final column, or null if any segment does not resolve.
+
+   Deliberately stricter than resolvePath in shared/view.ts, which also
+   accepts a case-insensitive column name and refuses a path deeper than
+   MAX_PATH_DEPTH. Both differences can only ever withhold a suggestion the
+   server would have accepted; neither can propose one it would refuse. */
+export function columnAt(baseId, path) {
+  const cut = path.lastIndexOf('.');
+  const table = tableAt(baseId, cut === -1 ? '' : path.slice(0, cut));
+  if (!table) return null;
+  const name = path.slice(cut + 1);
+  return table.columns.find((c) => c.name === name) ?? null;
+}
+
+const depthOf = (path) => (path ? path.split('.').length : 0);
+
+/* ---------- plain language ----------
+
+   The phrasing is generated from the key, not written per table, and says the
+   two things a foreign key actually tells you: the direction, and whether the
+   other row has to exist. "may have one" versus "has one" is the difference
+   between a column that will show nulls and one that will not. */
+
+function phraseOne(fromTable, hop) {
+  const target = findTable(hop.target);
+  const subject = fromTable.name;
+  const object = target ? target.name : hop.target;
+  const verb = hop.optional ? 'may have one' : 'has one';
+  const self = target && target.id === fromTable.id;
+  return self
+    ? `each ${subject} ${verb} parent ${object}`
+    : `each ${subject} ${verb} ${object}`;
+}
+
+function phraseMany(toTable, fk) {
+  const child = findTable(fk.from.table);
+  return `each ${toTable.name} has many ${plural(child ? child.name : fk.from.table)}`;
+}
+
+/* "each country has many customer" is the kind of almost-English that makes a
+   generated sentence read as generated. Three rules cover every table name
+   anyone actually writes, and a name they do not cover is still a real word
+   with an s on the end. */
+function plural(name) {
+  if (/(?:s|x|z|ch|sh)$/i.test(name)) return `${name}es`;
+  if (/[^aeiou]y$/i.test(name)) return `${name.slice(0, -1)}ies`;
+  return `${name}s`;
+}
+
+/* ---------- storage ---------- */
+
+const connectionKey = () => state.activeConnection ?? 'default';
+
+/**
+ * Everything stored for one connection: the views, and which ids are pinned.
+ *
+ * Pins live beside the views rather than on them because a view defined in
+ * `tablewalk.json` can be pinned too, and that view is not ours to write to.
+ * A list of ids covers both without the config half needing a copy kept here
+ * that could drift from the file.
+ *
+ * An earlier shape stored the array directly. It is read rather than
+ * discarded: someone who saved three views before this existed should not
+ * find them gone.
+ */
+function bucket() {
+  const stored = loadJson(STORE, {})[connectionKey()];
+  if (Array.isArray(stored)) return { views: stored, pinned: [] };
+  return { views: stored?.views ?? [], pinned: stored?.pinned ?? [] };
+}
+
+function savedViews() {
+  return bucket().views;
+}
+
+const pinnedIds = () => bucket().pinned;
+const isPinned = (id) => pinnedIds().includes(id);
+
+function writeBucket(next) {
+  const all = loadJson(STORE, {});
+  all[connectionKey()] = next;
+  if (!saveJson(STORE, all)) {
+    toast('Could not save — this browser is not allowing local storage.', 'error');
+    return false;
+  }
+  return true;
+}
+
+function writeSaved(list) {
+  return writeBucket({ ...bucket(), views: list });
+}
+
+function togglePin(id) {
+  const current = bucket();
+  const pinned = current.pinned.includes(id)
+    ? current.pinned.filter((p) => p !== id)
+    : [...current.pinned, id];
+  if (writeBucket({ ...current, pinned })) redraw();
+}
+
+function newId() {
+  /* Time plus a little noise. Ids end up in URLs, so they stay in the
+     character set the hash scheme already treats as opaque. */
+  return `v${Date.now().toString(36)}${Math.floor(Math.random() * 1296).toString(36)}`;
+}
+
+/* ---------- the draft ---------- */
+
+function blankView(baseId) {
+  const table = findTable(baseId);
+  const label = table ? labelColumn(table) : null;
+  const key = table ? primaryKey(table) : [];
+  /* A brand new view opens with the row's key and its readable column ticked.
+     An empty grid is a worse starting point than a small correct one: it
+     gives you nothing to recognise your data by while you build. */
+  const columns = [...new Set([...key, label].filter(Boolean))].map((path) => ({ path }));
+  return { id: '', name: '', base: baseId, columns, aggregates: [], query: '', orderBy: [], limit: 20 };
+}
+
+const selected = () => draft.columns.map((c) => c.path);
+const isSelected = (path) => draft.columns.some((c) => c.path === path);
+
+function toggleField(path) {
+  draft.columns = isSelected(path)
+    ? draft.columns.filter((c) => c.path !== path)
+    : [...draft.columns, { path }];
+  changed();
+}
+
+function addJoin(prefix) {
+  opened.add(prefix);
+  /* A join with nothing showing through it is a join you cannot see: the SQL
+     does not even emit it, because no path uses it, so "Add" appears to do
+     nothing at all. One field comes along — the readable one where there is
+     one — so the click has a visible consequence in the grid as well as in
+     the checklist. */
+  const table = tableAt(draft.base, prefix);
+  const field = table ? defaultField(table, prefix) : null;
+  if (field) draft.columns.push({ path: `${prefix}.${field}` });
+  justAdded = prefix;
+  changed();
+}
+
+/** The one field worth showing by default from a newly joined table. */
+function defaultField(table, prefix) {
+  const free = (name) => name && !isSelected(`${prefix}.${name}`);
+  const label = labelColumn(table);
+  if (free(label)) return label;
+  const text = table.columns.find((c) => !c.primaryKey && /char|text|varchar|string/i.test(c.type));
+  if (free(text?.name)) return text.name;
+  const key = primaryKey(table)[0];
+  if (free(key)) return key;
+  return table.columns.map((c) => c.name).find(free) ?? null;
+}
+
+function removeJoin(prefix) {
+  // Everything reached *through* this table goes with it, or the view keeps
+  // paths whose join has just been taken away.
+  for (const open of [...opened]) {
+    if (open === prefix || open.startsWith(`${prefix}.`)) opened.delete(open);
+  }
+  draft.columns = draft.columns.filter((c) => !c.path.startsWith(`${prefix}.`));
+  draft.orderBy = (draft.orderBy ?? []).filter((o) => !o.path.startsWith(`${prefix}.`));
+  changed();
+}
+
+/** Rebase onto another table, discarding paths that no longer mean anything. */
+function setBase(baseId) {
+  draft = { ...blankView(baseId), id: draft.id, name: draft.name };
+  opened = new Set();
+  claim();
+  changed();
+}
+
+/** Record what is on screen and make the address bar agree with it. */
+function claim() {
+  const tab = tabForDraft();
+  openFor = `${draft.base}|${viewTabOf({ kind: 'table', tab })}`;
+  linkTo(tab);
+}
+
+/**
+ * One edit: redraw the panels, then re-run the preview.
+ *
+ * Kept as a pair rather than folded into `redraw`, because `redraw` also runs
+ * when nothing about the *view* changed — opening the overlay, toggling the
+ * SQL panel — and re-querying for those would put a round trip behind a
+ * button that only reveals text.
+ */
+function changed() {
+  redraw();
+  schedulePreview();
+}
+
+/* ---------- the view sent to the server ---------- */
+
+function payload() {
+  return {
+    id: draft.id,
+    name: draft.name,
+    base: draft.base,
+    columns: draft.columns,
+    aggregates: draft.aggregates ?? [],
+    /* Carried, and not only when the box is empty. A view defined in
+       `tablewalk.json` holds its filter as a structure, and leaving it out
+       here was a bug with the worst possible shape: the view ran, returned
+       rows, and returned the wrong ones — an "Australian work orders" view
+       quietly listing New Zealand. */
+    filter: draft.filter,
+    orderBy: draft.orderBy ?? [],
+    limit: draft.limit,
+  };
+}
+
+/* ---------- a filter, written back as text ----------
+
+   A structural filter that does not appear in the box is a filter you cannot
+   see, edit or argue with — the composer would be applying a condition the
+   screen denies exists. Rendering it back into the language closes that gap
+   and makes the box the single thing the view's filter *is*. */
+
+const OP_TEXT = {
+  '=': '=', '!=': '!=', '<': '<', '<=': '<=', '>': '>', '>=': '>=',
+  contains: 'contains', startsWith: 'startswith', endsWith: 'endswith', like: 'like',
+};
+
+function filterToText(filter) {
+  if (!filter?.groups?.length) return '';
+  return filter.groups
+    .map((group) => group.map(conditionToText).filter(Boolean).join(' and '))
+    .filter(Boolean)
+    .map((text, _, all) => (all.length > 1 ? `(${text})` : text))
+    .join(' or ');
+}
+
+function conditionToText(condition) {
+  const { path, op, value } = condition;
+  if (op === 'isNull') return `${path} is empty`;
+  if (op === 'isNotNull') return `${path} is not empty`;
+  if (op === 'in') {
+    const list = (Array.isArray(value) ? value : [value]).map(valueToText).join(', ');
+    return `${path} in (${list})`;
+  }
+  const word = OP_TEXT[op];
+  return word ? `${path} ${word} ${valueToText(value)}` : '';
+}
+
+function valueToText(value) {
+  /* Quoted whenever a bare word would not survive the round trip. The parser
+     treats an explicit quote as "this is text", which is exactly right for a
+     value that came out of a config file already typed.
+  
+     This kept its own copy with a slightly wider bare-word set (`$`), so the
+     same value written here and in the query bar could come out differently.
+     A `$` now gets quoted instead of passing bare, which the grammar reads
+     identically — one rule beats two nearly-identical ones. */
+  return quote(String(value ?? ''));
+}
+
+/* ---------- preview ----------
+
+   Debounced, and every response carries the token of the request that asked
+   for it. Without that, a slow query started three keystrokes ago lands after
+   a fast one and the grid shows an answer to a question nobody is asking any
+   more — the classic race, and invisible when it happens. */
+
+let previewTimer = null;
+
+function schedulePreview() {
+  clearTimeout(previewTimer);
+  previewTimer = setTimeout(() => void runPreview(), 220);
+}
+
+async function runPreview() {
+  if (!draft || (!draft.columns.length && !aggregates().length)) {
+    preview = null;
+    previewError = null;
+    paintPreview();
+    return;
+  }
+  const token = ++runToken;
+  running = true;
+  paintPreview();
+  try {
+    const data = await api('/api/view/run', {
+      view: payload(),
+      query: draft.query,
+      limit: draft.limit,
+    });
+    if (token !== runToken) return;
+    if (data.errors && data.errors.length) {
+      preview = null;
+      previewError = data.errors;
+    } else {
+      preview = data;
+      previewError = null;
+      /* The text form only exists once the view has run, so this is where an
+         unsaved composer becomes a link worth copying. Stamped rather than
+         navigated: `go()` would repaint the whole app underneath the overlay,
+         and a network round trip per keystroke is exactly what a live preview
+         must not cost. */
+      stampHash();
+      if (showText) textEdit = null;
+    }
+  } catch (err) {
+    if (token !== runToken) return;
+    preview = null;
+    previewError = [{ message: err.message }];
+  } finally {
+    if (token === runToken) {
+      running = false;
+      paintPreview();
+    }
+  }
+}
+
+/* ---------- open / close ---------- */
+
+/** The view id encoded in a stack entry's tab, or null if it is not a view. */
+function viewTabOf(entry) {
+  if (!entry || entry.kind !== 'table') return null;
+  const tab = entry.tab ?? 'rows';
+  if (tab === 'view') return '';
+  /* Two forms, and the leading character says which. `view:<id>` names
+     something saved; `view+<text>` carries the view itself, so a composer
+     session that was never saved is still a link you can send someone. */
+  if (tab.startsWith('view:')) return tab.slice(5);
+  if (tab.startsWith('view+')) return `+${tab.slice(5)}`;
+  return null;
+}
+
+/* The hash is one segment of a `/`-separated path, and deeplink.js finds the
+   tab by the last `!` in it. Neither may appear in the payload, and
+   encodeURIComponent leaves `!` alone. */
+const encodeText = (text) => encodeURIComponent(text).replace(/!/g, '%21');
+
+/** Above this the URL stops being pasteable, so the link degrades to the base. */
+const MAX_LINK_TEXT = 1200;
+
+function tabForDraft() {
+  if (draft.id) return `view:${draft.id}`;
+  const text = preview?.text;
+  if (text) {
+    const encoded = encodeText(text);
+    if (encoded.length <= MAX_LINK_TEXT) return `view+${encoded}`;
+  }
+  return 'view';
+}
+
+function closeComposer() {
+  if (!root) return;
+  root.remove();
+  root = null;
+  openFor = null;
+  draft = null;
+  preview = null;
+  previewError = null;
+  document.body.classList.remove('composing');
+}
+
+async function openComposer(baseId, viewId) {
+  const base = findTable(baseId) ? baseId : likeliestBase();
+  if (!base) return;
+
+  openFor = `${base}|${viewId}`;
+  showSql = false;
+  draft = blankView(base);
+  opened = new Set();
+
+  if (!root) {
+    root = el('div', { class: 'composer', role: 'dialog', 'aria-modal': 'false', 'aria-label': 'View composer' });
+    document.body.append(root);
+    document.body.classList.add('composing');
+  }
+  redraw();
+
+  /* Config views are fetched rather than cached across opens: they can change
+     when the connection does, and the request is one small GET. */
+  try {
+    const data = await api('/api/views');
+    fromConfig = data.views ?? [];
+  } catch {
+    // A server that cannot list config views is not a reason to refuse to
+    // compose one. The saved list still works.
+    fromConfig = [];
+  }
+
+  if (viewId && viewId.startsWith('+')) {
+    /* The link carries the view itself. Parsed by the server, because the
+       grammar lives there — the same call the text panel makes. */
+    try {
+      const data = await api('/api/view/run', { text: decodeURIComponent(viewId.slice(1)) });
+      if (data.errors?.length) {
+        previewError = data.errors;
+      } else {
+        loadView({ ...data.view, id: '', name: draft.name });
+        preview = data;
+      }
+    } catch (err) {
+      previewError = [{ message: err.message }];
+    }
+    redraw();
+    return;
+  }
+
+  if (viewId) {
+    const found = [...savedViews(), ...fromConfig].find((v) => v.id === viewId);
+    if (found) {
+      loadView(found);
+      /* A saved view carries its own base table, which need not be the one
+         named in the link that opened it. Correcting the address bar keeps a
+         copied URL truthful rather than merely functional. */
+      claim();
+    } else {
+      toast(`No saved view called "${viewId}" — starting a new one.`, 'error');
+    }
+  }
+  redraw();
+  schedulePreview();
+}
+
+function loadView(view) {
+  draft = {
+    id: view.id,
+    name: view.name ?? '',
+    base: view.base,
+    columns: (view.columns ?? []).map((c) => (typeof c === 'string' ? { path: c } : { ...c })),
+    aggregates: (view.aggregates ?? []).map((a) => ({ ...a })),
+    /* Shown in the box, so the condition a config view applies is visible and
+       editable rather than invisible and authoritative. The structure is kept
+       alongside as the authority until the box is touched, so a filter that
+       does not survive the round trip exactly still runs exactly. */
+    query: view.query ?? filterToText(view.filter),
+    filter: view.filter,
+    orderBy: view.orderBy ?? [],
+    limit: view.limit ?? 20,
+    source: view.source,
+  };
+  /* Every prefix a path walks through is a join that must be open, or the
+     tables panel would show a view whose own columns are not in it. */
+  opened = new Set();
+  for (const col of draft.columns) {
+    const parts = col.path.split('.');
+    for (let i = 1; i < parts.length; i++) opened.add(parts.slice(0, i).join('.'));
+  }
+}
+
+/* ---------- rendering ---------- */
+
+/**
+ * Sit below the app's own top bar rather than over it.
+ *
+ * Covering the whole window would be simpler and would also hide the
+ * connection label and the schema button — the two things that tell you
+ * *which* database you are composing against. Measuring is a line; guessing a
+ * height in the stylesheet is a line that goes wrong the first time the bar
+ * wraps on a narrow window.
+ */
+function positionRoot() {
+  if (!root) return;
+  const bar = document.querySelector('.topbar');
+  root.style.top = bar ? `${Math.round(bar.getBoundingClientRect().bottom)}px` : '0px';
+}
+
+function redraw() {
+  if (!root || !draft) return;
+  positionRoot();
+  const focused = document.activeElement;
+  const keepFilter = focused && focused.classList.contains('composer-query');
+  const keepText = focused && focused.classList.contains('composer-text');
+  const caret = keepFilter || keepText ? focused.selectionStart : null;
+
+  root.replaceChildren(topBar(), body());
+
+  if (keepFilter || keepText) {
+    const input = root.querySelector(keepFilter ? '.composer-query' : '.composer-text');
+    if (input) {
+      input.focus();
+      input.setSelectionRange(caret, caret);
+    }
+  }
+
+  /* Bring a freshly added table's fields into sight. Twenty new checkboxes
+     below the fold is indistinguishable from nothing having happened, which
+     is precisely how "Add" read before this. */
+  if (justAdded) {
+    const block = root.querySelector(`.composer-group[data-prefix="${cssEscape(justAdded)}"]`);
+    if (block) block.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+    justAdded = null;
+  }
+}
+
+function topBar() {
+  const name = el('input', {
+    class: 'composer-name',
+    type: 'text',
+    value: draft.name,
+    placeholder: 'Untitled view',
+    'aria-label': 'View name',
+    oninput: (e) => {
+      draft.name = e.target.value;
+    },
+  });
+
+  return el('header', { class: 'composer-bar' }, [
+    el('span', { class: 'composer-eyebrow', text: 'View' }),
+    name,
+    el('span', { class: 'composer-on', text: `from ${draft.base}` }),
+    el('div', { class: 'composer-bar-actions' }, [
+      /* Text first, then SQL: one is the view in the language you can edit,
+         the other is what it became. Reading left to right, that is also the
+         order the translation happens in. */
+      el('button', {
+        type: 'button',
+        class: 'ghost',
+        'aria-pressed': String(showText),
+        title: 'The view written down — editable, and the same language as the bar',
+        text: 'Text',
+        onclick: () => {
+          showText = !showText;
+          textEdit = null;
+          redraw();
+        },
+      }),
+      el('button', {
+        type: 'button',
+        class: 'ghost',
+        'aria-pressed': String(showSql),
+        title: 'The statement this compiles to',
+        text: 'SQL',
+        onclick: () => {
+          showSql = !showSql;
+          redraw();
+        },
+      }),
+      el('button', { type: 'button', class: 'ghost', text: 'Save as…', onclick: () => void saveAs() }),
+      el('button', { type: 'button', text: 'Save', onclick: () => void saveDraft() }),
+      el('button', {
+        type: 'button',
+        class: 'ghost composer-close',
+        'aria-label': 'Close the composer',
+        title: 'Close (Esc)',
+        text: '×',
+        onclick: () => leave(),
+      }),
+    ]),
+  ]);
+}
+
+function body() {
+  return el('div', { class: 'composer-body' }, [
+    /* Saved views above the relationship list, not below it. The list of
+       relationships is long and scrolls; anything under it is, in practice,
+       not on the page. The thing you might want *before* building — the view
+       you already built — cannot be the thing you have to scroll to find. */
+    el('aside', { class: 'composer-side' }, [startPanel(), savedPanel(), relatedPanel()]),
+    el('div', { class: 'composer-main' }, [
+      fieldsPanel(),
+      filterPanel(),
+      summaryLine(),
+      showText ? textPanel() : null,
+      showSql ? sqlPanel() : null,
+      el('div', { class: 'composer-preview', id: 'composer-preview' }, previewBody()),
+    ]),
+  ]);
+}
+
+/**
+ * What the result *is*, in one sentence, above the grid that shows it.
+ *
+ * This is the question the panels do not answer. They show ingredients —
+ * relationships, checkboxes, a WHERE box — and leave the shape of the answer
+ * to be inferred. The two facts worth stating are the ones people get wrong
+ * about joins: how many rows there are, and what happens when the other row
+ * is missing.
+ */
+function summaryLine() {
+  const base = findTable(draft.base);
+  const name = base ? base.name : draft.base;
+
+  const sources = [...opened].sort().map((prefix) => {
+    const table = tableAt(draft.base, prefix);
+    return { prefix, name: table ? table.name : prefix };
+  });
+  /* Two hops onto the same table are two different things — `raised_by` and
+     `assigned_to` are both "employee" — so the path is added when the bare
+     name would be ambiguous, and left off when it would just be noise. */
+  const counts = new Map();
+  for (const s of sources) counts.set(s.name, (counts.get(s.name) ?? 0) + 1);
+  const labels = sources.map((s) => (counts.get(s.name) > 1 ? `${s.name} (${s.prefix})` : s.name));
+
+  const rolled = (draft.aggregates ?? []).map((a) => aggregateLabel(a));
+
+  const parts = [`One row per ${name}`];
+  if (labels.length) parts.push(`, with columns from ${andList(labels)}`);
+  if (rolled.length) parts.push(`${labels.length ? ', and' : ', with'} ${andList(rolled)}`);
+  parts.push('.');
+
+  const sentence = parts.join('');
+  const promise = labels.length
+    ? ` Every ${name} appears exactly once, even where the related row is missing — those cells read null rather than dropping the row.`
+    : '';
+
+  return el('p', { class: 'composer-summary' }, [
+    el('strong', { text: sentence }),
+    promise ? document.createTextNode(promise) : null,
+  ]);
+}
+
+function andList(items) {
+  if (items.length <= 1) return items[0] ?? '';
+  return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}
+
+/* ---------- panel: start from ---------- */
+
+function startPanel() {
+  const items = state.schema.tables.map((t) => ({
+    value: t.id,
+    label: t.id,
+    detail: `${t.columns.length} columns${t.approxRows != null ? ` · ${t.approxRows.toLocaleString()} rows` : ''}`,
+    badge: t.isView ? 'view' : undefined,
+  }));
+  return el('section', { class: 'panel composer-panel' }, [
+    el('h3', { text: 'Start from' }),
+    el('div', { class: 'composer-pad' }, dropdown({
+      items,
+      value: draft.base,
+      ariaLabel: 'Base table',
+      onChange: (id) => setBase(id),
+    })),
+  ]);
+}
+
+/* ---------- panel: related tables ---------- */
+
+function relatedPanel() {
+  const panel = el('section', { class: 'panel composer-panel composer-related' }, el('h3', { text: 'Related tables' }));
+  const list = el('ul', { class: 'composer-rel' });
+  outgoing(list, draft.base, '', 0);
+
+  /* The other direction, and the honest treatment of it.
+
+     A has-many cannot be joined into this statement without multiplying: one
+     work order with four parts and three notes becomes twelve rows, each
+     repeating the work order's own columns, and "20 rows" stops meaning 20
+     work orders. Almost nobody asking for "work orders with their parts"
+     wants that, and a composer that produces it silently is worse than one
+     that refuses — the duplication reads as a bug in the data.
+
+     So the many side is offered as the two things that *are* one row per
+     record: a summary of the children, or a view starting from them. */
+  const incoming = refsTo(draft.base);
+  if (incoming.length) {
+    const base = findTable(draft.base);
+    list.append(el('li', { class: 'composer-rel-head', text: 'Pointing back at it' }));
+    for (const fk of incoming) {
+      const child = findTable(fk.from.table);
+      if (!child) continue;
+      list.append(el('li', { class: 'composer-rel-item many' }, [
+        el('span', { class: 'composer-phrase', text: phraseMany(base, fk) }),
+        el('span', {
+          class: 'composer-via',
+          text: `via ${fk.from.columns.join(', ')} · joining it would repeat each ${base.name} once per ${child.name}`,
+        }),
+        el('span', { class: 'composer-many-actions' }, [
+          countButton(fk, child, base),
+          summariseMenu(fk, child),
+          el('button', {
+            type: 'button',
+            class: 'composer-add',
+            title: `Start a view from ${child.name}, showing this ${base.name}`,
+            text: 'Start here',
+            onclick: () => startFromChild(fk),
+          }),
+        ]),
+      ]));
+    }
+  }
+
+  panel.append(list);
+  return panel;
+}
+
+/* ---------- summaries of the many side ---------- */
+
+const aggregates = () => draft.aggregates ?? [];
+
+const sameAggregate = (a, b) =>
+  a.fn === b.fn && a.via === b.via && (a.on ?? '') === (b.on ?? '') && (a.column ?? '') === (b.column ?? '');
+
+function addAggregate(next) {
+  if (aggregates().some((a) => sameAggregate(a, next))) return;
+  draft.aggregates = [...aggregates(), next];
+  changed();
+}
+
+function removeAggregate(target) {
+  draft.aggregates = aggregates().filter((a) => !sameAggregate(a, target));
+  changed();
+}
+
+function countButton(fk, child, base) {
+  const spec = { fn: 'count', via: fk.name };
+  const on = aggregates().some((a) => sameAggregate(a, spec));
+  return el('button', {
+    type: 'button',
+    class: `composer-add${on ? ' on' : ''}`,
+    'aria-pressed': String(on),
+    title: on
+      ? `Remove the ${child.name} count`
+      : `Add a column counting each ${base.name}'s ${plural(child.name)} — one row per ${base.name}, no repeats`,
+    text: on ? 'Counted' : 'Count',
+    onclick: () => (on ? removeAggregate(spec) : addAggregate(spec)),
+  });
+}
+
+/**
+ * Sum, min, max and average over a child column.
+ *
+ * A themed listbox rather than a row of buttons, because the useful
+ * combinations are (four functions × every number column) and that is a menu,
+ * not a toolbar. Dates get min and max only: an average of two timestamps is
+ * a number nobody asked for.
+ */
+/**
+ * Plain language for a summary, rather than function syntax.
+ *
+ * `sum(quantity)` asks the reader to translate; "Total quantity" is the thing
+ * they were already trying to say. Every tool that does this well — Metabase's
+ * "Count of rows", Airtable's rollups — leads with the question rather than
+ * the function, and the function name is recoverable from the result column
+ * anyway.
+ */
+function summaryLabel(fn, column, isDate) {
+  switch (fn) {
+    case 'sum': return `Total ${column}`;
+    case 'avg': return `Average ${column}`;
+    case 'min': return isDate ? `Earliest ${column}` : `Smallest ${column}`;
+    case 'max': return isDate ? `Latest ${column}` : `Largest ${column}`;
+    default: return `${fn} ${column}`;
+  }
+}
+
+function summariseMenu(fk, child) {
+  const items = [{ value: '', label: 'Summarise…', detail: 'a total, an average, a range' }];
+  for (const column of child.columns) {
+    if (column.primaryKey) continue;
+    /* Foreign keys are excluded. They are numeric, so a type check alone lets
+       them through, and the menu offered `sum(customer_id)` and
+       `avg(sold_by)` — adding up identifiers, which is never a question
+       anyone has. A key is a name that happens to be spelled with digits. */
+    if (column.references) continue;
+    const type = column.type.toLowerCase();
+    const numeric = /int|numeric|decimal|real|double|float|money|serial/.test(type);
+    const dateish = /date|time/.test(type);
+    if (!numeric && !dateish) continue;
+    /* A flag is numeric in SQLite and averaging it is meaningless. */
+    if (numeric && /^(is|has|can|should)_|^(active|enabled|urgent|billable)/.test(column.name)) continue;
+    const fns = numeric ? ['sum', 'avg', 'min', 'max'] : ['min', 'max'];
+    for (const fn of fns) {
+      items.push({
+        value: `${fn}:${column.name}`,
+        label: summaryLabel(fn, column.name, dateish),
+        // What the resulting column will be called, so the trade between a
+        // readable label and a namable column is visible before committing.
+        detail: `${fn}(${column.name})`,
+      });
+    }
+  }
+  if (items.length === 1) return null;
+
+  return el('span', { class: 'composer-menu' }, dropdown({
+    items,
+    value: '',
+    ariaLabel: `Summarise ${child.name}`,
+    onChange: (value) => {
+      if (!value) return;
+      const [fn, column] = value.split(':');
+      addAggregate({ fn, via: fk.name, column });
+    },
+  }));
+}
+
+/** How a summary reads in a sentence: "a count of work_order_parts". */
+function aggregateLabel(spec) {
+  const fk = state.schema.foreignKeys.find((f) => f.name === spec.via);
+  const child = fk ? findTable(fk.from.table) : null;
+  const name = child ? child.name : spec.via;
+  const where = spec.on ? ` on its ${spec.on}` : '';
+  return spec.fn === 'count'
+    ? `a count of ${plural(name)}${where}`
+    : `the ${spec.fn} of ${name}.${spec.column}${where}`;
+}
+
+/**
+ * One level of the join tree, and recursively the levels below it.
+ *
+ * Hops are grouped by the table they land on. `work_order` reaches `employee`
+ * three ways — raised_by, assigned_to, approved_by — and listing them as three
+ * sentences that differ only in a trailing column name is a list you have to
+ * read word by word rather than scan. Grouped, the question becomes the one
+ * actually being asked: *which* employee.
+ *
+ * A table reachable exactly one way keeps its full sentence, because a header
+ * plus a single row underneath is ceremony around one fact.
+ */
+function outgoing(list, tableId, prefix, depth) {
+  const table = findTable(tableId);
+  if (!table) return;
+
+  const groups = new Map();
+  for (const hop of hopsOut(tableId)) {
+    const list_ = groups.get(hop.target) ?? [];
+    list_.push(hop);
+    groups.set(hop.target, list_);
+  }
+
+  for (const [targetId, hops] of groups) {
+    const target = findTable(targetId);
+    const rows = target && target.approxRows != null
+      ? ` · ${target.approxRows.toLocaleString()} rows`
+      : '';
+
+    if (hops.length === 1) {
+      list.append(hopRow(table, hops[0], prefix, depth, {
+        phrase: phraseOne(table, hops[0]),
+        detail: `via ${hops[0].name}${rows}`,
+      }));
+      if (opened.has(pathOf(prefix, hops[0]))) {
+        outgoing(list, targetId, pathOf(prefix, hops[0]), depth + 1);
+      }
+      continue;
+    }
+
+    /* The header states the relationship once; "may have one" is used when
+       any of the ways is optional, since the group as a whole then cannot
+       promise a row. Which particular way is optional is said on its own
+       line, where it is actionable. */
+    const anyOptional = hops.some((h) => h.optional);
+    const self = targetId === table.id;
+    list.append(el('li', {
+      class: 'composer-rel-group',
+      style: depth ? `padding-left:${10 + depth * 14}px` : undefined,
+    }, [
+      el('span', {
+        class: 'composer-phrase',
+        text: `each ${table.name} ${anyOptional ? 'may have one' : 'has one'} `
+          + `${self ? 'related ' : ''}${target ? target.name : targetId}`,
+      }),
+      el('span', { class: 'composer-ways', text: `${hops.length} ways${rows}` }),
+    ]));
+
+    for (const hop of hops) {
+      list.append(hopRow(table, hop, prefix, depth, {
+        detail: `via ${hop.name}${hop.optional ? ' · may be empty' : ''}`,
+        inGroup: true,
+      }));
+      if (opened.has(pathOf(prefix, hop))) outgoing(list, targetId, pathOf(prefix, hop), depth + 1);
+    }
+  }
+}
+
+const pathOf = (prefix, hop) => (prefix ? `${prefix}.${hop.name}` : hop.name);
+
+function hopRow(table, hop, prefix, depth, { phrase, detail, inGroup }) {
+  const path = pathOf(prefix, hop);
+  const isOpen = opened.has(path);
+  const tooDeep = depth >= MAX_DEPTH;
+  const indent = 10 + depth * 14 + (inGroup ? 12 : 0);
+
+  return el('li', {
+    class: `composer-rel-item${isOpen ? ' open' : ''}${inGroup ? ' in-group' : ''}`,
+    style: indent === 10 ? undefined : `padding-left:${indent}px`,
+  }, [
+    phrase ? el('span', { class: 'composer-phrase', text: phrase }) : null,
+    el('span', { class: 'composer-via', text: detail }),
+    tooDeep && !isOpen
+      ? el('span', { class: 'composer-cap', title: `A path may follow at most ${MAX_DEPTH} references.`, text: 'too deep' })
+      : el('button', {
+          type: 'button',
+          class: `composer-add${isOpen ? ' on' : ''}`,
+          'aria-pressed': String(isOpen),
+          title: isOpen
+            ? `Remove ${path} and every field taken through it`
+            : `Add ${path} — its fields join the checklist above`,
+          text: isOpen ? 'Added' : 'Add',
+          onclick: () => (isOpen ? removeJoin(path) : addJoin(path)),
+        }),
+  ]);
+}
+
+/**
+ * Turn "each customer has many invoices" into a view of invoices.
+ *
+ * The reverse of a to-many is a to-one, so the child's own key becomes the
+ * first hop and the thing you were looking at is a column on it. That is the
+ * same result the user wanted, expressed as something a path can say.
+ */
+function startFromChild(fk) {
+  const child = findTable(fk.from.table);
+  if (!child) return;
+  draft = { ...blankView(child.id), id: draft.id, name: draft.name };
+  opened = new Set();
+  claim();
+  const hop = hopsOut(child.id).find((h) => h.fk.name === fk.name);
+  if (hop) addJoin(hop.name);
+  else changed();
+}
+
+/* ---------- panel: fields ---------- */
+
+function fieldsPanel() {
+  const panel = el('section', { class: 'panel composer-panel composer-fields' }, [
+    el('h3', {}, [
+      document.createTextNode('Fields'),
+      el('span', { class: 'composer-count', text: `${draft.columns.length} shown` }),
+    ]),
+  ]);
+
+  const groups = [{ prefix: '', tableId: draft.base }];
+  for (const prefix of [...opened].sort()) {
+    const table = tableAt(draft.base, prefix);
+    if (table) groups.push({ prefix, tableId: table.id });
+  }
+
+  /* One sentence, once, and only until it has been acted on. A view is an
+     unfamiliar idea and the panel below is just a wall of checkboxes until
+     someone tells you what the wall is for; after the first Add the sentence
+     is describing something you can already see, so it goes away. */
+  if (groups.length === 1) {
+    panel.append(el('p', { class: 'composer-empty' }, [
+      el('strong', { text: `A view is one row per ${findTable(draft.base)?.name ?? draft.base}, ` }),
+      document.createTextNode(
+        'with any field from any table it points at. Tick fields here; press '
+        + '“Add” beside a related table on the left to bring its fields into this list too.',
+      ),
+    ]));
+  }
+
+  for (const group of groups) {
+    const table = findTable(group.tableId);
+    if (!table) continue;
+    /* The group that just arrived is marked and scrolled to. Adding a related
+       table put twenty new checkboxes on screen; without this they appear
+       below the fold and the click reads as having done nothing. */
+    const fresh = group.prefix && group.prefix === justAdded;
+    const block = el('div', {
+      class: `composer-group${fresh ? ' fresh' : ''}`,
+      'data-prefix': group.prefix || undefined,
+    }, [
+      el('div', { class: 'composer-group-head' }, [
+        el('span', { class: 'composer-group-name', text: table.name }),
+        group.prefix
+          ? el('span', { class: 'composer-group-path', text: `via ${group.prefix}` })
+          : el('span', { class: 'composer-group-path', text: 'base table' }),
+        fresh ? el('span', { class: 'composer-group-new', text: 'just added' }) : null,
+      ]),
+    ]);
+    const grid = el('div', { class: 'composer-checks' });
+    for (const column of table.columns) {
+      const path = group.prefix ? `${group.prefix}.${column.name}` : column.name;
+      if (depthOf(path) > MAX_DEPTH + 1) continue;
+      const on = isSelected(path);
+      grid.append(el('label', { class: `composer-check${on ? ' on' : ''}`, title: path }, [
+        el('input', {
+          type: 'checkbox',
+          checked: on || undefined,
+          onchange: () => toggleField(path),
+        }),
+        el('span', { class: 'composer-field-name', text: column.name }),
+        el('span', { class: 'composer-field-type', text: column.type.toLowerCase() }),
+        column.primaryKey ? el('span', { class: 'composer-mark pk', text: 'key' }) : null,
+        column.references ? el('span', { class: 'composer-mark fk', title: `→ ${column.references.table}`, text: '→' }) : null,
+      ]));
+    }
+    block.append(grid);
+    panel.append(block);
+  }
+
+  /* Summaries live in the checklist rather than only where they were added,
+     because that is where you look to find out what the result contains — and
+     a column you cannot find is a column you cannot remove. */
+  if (aggregates().length) {
+    const block = el('div', { class: 'composer-group' }, [
+      el('div', { class: 'composer-group-head' }, [
+        el('span', { class: 'composer-group-name', text: 'summaries' }),
+        el('span', { class: 'composer-group-path', text: 'one value per row, from many rows' }),
+      ]),
+    ]);
+    const grid = el('div', { class: 'composer-checks' });
+    for (const spec of aggregates()) {
+      grid.append(el('label', { class: 'composer-check on', title: aggregateLabel(spec) }, [
+        el('input', { type: 'checkbox', checked: true, onchange: () => removeAggregate(spec) }),
+        el('span', { class: 'composer-field-name', text: shortAggregate(spec) }),
+        el('span', { class: 'composer-field-type', text: spec.fn }),
+      ]));
+    }
+    block.append(grid);
+    panel.append(block);
+  }
+  return panel;
+}
+
+/** The chip's text: `count(work_order_part)`, matching the column header. */
+function shortAggregate(spec) {
+  const fk = state.schema.foreignKeys.find((f) => f.name === spec.via);
+  const child = fk ? findTable(fk.from.table) : null;
+  const name = `${spec.on ? `${spec.on}.` : ''}${child ? child.name : spec.via}`;
+  return `${spec.fn}(${name}${spec.column ? `.${spec.column}` : ''})`;
+}
+
+/* ---------- panel: filter ---------- */
+
+function filterPanel() {
+  const input = el('input', {
+    class: 'composer-query',
+    type: 'text',
+    spellcheck: 'false',
+    value: draft.query,
+    'aria-label': 'Filter',
+    placeholder: 'customer_id.country_code.name = Australia and total > 500',
+  });
+
+  const box = el('div', { class: 'ac composer-ac', hidden: true, role: 'listbox' });
+  attachComplete(input, box);
+
+  input.addEventListener('input', () => {
+    draft.query = input.value;
+    /* The moment the box is edited it becomes the filter, entirely. Keeping
+       the loaded structure as a fallback would mean clearing the box quietly
+       restores a condition you just deleted — which reads as the tool
+       ignoring you. */
+    draft.filter = undefined;
+    schedulePreview();
+  });
+
+  const rows = el('input', {
+    class: 'composer-limit',
+    type: 'number',
+    min: '1',
+    max: '1000',
+    value: String(draft.limit),
+    'aria-label': 'Rows',
+    onchange: (e) => {
+      const n = Number(e.target.value);
+      draft.limit = Number.isFinite(n) && n > 0 ? Math.min(Math.floor(n), 1000) : 20;
+      schedulePreview();
+    },
+  });
+
+  return el('section', { class: 'composer-filter' }, [
+    el('div', { class: 'composer-filter-row' }, [
+      el('span', { class: 'composer-filter-label', text: 'where' }),
+      el('span', { class: 'composer-query-wrap' }, [input, box]),
+      el('span', { class: 'composer-filter-label', text: 'rows' }),
+      rows,
+    ]),
+    el('p', {
+      class: 'composer-hint',
+      text: 'Same language as the bar at the top, over paths: '
+        + 'a dot follows a reference, so customer_id.name is the customer’s name.',
+    }),
+  ]);
+}
+
+/* ---------- path-aware autocomplete ----------
+
+   complete.js does this for the query bar and is left alone: it completes
+   *columns*, and a path is a different shape — the useful suggestion after
+   `customer_id.` is the next table's columns, which needs the key graph
+   walked. Same keyboard contract, different candidate set. */
+
+const CLAUSES = ['sort', 'show', 'limit'];
+const JOINERS = ['and', 'or'];
+const OPERATORS = ['=', '!=', '>', '>=', '<', '<=', 'contains', 'startswith', 'endswith', 'like', 'in'];
+const NULL_CHECKS = ['is empty', 'is not empty'];
+const DATE_VALUES = ['today', 'yesterday', 'this week', 'last week', 'this month', 'last month', 'last 7 days', 'last 30 days'];
+const EXPECTS_FIELD = new Set(['and', 'or', 'where', 'filter', 'show', 'select', 'sort', 'by', '']);
+
+function wordAt(text, caret) {
+  const before = text.slice(0, caret);
+  const start = Math.max(before.lastIndexOf(' '), before.lastIndexOf(',')) + 1;
+  return { word: before.slice(start), start };
+}
+
+/** Paths reachable from a typed prefix: this table's columns, and its hops. */
+function pathCandidates(word) {
+  const cut = word.lastIndexOf('.');
+  const prefix = cut === -1 ? '' : word.slice(0, cut);
+  const fragment = (cut === -1 ? word : word.slice(cut + 1)).toLowerCase();
+  const table = tableAt(draft.base, prefix);
+  if (!table) return [];
+  const lead = prefix ? `${prefix}.` : '';
+  const out = [];
+
+  for (const column of table.columns) {
+    if (fragment && !column.name.toLowerCase().startsWith(fragment)) continue;
+    out.push({
+      value: `${lead}${column.name}`,
+      label: `${lead}${column.name}`,
+      detail: `${column.type.toLowerCase()}${column.primaryKey ? ' · key' : ''}`,
+      kind: 'value',
+    });
+  }
+  /* Hops end in a dot and do not close the token, so accepting one leaves the
+     caret mid-path with the next table's columns already listed. That chaining
+     is the whole reason dot-walking is pleasant to type. */
+  if (depthOf(prefix) < MAX_DEPTH) {
+    for (const hop of hopsOut(table.id)) {
+      if (fragment && !hop.name.toLowerCase().startsWith(fragment)) continue;
+      const target = findTable(hop.target);
+      out.push({
+        value: `${lead}${hop.name}.`,
+        label: `${lead}${hop.name}.`,
+        detail: `→ ${target ? target.name : hop.target}`,
+        kind: 'table',
+        partial: true,
+      });
+    }
+  }
+  return out;
+}
+
+function completionsFor(text, caret) {
+  const { word, start } = wordAt(text, caret);
+  const previous = text.slice(0, start).trim().split(/\s+/).pop()?.toLowerCase() ?? '';
+  const lower = word.toLowerCase();
+  const matches = (list) => list.filter((s) => !lower || s.value.toLowerCase().startsWith(lower));
+
+  if (word.includes('.')) return pathCandidates(word);
+
+  const previousColumn = previous ? columnAt(draft.base, previous) : null;
+  if (previousColumn) {
+    /* Was a fourth copy of the date test, and the narrowest: its name pattern
+       had lost `datetime`, `timestamp` and `deleted`, so `event_timestamp`
+       got `=` and nothing else in the composer while the query bar offered it
+       the relative-date phrases — the language's best feature, missing on the
+       columns it exists for. */
+    const isDate = looksLikeDateColumn(previousColumn);
+    const dates = isDate
+      ? DATE_VALUES.map((v) => ({ value: `= ${v}`, label: `= ${v}`, detail: 'date range', kind: 'value' }))
+      : [];
+    return matches([
+      ...dates,
+      ...OPERATORS.map((o) => ({ value: o, label: o, detail: 'operator', kind: 'op' })),
+      ...NULL_CHECKS.map((o) => ({ value: o, label: o, detail: 'null check', kind: 'op' })),
+    ]);
+  }
+
+  if (EXPECTS_FIELD.has(previous)) return pathCandidates(word);
+
+  return matches([
+    ...JOINERS.map((j) => ({ value: j, label: j, detail: 'combine', kind: 'kw' })),
+    ...CLAUSES.map((c) => ({ value: c, label: c, detail: 'clause', kind: 'kw' })),
+    ...pathCandidates(word),
+  ]);
+}
+
+function attachComplete(input, box) {
+  let items = [];
+  let index = -1;
+
+  const shut = () => {
+    box.hidden = true;
+    items = [];
+    index = -1;
+  };
+
+  const accept = (item) => {
+    const caret = input.selectionStart ?? input.value.length;
+    const { start } = wordAt(input.value, caret);
+    const after = input.value.slice(caret);
+    // A hop keeps the caret against the dot; a finished token gets a space.
+    const insert = item.partial ? item.value : item.value + (after.startsWith(' ') ? '' : ' ');
+    input.value = input.value.slice(0, start) + insert + after;
+    const next = start + insert.length;
+    input.setSelectionRange(next, next);
+    draft.query = input.value;
+    shut();
+    schedulePreview();
+    show();
+  };
+
+  const highlight = (next) => {
+    if (!items.length) return;
+    index = (next + items.length) % items.length;
+    [...box.children].forEach((node, i) => {
+      node.setAttribute('aria-selected', String(i === index));
+      node.classList.toggle('active', i === index);
+    });
+    box.children[index]?.scrollIntoView({ block: 'nearest' });
+  };
+
+  function show() {
+    const caret = input.selectionStart ?? input.value.length;
+    items = completionsFor(input.value, caret).slice(0, 40);
+    if (!items.length) return shut();
+    box.replaceChildren();
+    for (const item of items) {
+      box.append(el('div', {
+        class: `ac-item kind-${item.kind}`,
+        role: 'option',
+        // mousedown, not click: blur fires first on a click and would close
+        // the list before the selection landed.
+        onmousedown: (e) => {
+          e.preventDefault();
+          accept(item);
+        },
+      }, [
+        el('span', { class: 'ac-label', text: item.label }),
+        el('span', { class: 'ac-detail', text: item.detail }),
+      ]));
+    }
+    index = -1;
+    box.hidden = false;
+  }
+
+  input.addEventListener('input', show);
+  input.addEventListener('click', show);
+  input.addEventListener('blur', () => setTimeout(shut, 120));
+  input.addEventListener('keydown', (e) => {
+    if (box.hidden) {
+      if (e.key === ' ' && (e.ctrlKey || e.metaKey)) {
+        e.preventDefault();
+        show();
+      }
+      return;
+    }
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      highlight(index + 1);
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      highlight(index - 1);
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      e.stopPropagation();
+      shut();
+    } else if (e.key === 'Tab') {
+      e.preventDefault();
+      accept(items[index >= 0 ? index : 0]);
+    } else if (e.key === 'Enter') {
+      if (index >= 0) {
+        e.preventDefault();
+        accept(items[index]);
+      } else {
+        shut();
+      }
+    }
+  });
+}
+
+/* ---------- panel: the view, written down ----------
+
+   A view built by clicking is UI state: it can be saved and loaded, and that
+   is all. Everything else in tablewalk holds that the *text* is the source of
+   truth — it is why sorting edits the query, why a link carries the walk, why
+   a filter composes into the bar. A view that could only be clicked could not
+   be hand-edited, diffed in a config file, or pasted to someone who does not
+   have the composer open.
+
+   So the panel is editable, and applying it replaces the draft. The grammar
+   is `viewtext.ts` on the server: one language, parsed once, rather than a
+   second one here that would drift. */
+
+function textPanel() {
+  const value = textEdit ?? preview?.text ?? '';
+  const area = el('textarea', {
+    class: 'composer-text',
+    spellcheck: 'false',
+    rows: String(Math.min(10, Math.max(3, value.split('\n').length + 1))),
+    'aria-label': 'The view as text',
+    placeholder: 'invoice\n  show id, customer_id.name as customer\n  where total > 500',
+  });
+  area.value = value;
+  area.addEventListener('input', () => {
+    textEdit = area.value;
+    const apply = root.querySelector('.composer-text-apply');
+    if (apply) apply.disabled = area.value.trim() === (preview?.text ?? '').trim();
+  });
+  /* Applied on demand rather than on every keystroke. A half-typed clause is
+     the normal state of a multi-line editor, and re-running the view at each
+     character would spend the round trip on text nobody has finished. */
+  area.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+      e.preventDefault();
+      void applyText(area.value);
+    }
+  });
+
+  return el('section', { class: 'composer-textpanel' }, [
+    area,
+    el('div', { class: 'composer-text-actions' }, [
+      el('span', {
+        class: 'composer-hint',
+        text: 'Edit and apply, or paste one someone sent you. ⌘↵ applies.',
+      }),
+      el('button', {
+        type: 'button',
+        class: 'ghost composer-text-apply',
+        disabled: textEdit === null || textEdit.trim() === (preview?.text ?? '').trim() ? true : undefined,
+        text: 'Apply',
+        onclick: () => void applyText(area.value),
+      }),
+    ]),
+  ]);
+}
+
+/**
+ * Replace the draft with a written view.
+ *
+ * Parsed on the server, because that is where the grammar lives. What comes
+ * back is a real `ViewDef`, so the panels rebuild themselves from it exactly
+ * as they would from a saved view — the text form is not a second model, it
+ * is another way of writing the one that exists.
+ */
+async function applyText(value) {
+  const text = String(value ?? '').trim();
+  if (!text) return;
+  running = true;
+  paintPreview();
+  try {
+    const data = await api('/api/view/run', { text, limit: draft.limit });
+    if (data.errors?.length) {
+      previewError = data.errors;
+      running = false;
+      paintPreview();
+      return;
+    }
+    // The name and the identity are the composer's, not the text's: retyping
+    // the body of a saved view should still be that saved view.
+    loadView({ ...data.view, id: draft.id, name: draft.name });
+    preview = data;
+    previewError = null;
+    textEdit = null;
+    running = false;
+    claim();
+    redraw();
+  } catch (err) {
+    previewError = [{ message: err.message }];
+    running = false;
+    paintPreview();
+  }
+}
+
+/**
+ * Give a column its own name.
+ *
+ * Applies to summaries as well as fields — `count(work_order_part)` is a
+ * worse column heading than `parts` in exactly the same way.
+ *
+ * Matching is by output name rather than by index. The result's column order
+ * is produced by the compiler, and tying a rename to a position would break
+ * the moment a field is ticked above it.
+ */
+async function renameColumn(meta, fallbackName) {
+  const current = meta?.name ?? fallbackName;
+  const chosen = await promptFor({
+    title: 'Rename column',
+    label: 'Shown as',
+    value: current,
+    hint: meta?.aggregate
+      ? `${meta.aggregate} over ${shortTable(meta.table)}`
+      : meta?.path ?? fallbackName,
+    confirmLabel: 'Rename',
+  });
+  if (chosen === null) return;
+  const alias = chosen.trim();
+
+  if (meta?.aggregate) {
+    const list = aggregates();
+    const hit = list.find((a) => (a.alias ?? '') === current || aggregateOutputName(a) === current);
+    if (hit) hit.alias = alias || undefined;
+  } else if (meta?.path) {
+    const hit = draft.columns.find((c) => c.path === meta.path);
+    // Clearing the box removes the alias rather than setting an empty one,
+    // so the column goes back to naming itself.
+    if (hit) hit.alias = alias && alias !== meta.path ? alias : undefined;
+  }
+  claim();
+  void runPreview();
+}
+
+/** What an aggregate is called when it has no alias of its own. */
+function aggregateOutputName(spec) {
+  const fk = state.schema.foreignKeys.find((f) => f.name === spec.via);
+  const child = fk ? shortTable(fk.from.table) : spec.via;
+  return spec.alias ?? `${spec.fn}(${child}${spec.column ? `.${spec.column}` : ''})`;
+}
+
+/* ---------- panel: SQL ---------- */
+
+function sqlPanel() {
+  const text = preview?.explain
+    ?? (previewError ? 'The view does not compile yet — fix the errors above.' : 'Pick a field to see the statement.');
+  return el('pre', { class: 'explain composer-explain', text });
+}
+
+/* ---------- panel: preview ---------- */
+
+function paintPreview() {
+  if (!root) return;
+  const host = root.querySelector('#composer-preview');
+  if (host) host.replaceChildren(...[].concat(previewBody()));
+  const sql = root.querySelector('.composer-explain');
+  if (sql && showSql) sql.replaceWith(sqlPanel());
+}
+
+function previewBody() {
+  if (previewError) {
+    return el('div', { class: 'errors composer-errors' }, previewError.map((e) => el('p', { text: e.message })));
+  }
+  if (!draft.columns.length && !aggregates().length) {
+    return el('p', { class: 'note', text: 'Tick a field to see the rows.' });
+  }
+  if (!preview) {
+    return el('p', { class: 'loading', text: running ? 'Running…' : 'Building…' });
+  }
+
+  const head = el('div', { class: 'result-head' }, [
+    el('h2', { text: draft.name || draft.base }),
+    el('span', {
+      class: 'stat',
+      /* An exact total, not "first 20 rows". It is affordable *and* correct
+         only because a view never multiplies: every join is to-one, so
+         counting the view is counting the table it started from. */
+      text: preview.total !== undefined && preview.total > preview.rows.length
+        ? `${preview.rows.length.toLocaleString()} of ${preview.total.toLocaleString()} rows`
+        : `${(preview.total ?? preview.rows.length).toLocaleString()} row${(preview.total ?? preview.rows.length) === 1 ? '' : 's'}`,
+    }),
+    el('span', { class: 'stat', text: `${preview.ms} ms` }),
+    el('span', { class: 'stat', text: `${preview.joins.length} join${preview.joins.length === 1 ? '' : 's'}` }),
+    running ? el('span', { class: 'stat', text: '…' }) : null,
+  ]);
+
+  const wrap = el('div', { class: 'table-wrap' });
+  if (!preview.rows.length) {
+    wrap.append(el('p', { class: 'note', text: 'No rows match.' }));
+    return [head, wrap];
+  }
+
+  const byName = new Map(preview.resolved.map((c) => [c.name, c]));
+  const headRow = el('tr');
+  for (const name of preview.columns) {
+    const meta = byName.get(name);
+    const sorted = (draft.orderBy ?? []).find((o) => o.path === (meta ? meta.path : name));
+    const summary = meta?.aggregate;
+    headRow.append(el('th', {
+      title: summary
+        ? `${meta.aggregate} over ${shortTable(meta.table)} — one value per row, computed from many`
+        : meta ? `${meta.path} · ${meta.type}` : name,
+      class: `${sorted ? `sorted-${sorted.direction}` : ''}${summary ? ' is-summary' : ''}`.trim() || undefined,
+      // A summary is a subquery, not a column of a joined table, and sorting
+      // by one would need it repeated in ORDER BY. Left unsortable rather
+      // than sortable-but-broken.
+      onclick: summary ? undefined : () => sortByPath(meta ? meta.path : name),
+    }, [
+      // The table qualifier, then the column. A view of thirty fields drawn
+      // from five tables is unreadable if every header is just "name".
+      meta && (meta.hops || summary)
+        ? el('span', {
+            class: 'composer-th-table',
+            text: `${summary ? `${meta.aggregate} ` : ''}${shortTable(meta.table)} `,
+          })
+        : null,
+      /* An explicit alias wins: a view that named a column `owner` should say
+         `owner`, not re-derive `last_name` from where the value came from. */
+      document.createTextNode(
+        meta && meta.name !== meta.path
+          ? meta.name
+          : summary ? (meta.column === '*' ? '' : meta.column) : (meta ? meta.column : name),
+      ),
+      sorted ? el('span', { class: 'composer-th-sort', text: sorted.direction === 'desc' ? ' ↓' : ' ↑' }) : null,
+      /* Renaming lives on the header because that is where the problem is
+         visible: a manager's name arrives as `employee first_name`, which is
+         true and useless. The alias already existed in the model and in the
+         text form — there was simply no way to set one by clicking. */
+      el('button', {
+        class: 'composer-th-rename',
+        type: 'button',
+        title: 'Rename this column',
+        'aria-label': `Rename ${name}`,
+        text: '✎',
+        onclick: (e) => { e.stopPropagation(); void renameColumn(meta, name); },
+      }),
+    ]));
+  }
+
+  const tbody = el('tbody');
+  for (const row of preview.rows) {
+    const tr = el('tr');
+    for (const name of preview.columns) {
+      const value = row[name];
+      tr.append(value === null || value === undefined
+        ? el('td', { class: 'null', text: 'null' })
+        : el('td', { class: 'mono', title: String(value).length > 40 ? String(value) : undefined, text: String(value) }));
+    }
+    tbody.append(tr);
+  }
+  wrap.append(el('table', {}, [el('thead', {}, headRow), tbody]));
+  if (preview.more) {
+    wrap.append(el('p', {
+      class: 'note',
+      text: `More rows match than are shown. Raise "rows", or narrow the filter.`,
+    }));
+  }
+  return [head, wrap];
+}
+
+const shortTable = (id) => (findTable(id)?.name ?? id);
+
+/* Quotes and backslashes, for an attribute selector. Path segments cannot
+   contain either, but a selector built from data is a selector worth escaping
+   whether or not today's data needs it. */
+const cssEscape = (text) => String(text).replace(/["\\]/g, '\\$&');
+
+function sortByPath(path) {
+  const current = (draft.orderBy ?? []).find((o) => o.path === path);
+  // Click sorts ascending, click again reverses, a third clears — the same
+  // three states the results grid has, so the gesture transfers.
+  if (!current) draft.orderBy = [{ path, direction: 'asc' }];
+  else if (current.direction === 'asc') draft.orderBy = [{ path, direction: 'desc' }];
+  else draft.orderBy = [];
+  changed();
+}
+
+/* ---------- panel: saved views ---------- */
+
+function savedPanel() {
+  const panel = el('section', { class: 'panel composer-panel' }, el('h3', { text: 'Saved views' }));
+  const list = el('ul', { class: 'composer-saved' });
+
+  const all = [...savedViews(), ...fromConfig];
+  if (!all.length) {
+    panel.append(el('p', { class: 'note', text: 'Nothing saved yet. Build a view and press Save.' }));
+    return panel;
+  }
+
+  /* Pinned first, and stably: `sort` on a boolean difference leaves equal
+     items in the order they were already in, so unpinning something puts it
+     back where it was rather than shuffling the list under the cursor. */
+  const pins = pinnedIds();
+  const ordered = [...all].sort(
+    (a, b) => Number(pins.includes(b.id)) - Number(pins.includes(a.id)),
+  );
+
+  for (const view of ordered) {
+    const isConfig = view.source === 'config';
+    const pinned = pins.includes(view.id);
+    list.append(el('li', { class: `composer-saved-item${view.id === draft.id ? ' active' : ''}` }, [
+      el('button', {
+        type: 'button',
+        class: `composer-pin${pinned ? ' on' : ''}`,
+        'aria-pressed': String(pinned),
+        title: pinned ? `Unpin "${view.name}"` : `Pin "${view.name}" to the top`,
+        'aria-label': pinned ? `Unpin ${view.name}` : `Pin ${view.name}`,
+        text: pinned ? '★' : '☆',
+        onclick: () => togglePin(view.id),
+      }),
+      el('button', {
+        type: 'button',
+        class: 'composer-saved-open',
+        title: view.error
+          ? view.error
+          : `${view.base} · ${(view.columns ?? []).length} fields`
+            + `${(view.aggregates ?? []).length ? ` · ${view.aggregates.length} summaries` : ''}`,
+        disabled: view.error ? true : undefined,
+        onclick: () => openSaved(view),
+      }, [
+        el('span', { class: 'composer-saved-name', text: view.name }),
+        el('span', { class: 'composer-saved-base', text: view.base }),
+      ]),
+      isConfig
+        ? el('span', { class: 'composer-saved-tag', title: 'Defined in tablewalk.json', text: 'config' })
+        : el('button', {
+            type: 'button',
+            class: 'view-remove',
+            title: `Remove "${view.name}"`,
+            'aria-label': `Remove ${view.name}`,
+            text: '×',
+            onclick: () => void removeSaved(view),
+          }),
+    ]));
+  }
+  panel.append(list);
+  return panel;
+}
+
+function openSaved(view) {
+  loadView(view);
+  claim();
+  changed();
+}
+
+async function removeSaved(view) {
+  const ok = await askConfirm({
+    title: `Remove "${view.name}"?`,
+    body: 'The view is only stored in this browser, so this cannot be undone from here.',
+    confirmLabel: 'Remove',
+  });
+  if (!ok) return;
+  if (!writeSaved(savedViews().filter((v) => v.id !== view.id))) return;
+  if (draft.id === view.id) {
+    /* The draft stays on screen — losing your work because you tidied the
+       list would be a rude surprise — but it is no longer *that* view, and
+       the link has to stop claiming it is or reloading would 404 it. */
+    draft.id = '';
+    claim();
+  }
+  redraw();
+}
+
+/* ---------- saving ---------- */
+
+async function saveDraft() {
+  if (!draft.columns.length && !aggregates().length) {
+    toast('Pick at least one field before saving.', 'error');
+    return;
+  }
+  if (draft.source === 'config') {
+    toast('This view comes from tablewalk.json. Use "Save as…" to keep your changes here.', 'error');
+    return;
+  }
+  if (!draft.name.trim() || !draft.id) return saveAs();
+
+  const list = savedViews().map((v) => (v.id === draft.id ? snapshot(draft.id) : v));
+  if (!list.some((v) => v.id === draft.id)) list.push(snapshot(draft.id));
+  if (!writeSaved(list)) return;
+  toast(`Saved "${draft.name.trim()}".`, 'ok');
+  claim();
+  redraw();
+}
+
+async function saveAs() {
+  if (!draft.columns.length && !aggregates().length) {
+    toast('Pick at least one field before saving.', 'error');
+    return;
+  }
+  const name = await promptFor({
+    title: 'Save this view',
+    label: 'Name',
+    value: draft.name.trim() || suggestName(),
+    hint: `${draft.base} · ${draft.columns.length} fields · ${opened.size} related table${opened.size === 1 ? '' : 's'}`,
+    placeholder: 'e.g. Australian work orders',
+  });
+  if (!name) return;
+
+  draft.name = name;
+  draft.source = undefined;
+  const id = newId();
+  draft.id = id;
+  // A repeated name replaces rather than duplicating: two entries reading
+  // "Open" that do different things is worse than losing the older one.
+  const list = savedViews().filter((v) => v.name !== name);
+  list.push(snapshot(id));
+  if (!writeSaved(list)) return;
+  toast(`Saved "${name}".`, 'ok');
+  claim();
+  redraw();
+}
+
+function snapshot(id) {
+  return {
+    id,
+    name: draft.name.trim(),
+    base: draft.base,
+    columns: draft.columns.map((c) => ({ path: c.path, alias: c.alias })),
+    aggregates: draft.aggregates ?? [],
+    query: draft.query,
+    filter: draft.filter,
+    orderBy: draft.orderBy ?? [],
+    limit: draft.limit,
+  };
+}
+
+function suggestName() {
+  const table = findTable(draft.base);
+  const extras = [...opened].map((p) => {
+    const joined = tableAt(draft.base, p);
+    return joined ? joined.name : p;
+  });
+  const head = table ? table.name : draft.base;
+  return extras.length ? `${head} with ${extras.slice(0, 2).join(' and ')}` : head;
+}
+
+/* ---------- a themed confirm ---------- */
+
+function askConfirm({ title, body: text, confirmLabel = 'OK' }) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const dialog = el('dialog', { class: 'confirm' }, el('form', {
+      method: 'dialog',
+      onsubmit: (e) => {
+        e.preventDefault();
+        dialog.close();
+        finish(true);
+      },
+    }, [
+      el('h2', { text: title }),
+      el('p', { text }),
+      el('div', { class: 'confirm-actions' }, [
+        el('button', { type: 'button', class: 'ghost', text: 'Cancel', onclick: () => dialog.close() }),
+        el('button', { type: 'submit', class: 'danger', text: confirmLabel }),
+      ]),
+    ]));
+    dialog.addEventListener('close', () => {
+      finish(false);
+      dialog.remove();
+    });
+    document.body.append(dialog);
+    dialog.showModal();
+  });
+}
+
+/* ---------- navigation ----------
+
+   A composer session is a tab on a table, which is why none of this needs a
+   second URL format: the hash already carries a tab, deeplink.js already
+   round-trips it, and the app underneath renders the base table — so closing
+   the composer leaves you somewhere sensible rather than on a blank page. */
+
+function linkTo(tab) {
+  const entry = currentEntry();
+  if (entry && entry.kind === 'table' && entry.table === draft.base) {
+    go({ ...entry, tab }, 'replace');
+  } else {
+    // Rebasing rewrites the crumb rather than adding one: choosing a
+    // different starting table is editing this view, not a step in a walk.
+    go(tableView(draft.base, draft.base, tab), entry ? 'replace' : 'reset');
+  }
+}
+
+/**
+ * Update the address bar without re-rendering the app beneath.
+ *
+ * `go()` is the right call when the *position* changes; here only the label
+ * on the position changes, and putting a full render behind every edit would
+ * re-run the base table's query each time a checkbox moved.
+ */
+function stampHash() {
+  const entry = currentEntry();
+  const tab = tabForDraft();
+  if (!entry || entry.kind !== 'table' || entry.table !== draft.base) return;
+  if (entry.tab === tab) return;
+  entry.tab = tab;
+  openFor = `${draft.base}|${viewTabOf(entry)}`;
+  window.history.replaceState(null, '', toHash());
+}
+
+function leave() {
+  const entry = currentEntry();
+  closeComposer();
+  if (entry && entry.kind === 'table') go({ ...entry, tab: 'rows' }, 'replace');
+}
+
+/**
+ * Where to start when nothing is selected.
+ *
+ * Not the first table alphabetically: on the demo that is `country`, a
+ * two-column lookup with no outgoing keys, so the composer opens with an
+ * empty "related tables" panel and appears to do nothing. The table with the
+ * most references out of it is the one where the idea explains itself.
+ */
+function likeliestBase() {
+  const tables = state.schema.tables.filter((t) => !t.isView);
+  const ranked = (tables.length ? tables : state.schema.tables)
+    .map((t) => ({ id: t.id, out: refsFrom(t.id).length }))
+    .sort((a, b) => b.out - a.out);
+  return ranked[0]?.id;
+}
+
+function openFromTopbar() {
+  const entry = currentEntry();
+  const base = entry?.table ?? likeliestBase();
+  if (!base) {
+    toast('This connection has no tables to compose from.', 'error');
+    return;
+  }
+  if (entry && entry.kind === 'table') go({ ...entry, tab: 'view' }, 'replace');
+  else go(tableView(base, base, 'view'), 'reset');
+  sync();
+}
+
+/**
+ * Reconcile the overlay with wherever the app now is.
+ *
+ * Called after anything that could have navigated. It is a no-op unless the
+ * *view identity* changed, so clicking around inside the composer — which
+ * also produces clicks — cannot reset the draft underneath your hands.
+ */
+function sync() {
+  if (!state.schema) return;
+  const entry = currentEntry();
+  const id = viewTabOf(entry);
+  if (id === null) {
+    closeComposer();
+    return;
+  }
+  if (root && openFor === `${entry.table}|${id}`) return;
+  void openComposer(entry.table, id);
+}
+
+/* ---------- attach ---------- */
+
+function attach() {
+  if ($('composer-button')) return;
+  const actions = document.querySelector('.topbar-actions');
+  if (!actions) return;
+
+  /* Registered rather than inserted. The composer does not need to know what
+     else is in the header, and the header does not need to know the composer
+     exists — which is what let six top-level buttons become one menu without
+     touching this file's reason for existing. */
+  addMenuItem({
+    label: 'Views…',
+    detail: 'compose across tables',
+    onSelect: () => openFromTopbar(),
+  });
+
+  /* The stylesheet is pulled in by the page, but a module that can be dropped
+     into a build without its <link> should still look right rather than
+     silently render as unstyled boxes. Adding it twice is harmless — the
+     browser dedupes identical hrefs — and missing it is not. */
+  if (!document.querySelector('link[href="/composer.css"]')) {
+    document.head.append(el('link', { rel: 'stylesheet', href: '/composer.css' }));
+  }
+
+  window.addEventListener('popstate', () => setTimeout(sync, 0));
+  window.addEventListener('resize', positionRoot);
+  /* go() updates the address bar with pushState, which fires no event, so a
+     tab click elsewhere in the app has to be noticed some other way. A check
+     per click is cheap and, because sync() only acts on a change of view
+     identity, cannot disturb the composer while it is being used. */
+  document.addEventListener('click', () => setTimeout(sync, 0), true);
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape' && root && !document.querySelector('dialog[open]')) {
+      const inside = root.contains(document.activeElement);
+      if (inside) document.activeElement.blur();
+      else leave();
+    }
+  });
+
+  /* A link pasted into a fresh tab arrives before app.js has finished asking
+     for the schema, and applying a hash raises no event — so the first sync
+     has to wait for the schema rather than for a signal. Polling a boolean
+     ten times a second for a few seconds is not elegant, but the alternative
+     is an import line in app.js, and the module earns its keep by not
+     needing one. */
+  whenReady(() => {
+    sync();
+    setTimeout(sync, 250);
+  });
+}
+
+function whenReady(fn, tries = 0) {
+  if (state.schema) {
+    fn();
+    return;
+  }
+  if (tries > 100) return; // ten seconds; the connection is not coming.
+  setTimeout(() => whenReady(fn, tries + 1), 100);
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', attach);
+} else {
+  attach();
+}