tablewalk 0.0.1

package/dist/client/page.js

@@ -0,0 +1,1345 @@
+/**
+ * A page: one root, and everything that hangs off it.
+ *
+ * The walk is what this tool is for, and the walk has a cost — every hop is a
+ * page you have to find your way back from. Most of the time the questions
+ * are not really a walk at all: *who is this customer, how much have they
+ * ordered, what did they order lately, what was in it.* Four questions about
+ * one record, answered on four different screens.
+ *
+ * A page answers them at once. It is the record layout with a front door:
+ * the same sections keyed by the same foreign keys, plus numbers, plus lists
+ * that reach further than one hop, plus a way in that asks *which* customer
+ * rather than assuming you already found one.
+ *
+ * Everything that could be wrong quietly — which rows a section shows — is
+ * decided in shared/page.ts and tested there. This file decides how it looks
+ * and when it is fetched, and its own rule is that **a section that fails
+ * fails alone**: one broken path must not take the other five sections with
+ * it, because a page is most useful on the day something is misconfigured.
+ */
+import { api, columnKind, currentEntry, disclosure, el, findTable, go, keyOf, labelColumn, labelPath, loadJson, looksLikeDateColumn, openRecord, pageView, primaryKey, quote, rowLabel, saveJson, setPageResolver, state, tableView } from './core.js';
+import { renderGrid } from './table.js';
+import { refJump, valueNode } from './value.js';
+import { gridSkeleton } from './skeleton.js';
+import { dropdown } from './dropdown.js';
+import { canEditRow, editable, pendingBar } from './write.js';
+import { forgetPage, isPinned, rememberVisit, togglePinned } from './pagemarks.js';
+import { syncHash } from './url.js';
+import { openBuilder, savedPages, sharedPrefix } from './pagebuilder.js';
+
+/** Roots opened recently, per connection. Enough to recognise, not a log. */
+const RECENT_KEY = 'tablewalk.pages.recent';
+const RECENT_MAX = 8;
+
+/** Rows offered when a saved filter is used as a way in. */
+const FILTER_ROWS = 8;
+
+/* ---------- recents ---------- */
+
+const recentKey = (conn) => `${RECENT_KEY}.${conn ?? ''}`;
+
+function recentRoots(conn, pageId) {
+  return (loadJson(recentKey(conn), {})[pageId] ?? []).filter(Boolean);
+}
+
+function rememberRoot(conn, pageId, key, label) {
+  const all = loadJson(recentKey(conn), {});
+  const mine = (all[pageId] ?? []).filter((r) => JSON.stringify(r.key) !== JSON.stringify(key));
+  mine.unshift({ key, label });
+  all[pageId] = mine.slice(0, RECENT_MAX);
+  saveJson(recentKey(conn), all);
+}
+
+/* ---------- the root bar ---------- */
+
+/** Fields offered as filters: what identifies a record of this table. */
+function filterFields(base) {
+  const key = primaryKey(base);
+  /* The path, not just the column: on a table whose name lives one hop away
+     — employee, named by `party_id.display_name` — the label is the one
+     field a person could actually have typed, and a filter row without it
+     offers three opaque ids and a date. The view runner resolves the hop, so
+     a dotted path filters as readily as an own column. */
+  const label = labelPath(base);
+  /* Ordered by how findable a column makes a record, not by where it sits in
+     the table.
+  
+     Text first: a name or a code is what someone has in their head. Then
+     dates, which narrow a search properly now that the boxes go through the
+     language — `hired_on = last 30 days` is a real way to find someone, where
+     a structured `contains` on a date was not, which is why they were left
+     out before. References last, and often not at all: `job_title_id` is an
+     opaque number nobody knows, and on `employee` three of them took every
+     slot and pushed out the one field a person could have typed. */
+  const rest = base.columns.filter((c) => !key.includes(c.name) && c.name !== label);
+  const identifying = [
+    ...rest.filter((c) => !c.references && columnKind(c.type) === 'text' && !looksLikeDateColumn(c)),
+    ...rest.filter((c) => looksLikeDateColumn(c)),
+    ...rest.filter((c) => c.references),
+  ].map((c) => c.name);
+  /* Deduplicated, because `labelColumn` falls back to the primary key when a
+     table has no text column worth calling a name — `employee` is one — and
+     the list then held `id` twice, as two identical boxes filtering the same
+     column. A Set rather than a check against `key` alone: the same trap is
+     one column away for any table whose label is also a reference. */
+  return [...new Set([...key, ...(label ? [label] : []), ...identifying])].slice(0, 4);
+}
+
+/**
+ * The row that chooses, and keeps choosing, which record the page is about.
+ *
+ * It used to be a door: a search box on an otherwise empty screen, gone the
+ * moment you picked something, so changing your mind meant a button called
+ * "change…" that took you back to the empty screen. The filter is the page's
+ * own control and belongs on it — one row, always there, holding the fields
+ * that identify a record.
+ *
+ * Which fields those are comes from the schema rather than from a setting:
+ * the key, the label, and whatever else names a row. On a table with no
+ * label column — `stock_movement`, say — that is the whole of what a person
+ * has to go on, and a single "Search stock_movement…" box was offering to
+ * search a name that does not exist.
+ */
+function rootBar(page, base, current, onPick) {
+  const fields = filterFields(base);
+  const byName = new Map(base.columns.map((c) => [c.name, c]));
+  const keyColumns = primaryKey(base);
+  const inputs = new Map();
+  const results = el('div', { class: 'root-results' });
+  let token = 0;
+
+  const pick = (row) => {
+    const key = keyOf(base, row);
+    if (!key) return;
+    results.replaceChildren();
+    onPick(key, rowLabel(base, row));
+  };
+
+  /**
+   * One candidate, as a line you can tell apart from the next one.
+   *
+   * The detail used to repeat the label and then join every field with dots:
+   * `ACC-5000` followed by `1 · ACC-5000 · 37 · AUD`, where two of the four
+   * said nothing and the other two said it without saying what they were.
+   * Named pairs, and never the value already used as the title.
+   */
+  const hit = (row) => {
+    const name = rowLabel(base, row);
+    const detail = fields
+      .filter((f) => String(row[f] ?? '') !== '' && String(row[f]) !== name)
+      .map((f) => `${f} ${row[f]}`)
+      .join('  \u00b7  ');
+
+    return el('button', {
+      type: 'button',
+      class: 'root-hit',
+      onclick: () => pick(row),
+    }, [
+      el('span', { class: 'root-hit-label', text: name }),
+      detail ? el('span', { class: 'root-hit-key', text: detail }) : null,
+    ].filter(Boolean));
+  };
+
+  const search = async () => {
+    const mine = ++token;
+    /* Every non-empty box, ANDed. Text is matched loosely because a person
+       types part of a name; a key is matched exactly because a person types
+       all of an id and half of one is a different record. */
+    const conditions = [];
+    for (const [name, input] of inputs) {
+      const value = input.value.trim();
+      if (!value) continue;
+      const column = byName.get(name);
+      const exact = keyColumns.includes(name) || columnKind(column?.type) === 'number';
+      conditions.push({ path: name, op: exact ? '=' : 'contains', value });
+    }
+    if (!conditions.length) {
+      results.replaceChildren();
+      return;
+    }
+    results.classList.remove('root-offered');
+
+    try {
+      const data = await api('/api/view/run', {
+        view: {
+          id: `page:${page.id}:root`,
+          name: base.name,
+          base: base.id,
+          columns: [...new Set([...keyColumns, ...fields])].map((path) => ({ path })),
+          filter: { groups: [conditions] },
+          limit: 12,
+        },
+      });
+      if (mine !== token) return;
+      const rows = data.rows ?? [];
+      results.replaceChildren(rows.length
+        ? el('div', { class: 'root-hits' }, rows.map((row) => hit(row)))
+        : el('p', { class: 'note', text: `Nothing in ${base.name} matches.` }));
+    } catch (err) {
+      if (mine !== token) return;
+      results.replaceChildren(el('p', { class: 'note', text: err.message }));
+    }
+  };
+
+  let timer = 0;
+  const boxes = fields.map((name) => {
+    const dated = looksLikeDateColumn(byName.get(name));
+    const input = el('input', {
+      type: 'search',
+      class: 'root-field',
+      // A dotted path names its column by the last segment; the title keeps
+      // the full route for anyone wondering where the value lives.
+      placeholder: name.includes('.') ? name.split('.').pop() : name,
+      /* A date box takes a phrase, not a prefix, and nothing on it says so.
+         The title is where that belongs: the placeholder has one job, which
+         is naming the column. */
+      title: dated
+        ? `${name} — a date, or a phrase like "last 30 days" or "between 2024-01-01 and 2024-06-30"`
+        : `Filter by ${name}`,
+      'aria-label': `Filter by ${name}`,
+      autocomplete: 'off',
+      spellcheck: 'false',
+    });
+    input.addEventListener('input', () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => void search(), 220);
+    });
+    input.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') {
+        e.preventDefault();
+        clearTimeout(timer);
+        void search();
+      }
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        results.querySelector('.root-hit')?.focus();
+      }
+      if (e.key === 'Escape') results.replaceChildren();
+    });
+    inputs.set(name, input);
+    return input;
+  });
+
+  /* Collapsed once there is an answer.
+  
+     The filter is four boxes wide and, with a record already chosen, four
+     boxes doing nothing — a grey slab across the header advertising a
+     capability nobody is using, permanently, next to the title it dwarfs.
+     Changing which record the page is about is occasional; looking at the
+     record is the whole time.
+  
+     So it shows its answer and puts the boxes away, and opens again on a
+     click. With no record chosen there is nothing to collapse to and nothing
+     else to do, so they start open. */
+  const group = el('div', { class: 'root-fields' }, boxes);
+  group.hidden = Boolean(current);
+
+  const open = () => {
+    group.hidden = false;
+    boxes[0]?.focus();
+  };
+
+  const bar = el('div', { class: 'root-bar' }, [
+    current
+      ? el('button', {
+          type: 'button',
+          class: 'root-current',
+          title: `Choose a different ${base.name}`,
+          onclick: () => (group.hidden ? open() : onPick(undefined, undefined)),
+        }, [
+          el('span', { text: current }),
+          el('span', { class: 'chip-x', 'aria-hidden': 'true', text: group.hidden ? '\u2304' : '\u00d7' }),
+        ])
+      : null,
+    group,
+    ...more(page, base, onPick),
+  ].filter(Boolean));
+
+  /* With no record chosen, the page is an empty frame and a row of boxes —
+     and the answer to "which product?" is nearly always one of the last few
+     you looked at, or one of the first few there are. Both were already
+     computed; one was behind an unlabelled `···` and the other was one query
+     away, so the screen that most needed something on it had nothing.
+
+     Typed input replaces this with its own hits, and choosing a record puts
+     the whole thing away. */
+  if (!current) void offer();
+
+  async function offer() {
+    const recent = recentRoots(state.activeConnection, page.id);
+    const groups = [];
+    if (recent.length) {
+      groups.push(el('div', { class: 'root-group' }, [
+        el('h3', { class: 'root-group-head', text: 'Recently opened' }),
+        el('div', { class: 'root-hits' }, recent.map((r) => el('button', {
+          type: 'button',
+          class: 'root-hit',
+          onclick: () => onPick(r.key, r.label),
+        }, el('span', { class: 'root-hit-label', text: r.label ?? rootLabel(r.key) })))),
+      ]));
+    }
+
+    try {
+      const data = await api('/api/view/run', {
+        view: {
+          id: `page:${page.id}:first`,
+          name: base.name,
+          base: base.id,
+          columns: [...new Set([...keyColumns, ...fields])].map((path) => ({ path })),
+          limit: FILTER_ROWS,
+        },
+      });
+      /* Only if nothing was typed while this was in flight: the reader's
+         search is the answer to their question, and this is a suggestion. */
+      if (token !== 0) return;
+      const rows = data.rows ?? [];
+      if (rows.length) {
+        groups.push(el('div', { class: 'root-group' }, [
+          el('h3', { class: 'root-group-head', text: `In ${base.name}` }),
+          el('div', { class: 'root-hits' }, rows.map((row) => hit(row))),
+        ]));
+      }
+    } catch {
+      /* A suggestion that cannot be fetched is simply not offered. */
+    }
+    if (token !== 0 || !groups.length) return;
+    /* Inline, not floating: with no record chosen this is the page, and a
+       dropdown hanging over an empty screen reads as a menu someone left
+       open. It goes back to being a dropdown the moment anyone types. */
+    results.classList.add('root-offered');
+    results.replaceChildren(...groups);
+  }
+
+  return el('div', { class: 'root-wrap' }, [bar, results]);
+}
+
+/** Recents and saved filters, folded into the bar rather than stacked below it. */
+function more(page, base, onPick) {
+  const recent = recentRoots(state.activeConnection, page.id);
+  const saved = savedFiltersFor(base.id);
+  if (!recent.length && !saved.length) return [];
+
+  const menu = el('div', { class: 'root-menu' }, [
+    recent.length
+      ? el('div', { class: 'root-group' }, [
+          el('h3', { class: 'root-group-head', text: 'Recent' }),
+          ...recent.map((r) => el('button', {
+            type: 'button', class: 'root-menu-item', text: r.label,
+            onclick: () => onPick(r.key, r.label),
+          })),
+        ])
+      : null,
+    saved.length
+      ? el('div', { class: 'root-group' }, [
+          el('h3', { class: 'root-group-head', text: 'Saved filters' }),
+          ...saved.map((view) => savedFilterEntry(base, view, onPick)),
+        ])
+      : null,
+  ].filter(Boolean));
+
+  return [disclosure(el('details', { class: 'root-more' }, [
+    el('summary', { class: 'root-more-head', title: 'Recent records and saved filters' }, '\u22ef'),
+    menu,
+  ]))];
+}
+
+/**
+ * A saved filter, expanded into the records it names.
+ *
+ * Collapsed until asked, because a page with six saved filters would
+ * otherwise run six queries to draw its own controls — five of them for lists
+ * nobody was going to open.
+ */
+function savedFilterEntry(base, view, onPick) {
+  const rows = el('div', { class: 'root-filter-rows' });
+  const wrap = disclosure(el('details', { class: 'root-filter' }, [
+    el('summary', { class: 'root-filter-head' }, [
+      el('span', { class: 'root-filter-name', text: view.name }),
+    ]),
+    rows,
+  ]));
+
+  let loaded = false;
+  wrap.addEventListener('toggle', () => {
+    if (!wrap.open || loaded) return;
+    loaded = true;
+    rows.replaceChildren(el('p', { class: 'note', text: 'Looking\u2026' }));
+    void (async () => {
+      try {
+        const data = await api('/api/run', { q: view.query, limit: FILTER_ROWS });
+        const hits = data.rows ?? [];
+        rows.replaceChildren(hits.length
+          ? el('div', { class: 'root-hits' }, hits.map((row) => {
+              const key = keyOf(base, row);
+              return key
+                ? el('button', {
+                    type: 'button', class: 'root-menu-item', text: rowLabel(base, row),
+                    onclick: () => onPick(key, rowLabel(base, row)),
+                  })
+                : null;
+            }).filter(Boolean))
+          : el('p', { class: 'note', text: 'Nothing matches this filter.' }));
+      } catch (err) {
+        rows.replaceChildren(el('p', { class: 'note', text: err.message }));
+      }
+    })();
+  });
+  return wrap;
+}
+
+/** Saved filters for this table, from the browser's own store. */
+function savedFiltersFor(tableId) {
+  const all = loadJson(`tablewalk.views.${state.activeConnection ?? ''}`, {});
+  return (all[tableId] ?? []).slice(0, 6);
+}
+
+/* ---------- sections ---------- */
+
+/**
+ * The classes a section wears, on the skeleton and on the settled box alike.
+ *
+ * One function on purpose: the loading slot is *replaced* when its content
+ * arrives, so a class only the slot carried — which is how the offsets first
+ * shipped — held its place while the section loaded and vanished the moment
+ * it drew.
+ */
+function sectionClass(section) {
+  return `page-section page-${section.kind} width-${section.width ?? 'full'}`
+    + `${section.offsetLeft ? ` offset-l-${section.offsetLeft}` : ''}`
+    + `${section.offsetRight ? ` offset-r-${section.offsetRight}` : ''}`;
+}
+
+function sectionBox(section, body, { foldable = false } = {}) {
+  /* A section without a title is named after what it shows.
+  
+     The heading was rendered from `section.title` alone, so a list whose
+     title had never been typed got an empty `h3` — a blank line above a table
+     with no indication of what the table was. The builder shows the table
+     name as a *placeholder*, which reads as a default and was not one. */
+  const heading = section.title
+    ?? (section.kind === 'fields' ? '' : findTable(section.from)?.name ?? section.from);
+
+  const box = el('section', { class: sectionClass(section) });
+
+  /* A group of fields past the first one folds.
+  
+     A record with forty columns is not one list — it is the identity, the
+     money and the dates — and a page that says so is readable where a
+     forty-row grid is not. But the *first* group never folds: whatever is at
+     the top of a form is what the form is about, and a page that opens with
+     everything shut is a page that opens empty. */
+  if (foldable && heading) {
+    const details = el('details', { class: 'page-fold' }, [
+      el('summary', { class: 'page-section-head page-fold-head' }, [
+        el('span', { text: heading }),
+      ]),
+      body,
+    ]);
+    details.open = !section.collapsed;
+    box.append(disclosure(details));
+    return box;
+  }
+
+  if (heading) box.append(el('h3', { class: 'page-section-head', text: heading }));
+  box.append(body);
+  return box;
+}
+
+/** A section that could not run. Named, in place, and not fatal to the rest. */
+function brokenSection(section, message) {
+  // The same placement as the section it stands in for — a broken half at the
+  // right offset keeps the rest of the page's geometry honest.
+  return el('section', { class: `${sectionClass(section)} page-broken` }, [
+    el('h3', { class: 'page-section-head', text: section.title ?? 'This section' }),
+    el('p', { class: 'note', text: message }),
+  ]);
+}
+
+/**
+ * The root's own fields.
+ *
+ * Rendered here rather than by handing off to the record page, because a page
+ * is not a record page with extra things below it — the fields are one
+ * section among several and have to sit in a row with the others.
+ */
+async function fieldsSection(page, section, base, key, onLabel, onEdit) {
+  const paths = section.paths?.length
+    ? section.paths
+    : base.columns.map((c) => c.name);
+
+  /* The root's name rides along hidden, exactly as the record view does it:
+     a table named through a reference — employee, via `party_id.display_name`
+     — would otherwise title its page by the key whenever the layout does not
+     happen to show that field. */
+  const namePath = labelPath(base);
+  const fetched = namePath && !paths.includes(namePath) ? [...paths, namePath] : paths;
+
+  const data = await api('/api/view/run', {
+    view: {
+      id: `page:${page.id}:fields`,
+      name: base.name,
+      base: base.id,
+      columns: fetched.map((path) => ({ path })),
+      filter: { groups: [primaryKey(base).map((c) => ({ path: c, op: '=', value: key[c] }))] },
+      limit: 1,
+    },
+  });
+  const row = data.rows?.[0];
+  if (!row) throw new Error('That record is no longer there.');
+  /* The row is already here, so the filter chip can stop saying `2`.
+     Arriving by link there is no label — the link carries a key, because a
+     key is what identifies a record and a name is not. This is the first
+     moment the name is known. */
+  onLabel?.(rowLabel(base, row));
+
+  const byName = new Map(base.columns.map((c) => [c.name, c]));
+  /* Joined columns arrive described by the view compiler — type, nullability
+     — which is what lets a pulled-in date or flag render exactly as a local
+     one would. Without this the page renderer was the record renderer's poor
+     cousin: `active` as `1`, midnights kept, foreign keys as bare integers. */
+  const byPath = new Map((data.resolved ?? []).map((c) => [c.path, c]));
+
+  /* A group of fields that all follow the same reference is that record shown
+     inline — the site a work order is at, under the work order's own fields.
+     Its heading already says which record it is, so the labels drop the hop
+     they all share rather than repeating `site_id.` down the column. The
+     builder's rule, imported rather than restated: this file had its own
+     one-hop copy, so a two-hop group was stripped in the arranger and
+     fully-qualified on the page. */
+  const stem = sharedPrefix(paths);
+  const shared = stem ? `${stem}.` : '';
+
+  /* Whether this group is the record's own fields, and therefore editable in
+     write mode. A group that follows a reference shows *another* record —
+     the record view refuses to edit those for the same reason: the write
+     would land on a row the page is not showing. */
+  const own = !section.of && !stem;
+  const editing = own && canEditRow(base, key);
+
+  const fields = paths.map((path) => {
+    const value = row[path];
+    const column = byName.get(path) ?? byPath.get(path);
+    /* The same three-way rule as the record view, from the same module:
+       null says null, a foreign key is a jump, everything else renders by
+       what it is. One renderer, so a page built in the builder can never
+       again read worse than the record it was built from. */
+    const dd = editing && byName.has(path)
+      ? el('dd', { class: 'page-field-edit' }, editable(base, row, byName.get(path), key, onEdit))
+      : value === null || value === undefined
+        ? el('dd', { class: 'null', text: 'null' })
+        : column?.references && String(value) !== ''
+          ? el('dd', {}, refJump(column.references, value))
+          : el('dd', {}, valueNode(column, value));
+    return el('div', { class: 'page-field' }, [
+      el('dt', { text: shared ? path.slice(shared.length) : path, title: path }),
+      dd,
+    ]);
+  });
+
+  /* `page-field-grid`, not `page-fields`: the section wrapper around this is
+     already `page-section page-fields width-…`, from `page-${section.kind}`,
+     so a rule written for the body was landing on the wrapper too — turning
+     the section itself into an auto-fit grid. With no heading there is one
+     child and nothing shows; give the section a title and the `<h3>` takes a
+     column of its own beside the fields. */
+  const grid = el('div', { class: 'page-field-grid' }, fields);
+
+  /* A fixed column count is somebody having arranged this group, and once
+     they have, it must not reflow behind them — `auto-fit` is the right
+     default for a page nobody has laid out and the wrong answer for one
+     somebody has. The fields fill the columns in `paths` order, left to
+     right, so moving a field between columns is moving it in the list. */
+  if (section.columns) {
+    grid.style.gridTemplateColumns = `repeat(${section.columns}, minmax(0, 1fr))`;
+  }
+  return grid;
+}
+
+/** One number, and a way to see what it counted. */
+async function metricSection(section, plan) {
+  if (plan.error) throw new Error(plan.error);
+  /* A section that goes through an empty reference — "tickets at its site"
+     on a record with no site — has no number, and an em dash is the honest
+     spelling of that. Zero would claim the site was checked and had none. */
+  if (plan.empty) {
+    return el('span', {
+      class: 'page-metric-value page-metric-empty',
+      title: `This record has no ${section.of ?? 'reference'} to count through.`,
+      text: '\u2014',
+    });
+  }
+  const data = await api('/api/view/run', { view: plan.view });
+  if (data.errors?.length) throw new Error(data.errors[0].message);
+
+  /* A count reads the view's own total — exact, because a view only joins
+     to-one, so counting it is counting the table it started from. Everything
+     else is an aggregate the compiler produced, aliased `value`.
+  
+     Falling back to the first non-key column rather than to zero: a metric
+     that quietly reads 0 because an alias moved is the kind of wrong number
+     nobody checks. */
+  const value = plan.counts
+    ? data.total ?? data.rows?.length ?? 0
+    : (data.rows?.[0] ?? {}).value
+      ?? Object.entries(data.rows?.[0] ?? {}).find(([k]) => k !== 'id')?.[1];
+  if (value === undefined) throw new Error('The aggregate came back without a value.');
+
+  /* A number you cannot get behind is a number you have to take on trust,
+     so clicking one opens the rows it counted — narrowed the same way.
+  
+     Which destination depends on what the section counted, and the plan says
+     which. A one-hop count is expressible in the query language, so it opens
+     the ordinary grid. Anything further out is not — the language has no
+     dotted paths — and it opens the composer on the exact view instead. The
+     fallback used to be `section.from` on its own, which is the child table
+     *unfiltered*: the card said 3 and the grid it opened said 20. */
+  const open = plan.query
+    ? () => go(tableView(section.from, plan.query), 'push')
+    : plan.viewText
+      ? () => go(tableView(section.from, section.from, `view+${encodeURIComponent(plan.viewText).replace(/!/g, '%21')}`), 'push')
+      : null;
+
+  return el('button', {
+    type: 'button',
+    class: 'page-metric-value',
+    disabled: !open,
+    title: open
+      ? `Open the ${section.from} this counted`
+      : `${section.from} — this count cannot be reopened as a query`,
+    onclick: open ?? undefined,
+  }, [
+    el('span', { class: 'metric-number', text: typeof value === 'number' ? value.toLocaleString() : String(value) }),
+    /* The table, only when the heading did not already say it. "INVOICES /
+       7 invoice" is the same word twice in a box three inches wide. */
+    el('span', { class: 'metric-of', text: section.title ? '' : section.from }),
+  ]);
+}
+
+/**
+ * Rows related to the root, a page at a time.
+ *
+ * A list has a limit and the limit was the end of it: eight of a customer's
+ * forty orders, with nothing to say there were more and no way to see them.
+ * The whole point of putting a list on a page is that it is the real list,
+ * not a sample of one — so it pages, and says where it is.
+ *
+ * The offset lives here rather than in the entry: it is a property of looking
+ * at this section, not of the page, and putting it in the URL would make
+ * "page 3 of the orders list" a thing you could link to and then a thing that
+ * has to survive the section being moved.
+ */
+async function listSection(section, plan) {
+  if (plan.error) throw new Error(plan.error);
+  const table = findTable(section.from);
+  /* Even with nothing to list, the columns are known — they are the section's
+     own, chosen when the page was built — so the list keeps its shape and the
+     sentence explains it. A bare sentence where a table should be reads as a
+     section that failed rather than one that is empty. */
+  const columnsOf = () => (section.columns?.length
+    ? section.columns
+    : (table?.columns ?? []).map((c) => c.name));
+
+  if (plan.empty) {
+    return renderGrid(table, { columns: columnsOf(), rows: [] }, {
+      emptyText: `This record has no ${section.of ?? 'reference'} to list through.`,
+    });
+  }
+  const limit = plan.view?.limit ?? 10;
+  /* The columns this list is pinned to, and their values: every row in it has
+     them whether or not the list shows them. Only single-value equalities on
+     the view's own base, which is exactly the "these children belong to that
+     parent" filter the page builds — anything else is a condition about the
+     result, not a fact about every row in it. */
+  const pinned = pinnedBy(plan.view);
+
+  const host = el('div', { class: 'page-list-body' });
+  let offset = 0;
+
+  const load = async () => {
+    const data = await api('/api/view/run', { view: plan.view, offset });
+    if (data.errors?.length) throw new Error(data.errors[0].message);
+
+    const rows = data.rows ?? [];
+    const grid = renderGrid(table, { ...data, rows, columns: data.columns ?? columnsOf() }, {
+      emptyText: `No ${table?.name ?? section.from} for this record.`,
+      onRowClick: (row) => {
+        /* Completed from the section's own filter before the key is read.
+           A child with a composite key — `work_order_part(work_order_id,
+           line_no)` — does not show the column that points back at the root,
+           because the whole list is that value. Reading the key off the row
+           alone therefore came up short, `keyOf` returned nothing, and
+           clicking the row did nothing at all with no way to tell why. */
+        const rowKey = table && keyOf(table, { ...pinned, ...row });
+        /* As a page, because that is what the walk is already doing — see
+           `openRecord`. */
+        if (rowKey) void openRecord(table.id, rowKey, rowLabel(table, { ...pinned, ...row }));
+      },
+    });
+
+    /* Only when there is somewhere to go. A pager under a list that fits on
+       one page is two disabled buttons explaining that nothing can be done. */
+    const pager = data.more || offset > 0 ? el('div', { class: 'page-pager' }, [
+      el('span', {
+        class: 'page-range',
+        /* Says where you are, not just that you can move. `9–16 of 41` is the
+           thing a reader wants; two arrows are the thing they have to work it
+           out from. */
+        text: data.total === undefined
+          ? `${offset + 1}–${offset + rows.length}`
+          : `${offset + 1}–${offset + rows.length} of ${data.total.toLocaleString()}`,
+      }),
+      el('button', {
+        type: 'button', class: 'ghost', text: '←',
+        'aria-label': 'Previous rows', disabled: offset === 0,
+        onclick: () => { offset = Math.max(0, offset - limit); void load(); },
+      }),
+      el('button', {
+        type: 'button', class: 'ghost', text: '→',
+        'aria-label': 'More rows', disabled: !data.more,
+        onclick: () => { offset += limit; void load(); },
+      }),
+    ]) : null;
+
+    host.replaceChildren(...[grid, pager].filter(Boolean));
+  };
+
+  await load();
+  return host;
+}
+
+/* ---------- the page ---------- */
+
+/**
+ * Draw a page for one root.
+ *
+ * Sections are started together and land as they arrive, each replacing its
+ * own placeholder. A page with a count over a large child table should not
+ * hold up the record's own name, and the alternative — waiting for all of
+ * them — makes the slowest section the speed of the page.
+ */
+function renderSections(page, base, key, host, plans, onLabel, onEdit, entry) {
+  /* Hidden sections are dropped here rather than anywhere further in.
+  
+     Hiding is a layout decision, not a validity one: the section keeps its
+     columns, its order and its filter, and the page keeps its error if it has
+     one — a section that is wrong is still wrong when it is not on screen.
+     What it stops doing is drawing, and — because the fetch hangs off the
+     slot — asking. The original index travels with it, because that is what
+     the plan is keyed by. */
+  const shown = page.sections
+    .map((section, index) => ({ section, index }))
+    .filter(({ section }) => !section.hidden);
+
+  /* Which groups of fields fold: every one after the first. Decided over the
+     whole page rather than per section, because "is this the first group of
+     fields" is not a property a section knows about itself. */
+  const firstFields = shown.find(({ section }) => section.kind === 'fields')?.index;
+
+  const slots = shown.map(({ section }) =>
+    el('section', {
+      class: `${sectionClass(section)} loading`,
+    }, [
+      section.title ? el('h3', { class: 'page-section-head', text: section.title }) : null,
+      section.kind === 'list' ? gridSkeleton(4, 3) : el('div', { class: 'sk-bar' }),
+    ].filter(Boolean)));
+
+  /* A run of metrics is one item, not several.
+  
+     Metrics are as wide as their numbers, so without something to hold them
+     the next section floats up beside them and the page reads as a strip of
+     counts with one table wedged into the gap. The first attempt put an empty
+     full-width element between them to force a wrap — which works, and costs
+     a whole extra flex line: `row-gap` applies *between lines*, so the seam
+     after a metric strip was two gaps rather than one, visibly wider than
+     every other seam on the page. A negative margin cannot take it back,
+     because a line's height clamps at zero.
+  
+     Wrapping the run in one full-width item gives the strip a line of its own
+     and the page a single gap after it. */
+  /* How long the run of lists containing each section is, so a run of one
+     can stay a plain section: a single tab is a heading with a border around
+     it, and the tab strip earns its place only where there is a choice. */
+  const listRuns = new Map();
+  for (let i = 0; i < shown.length; i += 1) {
+    if (shown[i].section.kind !== 'list') continue;
+    let end = i;
+    while (end + 1 < shown.length && shown[end + 1].section.kind === 'list') end += 1;
+    for (let at = i; at <= end; at += 1) listRuns.set(at, end - i + 1);
+    i = end;
+  }
+
+  const laid = [];
+  let run = null;
+  /* A run of lists, when the page asks for tabs. Same idea as the metric
+     run above and for the same reason — "these belong together" is a fact
+     about a run of sections, not about any one of them — except that a tab
+     strip also decides what is *not* drawn, so it keeps the indexes it
+     covers rather than just holding the nodes. */
+  let strip = null;
+  const strips = [];
+  shown.forEach(({ section }, i) => {
+    if (section.kind === 'metric') {
+      strip = null;
+      if (!run) {
+        run = el('div', { class: 'page-metric-row' });
+        laid.push(run);
+      }
+      run.append(slots[i]);
+      return;
+    }
+    run = null;
+    /* Tabs unless the page says otherwise — see `listTabs`. A single list
+       is left alone: one tab is a heading with a border around it. */
+    if (page.listTabs !== false && section.kind === 'list' && listRuns.get(i) > 1) {
+      if (!strip) {
+        strip = { at: [], node: el('div', { class: 'page-tabs' }) };
+        strips.push(strip);
+        laid.push(strip.node);
+      }
+      strip.at.push(i);
+      return;
+    }
+    strip = null;
+    laid.push(slots[i]);
+  });
+
+  host.replaceChildren(...laid);
+
+  /* Which sections a tab strip is responsible for drawing, and when. A tab
+     nobody has opened has not been fetched, which is the whole reason six
+     lists as tabs are cheaper than six lists down a page. */
+  const deferred = new Set();
+  for (const { at, node } of strips) {
+    tabStrip(page, node, at.map((i) => ({ ...shown[i], at: i, slot: slots[i] })), (i) => draw(i), entry);
+    for (const i of at) deferred.add(i);
+  }
+
+  function draw(at) {
+    const { section, index } = shown[at];
+    const slot = slots[at];
+    const plan = plans.find((p) => p.index === index) ?? {};
+    const settle = (node) => {
+      /* The slot may have been swapped already — a tab drawn once is not
+         drawn again — or may not be in the document at all if the page
+         moved on while its rows were in flight. */
+      if (slot.isConnected) slot.replaceWith(node);
+    };
+    const run = section.kind === 'fields'
+      ? fieldsSection(page, section, base, key, onLabel, onEdit)
+      : section.kind === 'metric'
+        ? metricSection(section, plan)
+        : listSection(section, plan);
+
+    void run
+      .then((body) => settle(sectionBox(section, body, {
+        foldable: section.kind === 'fields' && index !== firstFields,
+      })))
+      /* One bad path must not take the page with it. A page is most useful on
+         exactly the day something is misconfigured, and a screen that renders
+         five sections and names the sixth is more useful than an error. */
+      .catch((err) => settle(brokenSection(section, err.message)));
+  }
+
+  /* Everything not behind a tab starts now; a tab starts when it is opened,
+     which for the first tab of each strip is immediately. */
+  shown.forEach((_, at) => { if (!deferred.has(at)) draw(at); });
+}
+
+/**
+ * A run of lists as tabs.
+ *
+ * The names go across the top and one table sits under them. Six things
+ * pointing at a record is six tables stacked down a page, and the sixth is a
+ * scroll away from the record it is about; as tabs it is one table deep,
+ * with the other five named.
+ *
+ * Proper tabs, not styled buttons: a tablist with arrow keys, one tab in the
+ * tab order at a time, and `aria-controls` pointing at the panel each one
+ * shows. A tab strip that cannot be driven from the keyboard is a worse
+ * version of the stack it replaced.
+ */
+function tabStrip(page, node, items, drawOne, entry) {
+  const drawn = new Set();
+  /* The tab a link asked for, matched by name rather than by position: a
+     link that pointed at "tab 2" would point somewhere else the day someone
+     reorders the sections, which is a thing the grips make easy. */
+  const named = (item) => item.section.title ?? findTable(item.section.from)?.name ?? item.section.from;
+  const asked = items.findIndex((item) => named(item) === entry?.tab);
+  let active = asked === -1 ? 0 : asked;
+
+  const panels = items.map(({ slot }, i) => {
+    const panel = el('div', {
+      class: 'page-tabpanel',
+      role: 'tabpanel',
+      id: `${page.id}-tabpanel-${i}`,
+      'aria-labelledby': `${page.id}-tab-${i}`,
+      tabindex: '0',
+    }, slot);
+    panel.hidden = i !== active;
+    return panel;
+  });
+
+  const tabs = items.map(({ section }, i) => el('button', {
+    type: 'button',
+    class: 'page-tab',
+    role: 'tab',
+    id: `${page.id}-tab-${i}`,
+    'aria-controls': `${page.id}-tabpanel-${i}`,
+    'aria-selected': String(i === active),
+    /* One stop in the tab order for the whole strip: Tab moves past the
+       group, the arrows move within it. */
+    tabindex: i === active ? '0' : '-1',
+    text: section.title ?? findTable(section.from)?.name ?? section.from,
+    onclick: () => show(i),
+    onkeydown: (e) => {
+      const step = e.key === 'ArrowRight' ? 1 : e.key === 'ArrowLeft' ? -1 : 0;
+      const to = step ? (i + step + items.length) % items.length
+        : e.key === 'Home' ? 0
+          : e.key === 'End' ? items.length - 1 : -1;
+      if (to < 0) return;
+      e.preventDefault();
+      show(to);
+      tabs[to].focus();
+    },
+  }));
+
+  function show(i) {
+    active = i;
+    tabs.forEach((tab, at) => {
+      tab.setAttribute('aria-selected', String(at === i));
+      tab.tabIndex = at === i ? 0 : -1;
+    });
+    panels.forEach((panel, at) => { panel.hidden = at !== i; });
+    if (!drawn.has(i)) {
+      drawn.add(i);
+      drawOne(items[i].at);
+    }
+    /* Written into the address bar without re-rendering: opening a tab is
+       not a step in the walk — it is what you are looking at, which is
+       exactly the thing a link should carry. The first tab writes nothing,
+       so an ordinary link stays as short as it was. */
+    if (entry) {
+      entry.tab = i === 0 ? undefined : named(items[i]);
+      syncHash();
+    }
+  }
+
+  node.replaceChildren(
+    el('div', { class: 'page-tabstrip', role: 'tablist', 'aria-label': 'Related lists' }, tabs),
+    ...panels,
+  );
+  /* The open tab is fetched — and nothing else is until someone asks for
+     it. Which tab that is may have come from the link. */
+  drawn.add(active);
+  drawOne(items[active].at);
+  return { show, get active() { return active; } };
+}
+
+export async function renderPage(entry, content) {
+  const host = el('div', { class: 'page-body' });
+  const head = el('div', { class: 'page-head' });
+  /* Appended, not replacing: the trail is already in `content`, put there by
+     the paint that called this. Replacing swallowed it, so the one view you
+     can now walk several steps deep in was the one with nothing saying where
+     you were or how to get back. */
+  content.append(el('div', { class: 'panel-pad' }, [head, host]));
+
+  let page;
+  try {
+    page = await pageById(entry.pageId, entry.table);
+  } catch (err) {
+    host.replaceChildren(el('p', { class: 'note', text: err.message }));
+    return;
+  }
+  if (page.error) {
+    head.replaceChildren(el('h2', { class: 'page-title', text: page.name }));
+    host.replaceChildren(el('p', { class: 'note', text: page.error }));
+    return;
+  }
+
+  const base = findTable(page.base);
+  if (!base) {
+    host.replaceChildren(el('p', { class: 'note', text: `"${page.base}" is not a table here.` }));
+    return;
+  }
+
+  /* A link carries the root as text, because a single-column key is written
+     as a bare value and only the base table says which column that is. */
+  if (!entry.key && entry.rootBody !== undefined) {
+    entry.key = entry.rootBody.includes('=')
+      ? Object.fromEntries(entry.rootBody.split(',').map((pair) => {
+          const [column, ...rest] = pair.split('=');
+          return [column, rest.join('=')];
+        }))
+      : { [primaryKey(base)[0]]: entry.rootBody };
+  }
+
+  const open = (key, label) => {
+    // Clearing is picking nothing, so one handler covers both.
+    if (key) rememberRoot(state.activeConnection, page.id, key, label);
+    go({ ...entry, key, label, rootBody: undefined }, 'replace');
+  };
+
+  /* Two rows, not one.
+  
+     The title, the pin, four filter boxes, the `\u00b7\u00b7\u00b7` menu and the
+     Layout button in a single flex row put the page's name and its controls
+     in competition for the same line, and the boxes — which are the widest
+     thing there and the only one you *type* into — ended up wedged between
+     two buttons. What the page is called belongs on its own line; how you
+     choose the record it is about belongs under it, full width. */
+  const identity = el('div', { class: 'page-head-top' }, [
+    /* The title is a picker when this table has more than one page: the same
+       record read two ways is the reason to build a second page at all, and
+       switching between them meant going back to the command palette and
+       finding the other one by name. The root travels across the switch —
+       that is the whole point of it. */
+    await pagePicker(page, entry),
+    pinButton(page),
+    el('button', {
+      type: 'button',
+      class: 'ghost page-edit',
+      /* A page from the config file or from the schema is not this browser's
+         to change, so editing one starts a copy — which is what someone means
+         by opening the builder on a page they cannot edit. Said on the button
+         rather than discovered on save. */
+      /* "Layout", because "Edit" on a screen full of a record's values is a
+         promise to edit the record — which this button does not do, and
+         which write mode now does right there in the fields. */
+      text: page.source === 'saved' ? 'Layout' : 'Copy layout',
+      title: page.source === 'saved'
+        ? 'Add, remove and reorder the sections of this page'
+        : 'This page belongs to the file it came from — editing it starts your own copy',
+      onclick: () => void openBuilder(page, {
+        onSaved: (saved) => go(pageView(saved.id, saved.base, entry.key, entry.label), 'replace'),
+        /* Deleting the page you are standing on has to go somewhere. The
+           table it was about is the honest answer — it is what the page was a
+           view of. */
+        onDeleted: () => {
+          /* Pinned or recently opened, it is neither now: a home screen
+             offering a link to a page that was deleted is a home screen
+             offering an error. */
+          forgetPage(page.id);
+          go(tableView(page.base), 'replace');
+        },
+      }),
+    }),
+  ]);
+
+  head.replaceChildren(
+    identity,
+    rootBar(page, base, entry.key ? (entry.label ?? rootLabel(entry.key)) : null, open),
+  );
+
+  if (!entry.key) {
+    host.replaceChildren(el('p', {
+      class: 'note page-empty',
+      text: `Choose a ${base.name} above to see this page.`,
+    }));
+    return;
+  }
+
+  /* One planning call for the whole page, then a run per section. The plan is
+     where every path is resolved, so a section that cannot be built is named
+     before anything is fetched. */
+  let plan;
+  try {
+    /* A page this browser built is sent whole: the server has never seen it,
+       so an id would name nothing. Config and suggested pages go by id, which
+       keeps the request small and lets the server be the one that decides
+       whether the page is still valid for this connection. */
+    plan = await api('/api/pages/plan', {
+      page: page.source === 'saved' ? page : page.id,
+      key: entry.key,
+    });
+  } catch (err) {
+    host.replaceChildren(el('p', { class: 'note', text: err.message }));
+    return;
+  }
+  /* The unsaved-changes bar, in the head where the record view keeps it —
+     above the fields it is about, and on screen without scrolling back. */
+  const pending = el('div', { class: 'page-pending' });
+  head.append(pending);
+  const refreshPending = (opts) => {
+    if (opts && opts.inPlace === false) {
+      go({ ...entry }, 'replace');
+      return;
+    }
+    pending.replaceChildren(
+      pendingBar(base, entry.key, (done) => refreshPending(done ?? { inPlace: true })) ?? '',
+    );
+  };
+
+  renderSections(plan.page ?? page, base, entry.key, host, plan.plans ?? [], (label) => {
+    /* Written onto the entry as well as the chip, so going away and coming
+       back through the trail keeps the name rather than dropping to the key
+       again. */
+    if (!label || entry.label === label) return;
+    entry.label = label;
+    /* Recorded again now that the record has a name: a link carries a key,
+       so the first recording could only say `1885` — which is not what
+       anybody is looking for when they come back to it. */
+    rememberVisit({ pageId: page.id, name: page.name, base: page.base, key: entry.key, label });
+
+    /* Looked up in the document rather than in the `head` this call built.
+    
+       Boot renders once and again after the incoming link is applied, so by
+       the time the fields have come back the head this closure captured can
+       be detached — the chip was updated faithfully, on an element no longer
+       on screen, while the one in front of the reader kept saying `2`.
+    
+       Guarded on the entry still being the current one, because a detached
+       head is not the only way to be late: the reader may have walked on. */
+    if (currentEntry() !== entry) return;
+    const shown = document.querySelector('.page-head .root-current > span:first-child');
+    if (shown) shown.textContent = label;
+  }, refreshPending, entry);
+
+  /* Painted once now: an edit staged before a re-render is still staged, and
+     a bar that only appears on the next keystroke is a bar that lies about
+     what is pending. */
+  refreshPending();
+
+  /* Where you were, for the home screen. Recorded after the page is known to
+     be renderable, so a link to a page that no longer exists does not put
+     itself on the list of places to go back to. */
+  rememberVisit({
+    pageId: page.id,
+    name: page.name,
+    base: page.base,
+    key: entry.key,
+    label: entry.label,
+  });
+}
+
+/** A key, when there is no label to show instead. */
+function rootLabel(key) {
+  return Object.values(key).join(' \u00b7 ');
+}
+
+/* ---------- lookup ---------- */
+
+let cache = { connection: null, pages: null };
+
+/** Every page for this connection: the config's, plus the suggested one. */
+/**
+ * The column values every row of a list already satisfies.
+ *
+ * A page's list is "the children of this record", which compiles to one
+ * equality on the child's reference column. That column is deliberately not
+ * shown — the heading says it — so it has to be put back before anything
+ * reads the row's key.
+ *
+ * One group only, and only bare `=` on the view's own base: an OR of two
+ * groups pins nothing, and a condition on a joined path is about the row's
+ * relations rather than about the row.
+ */
+function pinnedBy(view) {
+  const groups = view?.filter?.groups ?? [];
+  if (groups.length !== 1) return {};
+  const pinned = {};
+  for (const condition of groups[0]) {
+    if (condition.op !== '=' || typeof condition.path !== 'string') continue;
+    if (condition.path.includes('.')) continue;
+    pinned[condition.path] = condition.value;
+  }
+  return pinned;
+}
+
+/**
+ * The page's name, and the other pages for this table behind it.
+ *
+ * A plain heading when there is nothing to switch to, so a database with one
+ * page per table never grows a control that opens onto a list of one. The
+ * suggested layout is always in the list where it is not the page you are
+ * on: it is the page every table has, and it is the way back from a saved
+ * page that has been cut down too far.
+ */
+async function pagePicker(page, entry) {
+  let others = [];
+  try {
+    others = (await pagesFor(page.base)).filter((p) => !p.error);
+  } catch {
+    /* A config that cannot be read still leaves the page you are looking at. */
+  }
+  const suggested = { id: `suggested:${page.base}`, name: `${page.base} (default)`, source: 'suggested' };
+  const items = [...others, ...(others.some((p) => p.id === suggested.id) ? [] : [suggested])]
+    .filter((p) => p.id !== page.id);
+
+  if (!items.length) return el('h2', { class: 'page-title', text: page.name });
+
+  const picker = el('div', { class: 'page-title-pick' }, dropdown({
+    ariaLabel: 'Page',
+    value: page.id,
+    items: [
+      { value: page.id, label: page.name, detail: sourceOf(page) },
+      ...items.map((p) => ({ value: p.id, label: p.name, detail: sourceOf(p) })),
+    ],
+    onChange: (id) => {
+      if (id === page.id) return;
+      /* Replace, not push: reading the same record another way is not a step
+         along the walk, and a trail full of layout switches is a trail that
+         cannot be walked back. The root rides along. */
+      go({ ...entry, pageId: id }, 'replace');
+    },
+  }));
+  /* The page's name is `.page-title` whether or not it is also a control.
+     One name for "what this page is called on screen" — anything reading the
+     other spelling would be reading a heading that exists on some pages. */
+  picker.querySelector('.dd-value')?.classList.add('page-title');
+  return picker;
+}
+
+/**
+ * Pin this page, so the landing offers it without being asked.
+ *
+ * Beside the name rather than in the layout dialog: pinning is about how
+ * often you come back to a page, which is a thing you know while you are
+ * looking at it and not a thing you set while editing its sections.
+ */
+function pinButton(page) {
+  const button = el('button', {
+    type: 'button',
+    class: 'ghost page-pin',
+    onclick: () => {
+      paint(togglePinned(page));
+      /* The landing reads this list, and it is behind us — it will read the
+         new one when it is next drawn. */
+    },
+  });
+  const paint = (on) => {
+    button.textContent = on ? '\u2605' : '\u2606';
+    button.classList.toggle('is-pinned', on);
+    button.title = on ? `"${page.name}" is pinned to the home screen` : `Pin "${page.name}" to the home screen`;
+    button.setAttribute('aria-pressed', String(on));
+    button.setAttribute('aria-label', button.title);
+  };
+  paint(isPinned(page.id));
+  return button;
+}
+
+/** Where a page came from, which is the same question as who may change it. */
+function sourceOf(page) {
+  return page.source === 'saved' ? 'yours, in this browser'
+    : page.source === 'config' ? 'from your tablewalk.json'
+      : 'built from the schema';
+}
+
+/* Which page a record opens as, once the walk is in page view.
+ *
+ * A page someone built or configured for that table wins; otherwise the
+ * suggested one, which every table has. Registered at import time, so the
+ * rule is in force wherever a record is opened from — a list row, a
+ * reference chip — without each of those places knowing about pages. */
+setPageResolver(async (tableId) => {
+  const [configured] = await pagesFor(tableId);
+  return configured && !configured.error ? configured.id : `suggested:${tableId}`;
+});
+
+export async function pagesFor(tableId) {
+  if (cache.connection !== state.activeConnection || !cache.pages) {
+    const data = await api('/api/pages');
+    cache = { connection: state.activeConnection, pages: data.pages ?? [] };
+  }
+  /* This browser's own pages first. A page someone built here is the one they
+     were just working on; a page from the config file is the team's, and both
+     are the same kind of thing to whoever is looking for one — they differ
+     only in whether you may edit it. Read fresh rather than cached, because
+     the builder writes them and the next read must see it. */
+  const all = [...savedPages(), ...cache.pages];
+  return tableId ? all.filter((p) => p.base === tableId) : all;
+}
+
+/**
+ * Told when the set of pages changes, so the menu can be rebuilt.
+ *
+ * A callback rather than an import: the builder saves pages and the menu
+ * lists them, and having the builder call into `app.js` to say so made a
+ * cycle — app → page → pagebuilder → app — which in a test that stubs the DOM
+ * dragged boot code into a module that only wanted a function. The direction
+ * of the dependency is the thing worth keeping: the builder announces, and
+ * whoever cares listens.
+ */
+let listener = null;
+
+export function whenPagesChange(fn) {
+  listener = fn;
+}
+
+export function forgetPages() {
+  cache = { connection: null, pages: null };
+  listener?.();
+}
+
+async function pageById(id, tableId) {
+  const mine = savedPages().find((p) => p.id === id);
+  if (mine) return mine;
+  if (id?.startsWith('suggested:')) {
+    const data = await api(`/api/pages/suggested?table=${encodeURIComponent(id.slice('suggested:'.length))}`);
+    return data.page;
+  }
+  const pages = await pagesFor();
+  const found = pages.find((p) => p.id === id);
+  if (found) return found;
+
+  /* A link may name the page rather than identify it — `@customer-overview`
+     rather than `@saved:customer:1787509869158`, which is what someone
+     pastes into a ticket. Ids are tried first, so a page whose name happens
+     to look like an id still wins on its id. */
+  const named = pages.filter((p) => pageSlug(p) === id);
+  const mineFirst = named.find((p) => !tableId || p.base === tableId) ?? named[0];
+  if (mineFirst) return mineFirst;
+
+  /* And a bare table name is that table's suggested page, which is the page
+     every table has and nobody had to build. */
+  const asTable = findTable(id);
+  if (asTable) {
+    const data = await api(`/api/pages/suggested?table=${encodeURIComponent(asTable.id)}`);
+    return data.page;
+  }
+  if (tableId) {
+    const data = await api(`/api/pages/suggested?table=${encodeURIComponent(tableId)}`);
+    return data.page;
+  }
+  throw new Error(`There is no page called "${id}".`);
+}
+
+/**
+ * A page's name as it is written in a link.
+ *
+ * `saved:customer:1787509869158` is an identity, not a name: it says nothing
+ * about which page it is and carries a timestamp into every link someone
+ * pastes. The name someone gave the page is the readable half, and it is
+ * what a reader of the URL is trying to learn.
+ */
+export function pageSlug(page) {
+  return String(page?.name ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * The token a page is written as in the hash: its slug where that names it
+ * unambiguously, its id otherwise.
+ *
+ * Synchronous, because the address bar is stamped during a render and cannot
+ * wait on a fetch — so before the page list has loaded a link is written with
+ * the id, which still resolves. It becomes the readable form on the next
+ * paint, and both forms mean the same page forever.
+ */
+export function pageToken(pageId) {
+  if (!pageId) return pageId;
+  if (pageId.startsWith('suggested:')) return pageId.slice('suggested:'.length);
+  const known = [...savedPages(), ...(cache.pages ?? [])];
+  const page = known.find((p) => p.id === pageId);
+  if (!page) return pageId;
+  const slug = pageSlug(page);
+  /* Ambiguity keeps the id: two pages called "Overview" would otherwise both
+     answer to `@overview`, and a link that opens the wrong page is worse
+     than one that is hard to read. A table of the same name counts too,
+     since a bare table name is its suggested page. */
+  const clashes = known.filter((p) => pageSlug(p) === slug).length > 1 || Boolean(findTable(slug));
+  return slug && !clashes ? slug : pageId;
+}