tablewalk 0.0.1

package/dist/client/core.js

@@ -0,0 +1,893 @@
+/**
+ * The parts every other client module needs: the API, the navigation stack,
+ * the schema mirrors, and DOM building.
+ *
+ * This file deliberately depends on nothing else in the client. Everything
+ * else depends on it and not on each other, which is what keeps the module
+ * graph a fan-out rather than a web — and lets a feature live in its own file
+ * without reaching into the renderer.
+ */
+
+export const $ = (id) => document.getElementById(id);
+
+/**
+ * @type {{schema: any, stack: any[], page: number, canWrite: boolean}}
+ *
+ * `stack` is a navigation stack, and each entry is somewhere you have been —
+ * a table with a filter, or one row. The breadcrumb is that stack rendered,
+ * so walking back restores the filter you walked away from.
+ */
+export const state = { schema: null, stack: [], page: 0, canWrite: false, navMode: 'replace' };
+
+/* Matches DEFAULT_LIMIT on the server. Small on purpose: the first page of a
+   browse should be instant, and paging is one click. */
+export const PAGE_SIZE = 20;
+
+/**
+ * How many rows a page actually holds, which the reader chooses.
+ *
+ * `PAGE_SIZE` stays the default and stays equal to the server's
+ * `DEFAULT_LIMIT` — twenty is right for a first look, and the first look is
+ * what most browsing is. It was also the *only* size, which turned a
+ * sixty-thousand-row table into three thousand clicks: a table you could read
+ * the front of and nothing else.
+ *
+ * Capped at 250 rather than offering "all". The grid renders every row it is
+ * given, so the honest ceiling is the one where the DOM is still the reader's
+ * friend; past that the answer is a filter, a sort, or Export.
+ */
+export const PAGE_SIZES = [20, 50, 100, 250];
+const PAGE_SIZE_KEY = 'tablewalk.page-size';
+let chosenPageSize = null;
+
+export function pageSize() {
+  if (chosenPageSize === null) {
+    const stored = Number(loadJson(PAGE_SIZE_KEY, PAGE_SIZE));
+    /* Validated rather than trusted: the value comes from localStorage, where
+       a stale build or a hand edit can leave anything at all, and a page size
+       of `null` asks the server for `LIMIT NaN`. */
+    chosenPageSize = PAGE_SIZES.includes(stored) ? stored : PAGE_SIZE;
+  }
+  return chosenPageSize;
+}
+
+export function setPageSize(size) {
+  chosenPageSize = PAGE_SIZES.includes(Number(size)) ? Number(size) : PAGE_SIZE;
+  saveJson(PAGE_SIZE_KEY, chosenPageSize);
+  /* A page *number* means nothing once the size changes — page 40 of twenty
+     is not page 40 of a hundred — so the only honest place to land is the
+     front. */
+  state.page = 0;
+}
+
+/* Above this many rows the table is being fetched to be processed rather
+   than read, and the DOM is the bottleneck rather than the database. Until
+   the result grid is virtualised, render this many and say what was held
+   back — a silent truncation would read as "that is all there is". */
+export const RENDER_CAP = 2000;
+
+/* ---------- API ---------- */
+
+/**
+ * Endpoints that are *about* connections rather than answered by one.
+ *
+ * Naming a connection on these is at best redundant and at worst wrong:
+ * `/api/connections/remove` is about an id in its body, and resolving a second
+ * one from the same request would refuse it the moment the two disagreed.
+ */
+const CONNECTION_ENDPOINTS = /^\/api\/connections(\/|$)/;
+
+/**
+ * Every request says which database it is about.
+ *
+ * The server holds one "active" connection for the whole process, which is
+ * fine for one tab and wrong for two: switching database in one tab changed
+ * what every other tab's next request ran against, while those tabs went on
+ * rendering the schema they still had. The same query, the same screen,
+ * different data, and nothing to say so.
+ *
+ * So the connection stops being server state that the client nudges and
+ * becomes part of the question. The server's active connection remains as the
+ * answer to "no one said" — the first request of a session, before the client
+ * knows what it is connected to.
+ */
+export async function api(path, body) {
+  const conn = state.activeConnection;
+  const scoped = conn && !CONNECTION_ENDPOINTS.test(path.split('?')[0]);
+
+  let url = path;
+  if (scoped && !body) {
+    /* Appended rather than assumed to be the only parameter — `/api/ddl` and
+       `/api/pages/suggested` already carry one. */
+    url += `${path.includes('?') ? '&' : '?'}conn=${encodeURIComponent(conn)}`;
+  }
+  /* A caller that named one wins. `/api/connections/select` is followed by
+     reads that must go to the connection being switched *to*, which is not yet
+     the active one. */
+  const payload = scoped && body && body.conn === undefined ? { ...body, conn } : body;
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: payload ? 'POST' : 'GET',
+      headers: payload ? { 'content-type': 'application/json' } : undefined,
+      body: payload ? JSON.stringify(payload) : undefined,
+    });
+  } catch {
+    /* `fetch` rejects with "Failed to fetch" or "Load failed" depending on the
+       browser, and neither says the one thing that is true and useful: the
+       server this page came from is not answering. It is a local process, so
+       that nearly always means it was stopped — and "Failed to fetch" sends
+       people to look at their network. */
+    throw new Error(
+      'tablewalk is not answering. The server it was started with may have stopped — '
+      + 'restart it and reload this page.',
+    );
+  }
+
+  let data;
+  try {
+    data = await res.json();
+  } catch {
+    /* An answer that is not JSON is a proxy, a login page, or a crash — none
+       of which the caller can do anything with, and all of which read better
+       as what they are than as "Unexpected token < in JSON". */
+    throw new Error(
+      `The server answered ${res.status} with something that is not JSON. `
+      + 'Something between this page and tablewalk may be intercepting the request.',
+    );
+  }
+
+  if (!res.ok) {
+    /* The status travels with the message. Callers have always had to guess
+       the kind of failure from the text of it, which is how "No connection is
+       open." — a 409 with a specific meaning and a specific screen to show
+       for it — could only be recognised by matching a sentence. */
+    const failure = new Error(data.error ?? `Request failed (${res.status})`);
+    failure.status = res.status;
+    throw failure;
+  }
+  return data;
+}
+
+/**
+ * Run something when a node leaves the document.
+ *
+ * Observers outlive the thing they watch unless someone stops them, and these
+ * views are rebuilt constantly — browsing thirty tables left dozens of them
+ * holding detached DOM, each still re-measuring a table nobody can see on
+ * every resize, for as long as the tab was open.
+ *
+ * Watching the node's own parent does not work, and that is the whole reason
+ * this is a registry rather than one observer each: a view swap replaces the
+ * children of `#content`, which detaches the entire subtree in one operation.
+ * No `childList` record is delivered for the intermediate parents — they were
+ * not modified, they were carried off — so a watcher on the immediate parent
+ * of a nested table never hears anything.
+ *
+ * So one observer watches the place the swapping actually happens, and
+ * everything registered is swept for `isConnected` when it fires. One
+ * observer for the app rather than one per element is also the cheaper end of
+ * the trade.
+ */
+/**
+ * Make a `<details>` announce itself as the control it looks like.
+ *
+ * A `<summary>` styled as a button is read by Chromium as `group: + Count` —
+ * no role, no state, nothing to say it can be opened or that it currently is.
+ * The reader sees a button; the screen reader is told about a grouping box.
+ * Every disclosure in this app is a button in appearance and in intent, so
+ * each one says so, and keeps `aria-expanded` in step with the element's own
+ * `open` — through the `toggle` event, because a `<details>` can be opened by
+ * the keyboard, by a click on the marker, or by `open` being set in code, and
+ * only the event sees all three.
+ */
+export function disclosure(details) {
+  const summary = details.querySelector(':scope > summary');
+  if (!summary) return details;
+  summary.setAttribute('role', 'button');
+  summary.setAttribute('aria-expanded', String(details.open));
+  details.addEventListener('toggle', () => {
+    summary.setAttribute('aria-expanded', String(details.open));
+  });
+  return details;
+}
+
+/**
+ * Anything that has to be rebuilt when the database underneath changes.
+ *
+ * A connection switch is not a render: the trail is cleared, the schema is
+ * replaced and every per-connection thing — layouts, saved statements, write
+ * mode — is reloaded. Long-lived surfaces that are *not* inside `#content`
+ * miss all of it. The SQL editor was the case that showed it: painted once
+ * from the state it opened with, it went on naming the previous database
+ * while the statement it ran went to the new one, and it kept offering "Run
+ * as write…" after a switch to a connection the server would refuse.
+ *
+ * A set rather than the single `state.onSwitched` slot beside it, because the
+ * second thing that needed to know would have silently replaced the first.
+ */
+const switchWatchers = new Set();
+
+/** Register a rebuild. Returns the way to stop listening. */
+export function whenConnectionChanges(run) {
+  switchWatchers.add(run);
+  return () => switchWatchers.delete(run);
+}
+
+/**
+ * Say that the connection changed. Called by the two places that switch —
+ * the picker and a deep link into another database — after the new schema
+ * and everything keyed to it have landed, so a watcher reads the new state
+ * rather than the half-swapped one.
+ */
+export function connectionChanged() {
+  /* A copy, because a watcher may well unregister itself as its last act. */
+  for (const run of [...switchWatchers]) {
+    try {
+      run();
+    } catch (err) {
+      /* One surface failing to rebuild must not stop the next one. It is
+         already the wrong database on screen; making it the wrong database
+         everywhere is not an improvement. */
+      console.error(err);
+    }
+  }
+}
+
+const removals = new Set();
+let sweeper = null;
+
+export function whenRemoved(node, run) {
+  const entry = { node, run };
+  removals.add(entry);
+
+  if (!sweeper) {
+    const root = $('content') ?? document.body;
+    sweeper = new MutationObserver(() => {
+      for (const item of [...removals]) {
+        if (item.node.isConnected) continue;
+        removals.delete(item);
+        item.run();
+      }
+    });
+    sweeper.observe(root, { childList: true, subtree: true });
+  }
+  return () => removals.delete(entry);
+}
+
+/* ---------- schema helpers (mirrors of src/shared/schema.ts) ---------- */
+
+export const findTable = (id) => state.schema.tables.find((t) => t.id === id);
+export const refsTo = (id) => state.schema.foreignKeys.filter((fk) => fk.to.table === id);
+export const refsFrom = (id) => state.schema.foreignKeys.filter((fk) => fk.from.table === id);
+export const primaryKey = (table) => table.columns.filter((c) => c.primaryKey).map((c) => c.name);
+
+const LABEL_CANDIDATES = ['name', 'full_name', 'display_name', 'first_name', 'username', 'title', 'label', 'subject', 'number', 'email', 'slug', 'code'];
+
+/**
+ * Mirrors columnKind in shared/schema.ts.
+ *
+ * Here rather than beside the renderer that formats a column, because the
+ * date test below is defined in terms of it and every copy of that test the
+ * client grew — one per module that needed it — drifted from this one in a
+ * different direction.
+ */
+export function columnKind(type) {
+  const t = (type ?? '').toLowerCase();
+  if (/bool/.test(t)) return 'boolean';
+  if (/int|serial|numeric|decimal|real|double|float|money/.test(t)) return 'number';
+  if (/date|time/.test(t)) return 'date';
+  if (/char|text|uuid|json|enum|clob/.test(t)) return 'text';
+  return 'other';
+}
+
+/** Mirrors looksLikeDate in shared/schema.ts. */
+const DATE_NAME = /(^|_)(date|time|datetime|timestamp)(_|$)|_(at|on)$|^(created|updated|modified|deleted)(_|$)/i;
+
+/**
+ * Whether a column should be treated as a date for presentation.
+ *
+ * Exported, and the only copy: this rule had been rewritten by hand in five
+ * client modules and no two of them said the same thing. `event_timestamp
+ * TEXT` got relative-date filters in one place and not another; a `uuid`
+ * column named `created_at` was a date to the server and plain text here,
+ * because the type test was a `char|text|varchar` regex rather than the
+ * classifier the shared copy uses.
+ */
+export function looksLikeDateColumn(col) {
+  const kind = columnKind(col?.type);
+  if (kind === 'date') return true;
+  // Only text columns get the name-based benefit of the doubt; a number named
+  // `updated_at` is an epoch and comparing it to a timestamp string is wrong.
+  return kind === 'text' && DATE_NAME.test(col?.name ?? '');
+}
+
+export function labelColumn(table) {
+  const hit = LABEL_CANDIDATES.find((c) => table.columns.some((col) => col.name === c));
+  if (hit) return hit;
+  /* A date is never a good label. Two rows created the same day are
+     indistinguishable, and "2025-03-14" says nothing about *which* invoice you
+     are looking at — the key at least identifies it.
+
+     This guard exists in shared/schema.ts and had been dropped from this copy,
+     so the server and the browser disagreed about what a row is called: a
+     table whose first text column is a date got breadcrumbs and record
+     headings reading "2025-03-14" while every server-rendered label used the
+     key. */
+  /* Nor is a column the database gave a vocabulary: `status` reads like a
+     name and identifies nothing, since every sixth row shares it. */
+  const text = table.columns.find(
+    (c) => !c.primaryKey && /char|text|varchar|string/i.test(c.type)
+      && !looksLikeDateColumn(c) && !(c.allowed && c.allowed.length),
+  );
+  return text ? text.name : primaryKey(table)[0];
+}
+
+/** Mirrors IDENTITY_TABLE in shared/schema.ts. */
+const IDENTITY_TABLE = /(^|_)(party|parties|person|persons|people|user|users|profile|profiles|identity|identities)$/i;
+
+/**
+ * Mirrors labelPath in shared/schema.ts: where a row's name lives, as a view
+ * path. A table whose best label is its own key asks one forward hop further
+ * — employee has no name, `party_id.display_name` does — before settling for
+ * the number. Only across a plausibly one-to-one link: a reference that is
+ * the whole primary key, or a reference into an identity table. The invoice
+ * must not be named after its customer.
+ */
+export function labelPath(table) {
+  const own = labelColumn(table);
+  const key = primaryKey(table);
+  if (own && !key.includes(own)) return own;
+  for (const column of table.columns) {
+    const ref = column.references;
+    if (!ref || ref.table === table.id) continue;
+    const oneToOne = key.length === 1 && key[0] === column.name;
+    const target = findTable(ref.table);
+    if (!target) continue;
+    if (!oneToOne && !IDENTITY_TABLE.test(target.name)) continue;
+    const theirs = labelColumn(target);
+    if (!theirs || primaryKey(target).includes(theirs)) continue;
+    return `${column.name}.${theirs}`;
+  }
+  return own;
+}
+
+/* ---------- paths (mirrors of src/shared/view.ts) ----------
+
+   Every hop is derivable from the schema the page already holds, so proposing
+   the next segment of a path is local and instant; asking the server per
+   keystroke would make the one interaction that has to feel immediate the one
+   that does not. The server still resolves every path for real before
+   anything runs, so a mirror here can cost a suggestion and never a result.
+
+   Here rather than in the composer that reads them most, because the layout
+   builder walked the same prefixes with its own copy — one that matched a hop
+   only by its columns, so a section whose path names the *constraint* instead
+   resolved to nothing and the builder reported a reference that was still
+   perfectly present. */
+
+/** Mirrors hopName in shared/view.ts. Composite keys join their columns with +. */
+export function hopName(fk) {
+  return fk.from.columns.length === 1 ? fk.from.columns[0] : fk.from.columns.join('+');
+}
+
+/** Mirrors hopsFrom in shared/view.ts: every forward hop out of a table. */
+export function hopsFrom(tableId) {
+  const table = findTable(tableId);
+  return refsFrom(tableId).map((fk) => ({
+    name: hopName(fk),
+    fk,
+    target: fk.to.table,
+    optional: fk.from.columns.some(
+      (c) => (table ? table.columns.find((col) => col.name === c) : null)?.nullable !== false,
+    ),
+  }));
+}
+
+/** Mirrors tableAtPrefix in shared/view.ts. An empty prefix is the base. */
+export function tableAtPrefix(baseId, prefix) {
+  let table = findTable(baseId);
+  if (!prefix) return table;
+  for (const segment of prefix.split('.')) {
+    if (!table) return null;
+    const hop = hopsFrom(table.id).find((h) => h.name === segment || h.fk.name === segment);
+    if (!hop) return null;
+    table = findTable(hop.target);
+  }
+  return table;
+}
+
+/** How a row is named in a breadcrumb: the readable column, else the key. */
+export function rowLabel(table, row) {
+  /* The walked-to name first. A row fetched as a view carries the joined
+     label under its path — `party_id.display_name` — while a plain query row
+     simply lacks that key and falls through to the table's own label, then
+     the primary key. One function for both, so a caller never has to know
+     which kind of row it is holding. */
+  for (const name of [labelPath(table), labelColumn(table)]) {
+    const value = name != null ? row[name] : undefined;
+    if (value !== null && value !== undefined && String(value) !== '') return String(value);
+  }
+  const pk = primaryKey(table).map((c) => row[c]).filter((v) => v != null);
+  return pk.length ? pk.join('/') : '(row)';
+}
+
+/**
+ * The primary key of a row, or null when this row cannot supply one.
+ *
+ * Null rather than a key with `undefined` in it. A projected query — `show
+ * quantity`, or a child section showing four summary columns — returns rows
+ * that genuinely do not carry the key, and building `{invoice_id: undefined}`
+ * out of one produced a link to `~invoice_line:invoice_id=undefined` that
+ * landed on "That row is no longer there." Nothing had gone missing; the
+ * navigation was built from a row that never had the key to begin with.
+ *
+ * Callers use the null to decide whether a row is clickable at all, so a row
+ * that cannot be opened does not look like one that can.
+ */
+export function keyOf(table, row) {
+  const columns = primaryKey(table);
+  if (!columns.length) return null;
+  const key = {};
+  for (const col of columns) {
+    if (row[col] === undefined) return null;
+    key[col] = row[col];
+  }
+  return key;
+}
+
+/** A filter matching exactly one row by its primary key. */
+export function keyFilter(key) {
+  return { groups: [Object.entries(key).map(([column, value]) => ({ column, op: '=', value }))] };
+}
+
+/* ---------- DOM ---------- */
+
+export function el(tag, attrs = {}, children = []) {
+  const node = document.createElement(tag);
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === undefined || v === false || v === null) continue;
+    if (k === 'class') node.className = v;
+    else if (k === 'text') node.textContent = v;
+    else if (k.startsWith('on')) node.addEventListener(k.slice(2), v);
+    else node.setAttribute(k, v === true ? '' : String(v));
+  }
+  for (const child of [].concat(children)) {
+    if (child == null || child === false) continue;
+    node.append(child);
+  }
+  return node;
+}
+
+export function svgEl(tag, attrs = {}, children = []) {
+  const node = document.createElementNS('http://www.w3.org/2000/svg', tag);
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === undefined || v === null) continue;
+    if (k.startsWith('on')) node.addEventListener(k.slice(2), v);
+    else node.setAttribute(k, String(v));
+  }
+  for (const child of [].concat(children)) if (child) node.append(child);
+  return node;
+}
+
+/**
+ * Keep the keyboard inside a panel, and give it back on the way out.
+ *
+ * Eight surfaces here declare `role="dialog"` and `aria-modal="true"` on a
+ * plain `<div>`. The attribute is a promise: it tells a screen reader that
+ * everything behind this is inert and not to be reached. Nothing was
+ * enforcing it, so Tab walked straight out of the panel and into the table
+ * underneath — the page reading as sealed to one user and open to another,
+ * which is worse than not claiming it at all. The `<dialog>` elements
+ * elsewhere get this from the platform; these had to be told.
+ *
+ * It also puts focus back where it came from. Closing a panel used to drop
+ * focus on `<body>`, so the next Tab started again from the top of the
+ * document — a keyboard user who opened the connection manager from the
+ * toolbar and pressed Escape had to walk the whole page to get back.
+ *
+ * Returns the release function. Call it when the panel goes.
+ */
+export function trapFocus(panel) {
+  const cameFrom = document.activeElement;
+
+  /* Queried per keystroke rather than cached: these panels rebuild their own
+     contents constantly — a filter that repaints a list, a tour that swaps
+     the card — and a list captured on open goes stale immediately. */
+  const focusable = () => [...panel.querySelectorAll(
+    'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]),'
+    + ' textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
+  )].filter((node) => node.offsetWidth > 0 || node.offsetHeight > 0 || node === document.activeElement);
+
+  const onKey = (e) => {
+    if (e.key !== 'Tab') return;
+    const stops = focusable();
+    /* Nothing to move to yet — a panel painted but not filled. Swallowing the
+       key is the honest answer: the alternative is Tab escaping into the page
+       this panel has told a screen reader is inert. Escape still closes. */
+    if (!stops.length) { e.preventDefault(); return; }
+    const first = stops[0];
+    const last = stops[stops.length - 1];
+    /* Focus outside the panel entirely — it can happen, because a panel may
+       be opened while something behind it is focused. Pull it back rather
+       than letting the first Tab escape. */
+    if (!panel.contains(document.activeElement)) {
+      e.preventDefault();
+      (e.shiftKey ? last : first).focus();
+      return;
+    }
+    if (e.shiftKey && document.activeElement === first) {
+      e.preventDefault();
+      last.focus();
+    } else if (!e.shiftKey && document.activeElement === last) {
+      e.preventDefault();
+      first.focus();
+    }
+  };
+
+  /**
+   * Focus that ends up outside, brought back.
+   *
+   * Tab is not the only way out. These panels repaint themselves — the
+   * connection list arrives and replaces the loading state, a filter redraws
+   * the rows — and replacing the node that had focus drops it on `<body>`,
+   * outside the thing that claims to be modal. A click on the page behind
+   * does the same.
+   *
+   * A `<dialog>` on top is the exception, and it has to be: the connections
+   * panel opens one to add a connection, and pulling focus back to the panel
+   * underneath would make that dialog impossible to type into. The platform
+   * is already trapping focus there, so this stands aside.
+   */
+  const onFocusIn = (e) => {
+    if (!panel.isConnected) return;
+    if (panel.contains(e.target)) return;
+    if (document.querySelector('dialog[open]')) return;
+    const stops = focusable();
+    if (stops.length) stops[0].focus();
+  };
+
+  /**
+   * The panel rebuilding itself out from under the keyboard.
+   *
+   * This is the one that actually bit. These panels paint twice — a loading
+   * state, then the answer — and `replaceChildren` destroys whatever had
+   * focus. Removing a focused element does not reliably fire `blur` or
+   * `focusout` in Chrome, so nothing above hears it; focus simply becomes
+   * `<body>` and the next Tab starts from the top of the document, outside
+   * the panel that claims to be modal.
+   *
+   * Watching the subtree catches it whatever caused it — a repaint, a row
+   * that removed itself, a list that filtered. If the panel put focus
+   * somewhere itself, as the connection filter does, this sees focus already
+   * inside and stands aside.
+   */
+  const watcher = new MutationObserver(() => {
+    if (!panel.isConnected) return;
+    if (panel.contains(document.activeElement)) return;
+    if (document.querySelector('dialog[open]')) return;
+    const stops = focusable();
+    if (stops.length) stops[0].focus();
+  });
+  watcher.observe(panel, { childList: true, subtree: true });
+
+  document.addEventListener('keydown', onKey, true);
+  document.addEventListener('focusin', onFocusIn);
+  return () => {
+    watcher.disconnect();
+    document.removeEventListener('keydown', onKey, true);
+    document.removeEventListener('focusin', onFocusIn);
+    /* Only if the panel still holds it. Something that closed itself by
+       sending you somewhere — a connection row that opens that database —
+       has already put focus where it belongs. */
+    if (cameFrom?.isConnected && !document.activeElement?.closest?.('dialog')) {
+      if (!panel.isConnected || panel.contains(document.activeElement)) cameFrom.focus?.();
+    }
+  };
+}
+
+/* ---------- navigation ---------- */
+
+/* The renderer is registered rather than imported, so this module stays at
+   the bottom of the dependency graph and every view module can call `go`
+   without a cycle. */
+let renderer = () => {};
+export function setRenderer(fn) {
+  renderer = fn;
+}
+export function render() {
+  renderer();
+}
+
+/* Redrawing the trail alone, without re-running the view.
+   A row restored from a link knows only its key, so its crumb starts as the
+   key and is corrected once the row arrives. Calling render() for that would
+   re-fetch the row that just resolved it — and loop. */
+let crumbRenderer = () => {};
+export function setCrumbRenderer(fn) {
+  crumbRenderer = fn;
+}
+export function renderCrumbs() {
+  crumbRenderer();
+}
+
+/**
+ * Move to a view and render.
+ *
+ *   push    — a step along a reference; the trail grows
+ *   replace — the same view, re-run (a sort, an edited filter, a tab)
+ *   reset   — a fresh start; the trail is discarded
+ *
+ * The distinction is the whole meaning of the breadcrumb. A trail is a walk:
+ * every crumb should be reachable from the one before it by following a key.
+ * Jumping to an unrelated table is not a step along that walk, so it starts a
+ * new one rather than appending browsing history.
+ */
+export function go(entry, mode = 'push') {
+  if (mode === 'reset') state.stack = [entry];
+  else if (mode === 'replace') state.stack[state.stack.length - 1] = entry;
+  else state.stack.push(entry);
+  if (mode !== 'replace') state.page = 0;
+  /* How the address bar should record this. A step in the walk earns a
+     history entry so the browser's Back button undoes it; a refinement of the
+     view you are already on does not, or Back would spend three presses
+     undoing sort toggles. */
+  state.navMode = mode === 'replace' ? 'replace' : 'push';
+  render();
+}
+
+export function backTo(index) {
+  state.stack.length = index + 1;
+  state.page = 0;
+  // Clicking a crumb is a navigation, so Back returns you to where you were.
+  state.navMode = 'push';
+  render();
+}
+
+/** A table view, optionally filtered. The query text is what the bar shows. */
+export function tableView(tableId, query, tab) {
+  return { kind: 'table', table: tableId, query: query ?? tableId, tab: tab ?? 'rows' };
+}
+
+/**
+ * A breakdown: counts and sums, grouped by something.
+ *
+ * `table` is the base being counted, so the sidebar highlights it and the
+ * crumb reads like a table's. It is deliberately not a `tab` of the table
+ * view: the rows of a breakdown are groups rather than records, and a tab
+ * would promise they behave like the rows beside them.
+ */
+export function breakdownView(tableId, query) {
+  return { kind: 'breakdown', table: tableId, query };
+}
+
+/** A single row. The key is enough to re-fetch it, so nothing goes stale. */
+export function rowView(tableId, key, label) {
+  return { kind: 'row', table: tableId, key, label };
+}
+
+/**
+ * A page, with or without a root yet.
+ *
+ * `table` is the page's base rather than a table being browsed, so that the
+ * sidebar highlights the right thing and a page can find its way back to a
+ * suggested layout when the id names no configured page.
+ */
+export function pageView(pageId, tableId, key, label) {
+  return { kind: 'page', pageId, table: tableId, key, label };
+}
+
+export const currentEntry = () => state.stack[state.stack.length - 1];
+
+/* How a record opens, when the walk is already looking at pages.
+ *
+ * A page is a way of reading a record, not a place: someone who chose the
+ * page view for a customer wants the invoice they clicked to open the same
+ * way, and dropping them into the plain record view — and making them press
+ * "As a page" again — is the walk changing shape underneath them.
+ *
+ * The resolver is registered rather than imported because core must not know
+ * about pages: `page.js` already imports this file, and the preference for a
+ * saved or configured page over the suggested one lives there with the rest
+ * of the page machinery. Nothing registered means nothing changes.
+ */
+let pageResolver = null;
+
+export function setPageResolver(resolve) {
+  pageResolver = resolve;
+}
+
+/**
+ * Open one record, in whichever view the walk is already in.
+ *
+ * Every route into a record goes through here, so the mode is sticky by
+ * default and a call site that wants the record view specifically still says
+ * `go(rowView(...))` — which is what the table grid and the record view's own
+ * related lists do, since neither is in page view to begin with.
+ */
+export async function openRecord(tableId, key, label, how = 'push') {
+  if (currentEntry()?.kind === 'page' && pageResolver) {
+    try {
+      const pageId = await pageResolver(tableId);
+      if (pageId) {
+        go(pageView(pageId, tableId, key, label), how);
+        return;
+      }
+    } catch {
+      /* A page that cannot be resolved is not a reason to go nowhere. */
+    }
+  }
+  go(rowView(tableId, key, label), how);
+}
+
+/* ---------- chrome shared between views ---------- */
+
+/* Whether the compiled SQL is on show. Held here rather than read off a
+   button, because the control that sets it moved into a menu and the pane
+   should not care which widget last toggled it. */
+let explaining = false;
+
+export const explainVisible = () => explaining;
+
+export function setExplaining(on) {
+  explaining = on;
+  showExplain();
+}
+
+export function setExplain(sql) {
+  $('explain').textContent = sql ?? '';
+  lastExplained = sql ?? '';
+  showExplain();
+}
+
+/* The pane is hidden as a whole rather than the <pre> alone, so the control
+   that edits the statement cannot outlive the statement it edits. */
+function showExplain() {
+  const pane = $('explain-pane');
+  if (pane) pane.hidden = !explaining || !$('explain').textContent;
+}
+
+/** The statement the current view compiled to, for anything that wants to run it. */
+let lastExplained = '';
+export const explainedSql = () => lastExplained;
+
+
+export function showErrors(errors) {
+  const box = $('errors');
+  box.replaceChildren(...errors.map((e) => el('p', { text: e.message })));
+  box.hidden = !errors.length;
+
+  /* A query that did not run must not be saveable as a filter.
+  
+     The banner said `"quantitee" is not a column on invoice_line`, correctly
+     and helpfully — and beside it "+ Save this filter" stayed live, so a typo
+     could be given a name and kept. The clause chips stayed ordinary too,
+     which is the deeper misdescription: when the query fails *none* of them
+     are in effect, so a row of chips reading as the current filter is
+     describing something that is not happening.
+
+     Done here rather than where the bar is built because this is the only
+     moment the app knows: the bar is drawn from the query text, before the
+     answer comes back. */
+  const failed = errors.length > 0;
+  for (const save of document.querySelectorAll('.view-save')) {
+    save.disabled = failed;
+    save.title = failed ? 'Fix the query before saving it as a filter.' : '';
+  }
+  document.querySelector('.views')?.classList.toggle('not-in-effect', failed);
+}
+
+/**
+ * Quote a value for the query bar, only when it needs it.
+ *
+ * The one place the client writes a value into the grammar. There used to be
+ * three, disagreeing: two escaped an embedded `"` as `\"` and one deleted it
+ * outright, so a customer called `Harbour "HQ"` produced a different filter
+ * depending on which button you pressed — and neither matched, because the
+ * server stripped the quotes without unescaping. The server's `unquoteValue`
+ * now undoes exactly what this does; the pair is asserted as a round trip in
+ * mirrors.test.ts.
+ *
+ * The backslash is escaped before the quote, or a value ending in one would
+ * escape its own closing quote and swallow the rest of the query.
+ */
+export function quote(value) {
+  const text = String(value);
+  if (/^[\w.-]+$/.test(text)) return text;
+  return `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/** A short-lived message at the top of the content area. */
+/**
+ * A passing message, optionally with one thing to do about it.
+ *
+ * The action exists for the case where the message *is* the moment to act —
+ * "Updated 2 columns" is exactly when someone realises it was the wrong row,
+ * and sending them to a menu to find Undo wastes the seconds in which they
+ * still remember what they did. Anything that needs more than one verb belongs
+ * in a dialog rather than here.
+ */
+export function toast(message, tone = 'info', action) {
+  const box = $('toast');
+  box.className = `toast toast-${tone}`;
+  box.replaceChildren(el('span', { text: message }));
+  if (action) {
+    box.append(el('button', {
+      type: 'button',
+      class: 'toast-action',
+      text: action.label,
+      onclick: () => { box.hidden = true; action.run(); },
+    }));
+  }
+  box.hidden = false;
+  clearTimeout(toast.timer);
+  toast.timer = setTimeout(() => {
+    box.hidden = true;
+    // Longer when there is something to do: four seconds is enough to read a
+    // message and not enough to decide to act on one.
+  }, action ? 9000 : 4000);
+}
+
+/* ---------- persistence ----------
+
+   Every localStorage call is wrapped. It throws in Safari's private mode, it
+   throws when the quota is exceeded, and it is absent entirely in some
+   embedded webviews. A browser that cannot remember your saved filters should
+   still let you browse the database — losing a preference is not a reason to
+   lose the tool. */
+
+export function loadJson(key, fallback) {
+  try {
+    migrateNamespace();
+    const raw = window.localStorage?.getItem(key);
+    if (!raw) return fallback;
+    const parsed = JSON.parse(raw);
+    return parsed ?? fallback;
+  } catch {
+    // Corrupt or unreadable: start fresh rather than breaking the page.
+    return fallback;
+  }
+}
+
+/**
+ * Carry everything over from the previous name's namespace, once.
+ *
+ * The project was tablewalk, then datawalk, and is tablewalk again. The
+ * first rename copied lazily and left the old keys in place — so a lazy copy
+ * back would find those ancient `tablewalk.*` values first and quietly
+ * resurrect them over the `datawalk.*` ones that received every write since.
+ * One sweep instead: every `datawalk.*` key overwrites its `tablewalk.*`
+ * counterpart, newest namespace wins, and a marker stops it running twice.
+ * The old keys are left alone — a migration that also deletes has no way
+ * back if it turns out to be wrong.
+ */
+const MIGRATION_MARK = 'tablewalk.migrated-from-datawalk';
+function migrateNamespace() {
+  try {
+    const store = window.localStorage;
+    if (!store || store.getItem(MIGRATION_MARK)) return;
+    const carried = [];
+    for (let i = 0; i < store.length; i += 1) {
+      const key = store.key(i);
+      if (key?.startsWith('datawalk.')) carried.push(key);
+    }
+    // Collected before writing: setItem during iteration reorders the store.
+    for (const key of carried) {
+      const value = store.getItem(key);
+      if (value !== null) store.setItem(`tablewalk.${key.slice('datawalk.'.length)}`, value);
+    }
+    store.setItem(MIGRATION_MARK, '1');
+  } catch {
+    // Storage unavailable; nothing to migrate from either.
+  }
+}
+
+export function saveJson(key, value) {
+  try {
+    window.localStorage?.setItem(key, JSON.stringify(value));
+    return true;
+  } catch {
+    return false;
+  }
+}