tablewalk 0.0.1

package/dist/client/app.js

@@ -0,0 +1,973 @@
+/**
+ * The client: boot, chrome, and dispatch to a view.
+ *
+ * Plain ES modules, no framework and no build step, because the promise of
+ * this tool is `npx tablewalk mydb.sqlite` and nothing else. That constraint
+ * is worth the hand-written DOM: a bundler in the pipeline would mean a
+ * `dist/` to keep current and a reason for the published package to drift
+ * from the source. Browsers resolve the imports below natively, so the split
+ * into modules costs nothing at runtime.
+ *
+ * Everything here is wiring. The views live in their own files and reach the
+ * shared state through core.js, which imports nothing itself.
+ */
+import {
+  $, api, backTo, connectionChanged, currentEntry, el, explainVisible, findTable, go, pageView, render,
+  setCrumbRenderer, setExplaining, setRenderer, state, tableView, toast,
+  breakdownView, svgEl,
+} from './core.js';
+import { renderTable } from './table.js';
+import { renderRow } from './record.js';
+import { schemaDiagram } from './diagram.js';
+import { initWriteMode } from './write.js';
+import { initConnections, refreshConnections } from './connections.js';
+import { listConnections, showWelcome } from './welcome.js';
+import { initTour } from './tour.js';
+import { openAgentConsole } from './agent.js';
+import { openFindValue } from './findvalue.js';
+import { openShapeCheck } from './shapecheck.js';
+import { openConnections } from './connmanager.js';
+import { looksLikeBreakdown, renderBreakdown } from './breakdown.js';
+import { openAsk } from './ask.js';
+import { cycleTheme, initTheme, themeLabel } from './theme.js';
+import { allSavedFilters, savedViewsBar } from './views.js';
+import { allowSync, applyHash, connectionFromHash, fromHash, resolveLabels, syncHash, whileApplying } from './url.js';
+import { initComplete } from './complete.js';
+import { addMenuItem, initMenu, setMenuGroup } from './menu.js';
+import { initSql, openSql } from './sql.js';
+import { schemaSummary } from './summary.js';
+import { pagesFor, renderPage, whenPagesChange } from './page.js';
+import { pinnedPages, recentVisits } from './pagemarks.js';
+import { loadSavedPages } from './pagebuilder.js';
+import { initPeek } from './peek.js';
+import { initUndo, refreshUndo, undoDescription, undoLast } from './undo.js';
+import { loadSavedSql } from './sqlsaved.js';
+import { loadTemplates } from './template.js';
+import { initPalette, initSidebarToggle, openPalette } from './palette.js';
+import { initHelp } from './help.js';
+/* Imported for its side effect: composer.js attaches its own entry point, the
+   way history.js does. Loading it from a stylesheet's onload worked, but a
+   script that runs because a CSS file finished downloading is a dependency
+   nobody would guess from reading either file. */
+import './composer.js';
+
+/* ---------- dispatch ---------- */
+
+function paint() {
+  const content = $('content');
+  const entry = currentEntry();
+  // Every render is a state change worth linking to, so the address bar is
+  // updated here rather than at each of the dozen places that call go().
+  syncHash();
+  if (!entry) {
+    // With nothing selected, the most useful thing to show is the shape of
+    // the database itself — the whole point of the tool, before a click.
+    highlightTable(null);
+    content.replaceChildren(el('div', { class: 'panel-pad' }, [
+      /* Saved filters come first. Someone who has saved one is coming back to
+         it; making them re-derive the table from a diagram every time is the
+         landing page failing at its only job. */
+      /* Two columns: what you were doing, beside what this database is.
+      
+         They answer different questions and both are short, so stacking them
+         pushed the schema — the thing a first-time reader needs — below the
+         fold for anyone who had ever saved anything. Side by side, both are
+         above it.
+      
+         A first visit has no work to resume, and `workPanel` returns nothing
+         at all rather than an empty card; the survivor is then an only child
+         and takes the whole width, which is the layout that page wants and
+         needs no branch to say so. */
+      el('div', { class: 'landing-top' }, [
+        /* The database first, on the left where reading starts: it is the
+           answer for everyone, including the person who has never been here.
+           What you were doing sits beside it, because it is only an answer
+           once there is some. */
+        schemaSummary(),
+        /* One card, not four bands. Saved filters, pinned pages, where you
+           were and every page there is were four full-width sections, each
+           with its own heading and none the same width — a pile rather than
+           an answer. They are all work you already did, waiting to be
+           resumed. */
+        workPanel(),
+      ].filter(Boolean)),
+      schemaDiagram(),
+    ].filter(Boolean)));
+    return;
+  }
+  highlightTable(entry.table);
+  content.replaceChildren(breadcrumb());
+  if (entry.kind === 'table') {
+    /* Saved filters sit above the view tabs and below the trail: they are a
+       property of the table you are on, not of the walk that got you here. */
+    const views = savedViewsBar(entry);
+    if (views) content.append(views);
+    void renderTable(entry, content);
+  } else if (entry.kind === 'breakdown') {
+    /* Named explicitly, like `page` below and for the same reason: a dispatch
+       whose last branch is "or else a row" turns every kind it has not heard
+       of into a record view asking for a key nobody supplied. */
+    void renderBreakdown(entry, content);
+  } else if (entry.kind === 'page') {
+    /* Named explicitly rather than left to the `else`. This dispatch used to
+       be "table, or else a row", so any third kind of entry silently rendered
+       as a record — a page would have asked for the row `undefined` and shown
+       an error about a key nobody supplied. */
+    void renderPage(entry, content);
+  } else {
+    void renderRow(entry, content);
+  }
+}
+
+/**
+ * The landing page's shortcut back to work.
+ *
+ * Absent entirely when nothing is saved — an empty "Saved" heading above a
+ * schema diagram is a promise the tool has not kept yet.
+ */
+/**
+ * Everything you already did, in one card.
+ *
+ * Three questions in the order they are asked: what am I coming back to
+ * (pinned), where was I (a page *and* the record), and what else is there
+ * (saved filters, then every page, behind a filter box because a database
+ * with forty pages is one where finding a page matters more than seeing
+ * them all).
+ */
+function workPanel() {
+  const groups = [];
+  const pages = knownPages();
+  const byId = new Map(pages.map((p) => [p.id, p]));
+  const openPage = (pageId, base, key, label) =>
+    go(pageView(pageId, byId.get(pageId)?.base ?? base, key, label), 'reset');
+
+  /* A link, not a card.
+  
+     Four groups of two-line boxes made a wall of rectangles in four
+     different widths — "way more broken/jumbled up", and fairly. The card
+     under this one has answered four questions for months as a dim label
+     and a line of links, and nobody has ever complained about it. So this
+     card uses the same idiom: the label says which question, the links are
+     the answer, and there is one box on the screen instead of eleven. */
+  const link = (name, detail, title, onclick) => el('button', {
+    type: 'button', class: 'landing-link', title, onclick,
+  }, [
+    el('span', { class: 'landing-link-name', text: name }),
+    detail ? el('span', { class: 'landing-link-detail', text: detail }) : null,
+  ].filter(Boolean));
+
+  const line = (label, content) => el('li', { class: 'shape-line' }, [
+    el('span', { class: 'shape-label', text: label }),
+    el('span', { class: 'landing-links' }, content),
+  ]);
+
+  const pinned = pinnedPages();
+  if (pinned.length) {
+    groups.push(line('Pinned', pinned.map((page) =>
+      link(page.name, page.base, `A page about one ${page.base}`, () => openPage(page.id, page.base)))));
+  }
+
+  /* A position, not a page: the record is what makes it worth going back to,
+     and a list of page names would send you to the chooser you already got
+     past. */
+  const positions = recentVisits().filter((v) => v.label);
+  if (positions.length) {
+    groups.push(line('Where you were', positions.slice(0, 6).map((visit) =>
+      link(visit.label, visit.name, `${visit.name} — ${visit.label}`,
+        () => openPage(visit.pageId, visit.base, visit.key, visit.label)))));
+  }
+
+  const saved = allSavedFilters();
+  if (saved.length) {
+    groups.push(line('Saved filters', saved.map((view) =>
+      link(view.name, view.table, view.query, () => go(tableView(view.table, view.query), 'reset')))));
+  }
+
+  if (pages.length) {
+    const list = el('div', { class: 'landing-page-list' });
+    const draw = (needle) => {
+      const shown = pages.filter((p) => `${p.name} ${p.base}`.toLowerCase().includes(needle));
+      list.replaceChildren(...(shown.length
+        ? shown.map((page) => el('button', {
+            type: 'button',
+            class: 'landing-page',
+            onclick: () => openPage(page.id, page.base),
+          }, [
+            el('span', { class: 'landing-page-name', text: page.name }),
+            el('span', { class: 'landing-page-base', text: page.base }),
+            el('span', {
+              class: 'landing-page-source',
+              text: page.source === 'config' ? 'config' : page.source === 'saved' ? 'yours' : 'suggested',
+            }),
+          ]))
+        : [el('p', { class: 'note', text: 'No page of that name.' })]));
+    };
+    draw('');
+
+    groups.push(el('li', { class: 'shape-line landing-all' }, [
+      el('span', { class: 'shape-label', text: `All pages (${pages.length})` }),
+      el('div', {}, [
+        el('input', {
+          type: 'search',
+          class: 'landing-page-filter',
+          placeholder: 'Filter pages…',
+          'aria-label': 'Filter pages',
+          oninput: (e) => draw(e.target.value.trim().toLowerCase()),
+        }),
+        list,
+      ]),
+    ]));
+  }
+
+  /* Nothing to resume is not an empty card: on a database nobody has worked
+     in yet, the schema below really is the most useful thing on screen. */
+  if (!groups.length) return null;
+
+  return el('section', { class: 'landing-pages shape' }, [
+    el('h2', { class: 'landing-heading', text: 'Your work' }),
+    el('ul', { class: 'shape-lines' }, groups),
+  ]);
+}
+
+/* The pages this connection has, as the last read left them. Synchronous,
+   because the landing is drawn before anything is fetched — `registerPages`
+   has already filled the cache by the time anyone has a page to come back
+   to, and a first visit has none to show anyway. */
+let landingPages = [];
+const knownPages = () => landingPages;
+
+/**
+ * Back to the schema, from anywhere.
+ *
+ * At module scope because the trail needs it as well as the wordmark — see
+ * the root crumb in `breadcrumb`.
+ */
+function goHome() {
+  state.stack = [];
+  state.page = 0;
+  $('query').value = '';
+  render();
+}
+
+function breadcrumb() {
+  const bar = el('nav', { class: 'crumbs', 'aria-label': 'Trail' });
+
+  /* The trail starts at the schema, and says so.
+  
+     It used to start at whatever you were looking at, so a link opened deep —
+     which is how most links are opened — offered no way back to the landing
+     page at all. The wordmark has always been that button, but a wordmark is
+     not where anybody looks for one, and nothing on screen said it was
+     clickable. A trail whose first step is missing is the one place the
+     absence is obvious, so that is where it goes. */
+  /* An icon rather than the word "Schema".
+  
+     A house is the one glyph everybody already reads as "back to the start",
+     and it does not compete with the table names beside it for the eye — the
+     crumbs are text, so the one thing in the trail that is not a step should
+     not look like one. Drawn rather than typed: `⌂` renders at wildly
+     different weights across platforms and is missing outright on some. */
+  bar.append(el('button', {
+    type: 'button',
+    class: 'crumb-home',
+    title: 'The schema, your work, the diagram (h)',
+    'aria-label': 'Schema',
+    onclick: goHome,
+  }, svgEl('svg', {
+    viewBox: '0 0 16 16', width: '17', height: '17', 'aria-hidden': 'true',
+    fill: 'none', stroke: 'currentColor', 'stroke-width': '1.5',
+    'stroke-linecap': 'round', 'stroke-linejoin': 'round',
+  }, [
+    svgEl('path', { d: 'M2 7.2 8 2.4l6 4.8' }),
+    svgEl('path', { d: 'M3.4 6.6V13a.6.6 0 0 0 .6.6h8a.6.6 0 0 0 .6-.6V6.6' }),
+  ])));
+
+  state.stack.forEach((entry, i) => {
+    bar.append(el('span', { class: 'sep', text: '›' }));
+    const last = i === state.stack.length - 1;
+
+    /* A row crumb names its table when the walk has changed table — which is
+       exactly what following a foreign key does. Without it a trail reads
+       `work_order › WO-100008 › Southerly Surveying`, and nothing says that
+       the last step landed on a customer. Repeating the table when it has not
+       changed would be noise: `work_order › work_order WO-100008` says
+       nothing the crumb before it did not. */
+    const previousTable = i > 0 ? state.stack[i - 1].table : null;
+    /* A page crumb is a record crumb that happens to be drawn as a page, so
+       it names its table on the same rule. A page with no root chosen has no
+       label yet and is named by its table alone. */
+    const named = entry.kind === 'row' || entry.kind === 'page';
+    const showsTable = named && entry.label != null && entry.table !== previousTable;
+    /* A page reached by link knows its own name before it knows its table —
+       the link deliberately does not carry the base, since the page names it
+       — so the crumb falls through to the page rather than to `undefined`,
+       which is what it read while the page was loading. */
+    const name = entry.kind === 'table' || entry.kind === 'breakdown'
+      ? entry.query
+      : entry.label ?? entry.table ?? entry.pageId ?? '…';
+
+    const content = showsTable
+      ? [el('span', { class: 'crumb-table', text: entry.table }), document.createTextNode(name)]
+      : [document.createTextNode(name)];
+
+    bar.append(
+      last
+        ? el('span', { class: 'current' }, content)
+        : el('button', { type: 'button', onclick: () => backTo(i) }, content),
+    );
+  });
+
+  /* One step back along the trail, at the end of the trail it steps along.
+
+     It does what clicking the second-to-last crumb does, rather than calling
+     history.back() — a trail arrived at by pasting a link has crumbs but no
+     browser history behind it, and a Back button that did nothing on exactly
+     the pages people share links to would be worse than none. The browser's
+     own Back still works; this is the walk's back, which is a different
+     thing: it goes up the trail, not to whatever you looked at last. */
+  if (state.stack.length > 1) {
+    const previous = state.stack[state.stack.length - 2];
+    bar.append(el('button', {
+      type: 'button',
+      class: 'crumb-back',
+      title: `Back to ${previous.kind === 'table' || previous.kind === 'breakdown' ? previous.query : previous.label}`,
+      onclick: () => backTo(state.stack.length - 2),
+    }, [
+      el('span', { 'aria-hidden': 'true', text: '\u2190' }),
+      el('span', { text: 'Back' }),
+    ]));
+  }
+
+  return bar;
+}
+
+/**
+ * The tab the current view is on, if it is a table view.
+ *
+ * Rows for anything else: arriving from a record, the reader has not chosen a
+ * tab, and defaulting to whatever they last looked at three walks ago would
+ * be guessing.
+ */
+function stickyTab() {
+  const entry = currentEntry();
+  return entry?.kind === 'table' ? entry.tab ?? 'rows' : 'rows';
+}
+
+function highlightTable(tableId) {
+  const buttons = sidebarButtons();
+  buttons.forEach((button, i) => {
+    const current = button.dataset.table === tableId;
+    button.setAttribute('aria-current', String(current));
+    /* The keyboard cursor follows the mouse — class as well as index.
+       Clicking `invoice` and then pressing Down should move to
+       `invoice_line`, not to the second table in the list because the cursor
+       was still parked where the last arrow key left it; and the parked
+       row's `.active` styling used to stay behind too, a second selected
+       row that nothing would clear until the next arrow key. */
+    button.classList.toggle('active', current);
+    if (current) sidebarIndex = i;
+  });
+  // Cursor and current are the same row again; see highlightSidebar.
+  $('table-list')?.classList.remove('skimming');
+}
+
+/* ---------- sidebar ---------- */
+
+/** Index of the keyboard-highlighted table, or -1. Reset whenever the
+    filter changes, because the list it indexes into has changed. */
+let sidebarIndex = -1;
+
+function sidebarButtons() {
+  return [...document.querySelectorAll('#table-list button')];
+}
+
+function highlightSidebar(index) {
+  const buttons = sidebarButtons();
+  if (!buttons.length) return;
+  // Wraps, so holding one arrow key cycles rather than sticking at the end.
+  sidebarIndex = (index + buttons.length) % buttons.length;
+  buttons.forEach((b, i) => b.classList.toggle('active', i === sidebarIndex));
+  /* Whether the cursor has run ahead of the table on screen. The preview
+     behind the arrow keys is debounced, so for a beat the row being read
+     and the row being pointed at are different rows — and both carried the
+     full "you are here" treatment, two selected tables flashing during any
+     quick run down the list. The class lets the stale one step back until
+     the preview catches up (highlightTable clears it). */
+  $('table-list')?.classList.toggle(
+    'skimming',
+    buttons[sidebarIndex].getAttribute('aria-current') !== 'true',
+  );
+  buttons[sidebarIndex].scrollIntoView({ block: 'nearest' });
+}
+
+/**
+ * Move focus into the panel beside the list.
+ *
+ * The first thing worth landing on rather than the first focusable thing:
+ * a column header or a row, not the breadcrumb you just came through. If the
+ * panel has nothing to focus, the container itself takes it, so the keyboard
+ * is at least on the right side of the page.
+ */
+function focusContent() {
+  const content = $('content');
+  const target =
+    content.querySelector('tbody tr, .th-sort, .related-item, .field-group-head') ?? content;
+  if (target === content) content.tabIndex = -1;
+  target.focus({ preventScroll: true });
+  target.scrollIntoView?.({ block: 'nearest' });
+}
+
+/** Pending preview, so holding an arrow key does not fire a query per row. */
+let previewTimer = null;
+
+/**
+ * Move the highlight, and show what it lands on.
+ *
+ * Arrowing down a list of sixty-six tables and having the panel beside it not
+ * change makes the arrow keys a way of scrolling rather than a way of
+ * looking — you still have to press Enter on each one to find out what is in
+ * it. Highlight moves immediately; the query follows a beat later, so holding
+ * the key down skims the list without firing sixty-six queries on the way
+ * past.
+ *
+ * Navigation is a replace, not a push: skimming should not fill the browser's
+ * history with every table you scrolled past on the way to the one you
+ * wanted.
+ */
+function moveSidebar(delta) {
+  highlightSidebar(sidebarIndex + delta);
+  const button = sidebarButtons()[sidebarIndex];
+  if (!button) return;
+
+  /* Focus moves with the highlight.
+
+     Leaving it on the row you arrowed away from drew two selections at once —
+     a focus ring on the old table and the current-row styling on the new one —
+     which looks like the list cannot decide where you are. The exception is
+     the filter field: if you are typing there, focus belongs to what you are
+     typing in, and the highlight is a cursor into the list rather than a
+     place your hands are. */
+  if (document.activeElement !== $('table-filter')) button.focus({ preventScroll: true });
+
+  clearTimeout(previewTimer);
+  previewTimer = setTimeout(() => {
+    go(tableView(button.dataset.table, undefined, stickyTab()), 'replace');
+  }, 110);
+}
+
+function renderTableList(filterText = '') {
+  const list = $('table-list');
+  const needle = filterText.trim().toLowerCase();
+  sidebarIndex = -1;
+  list.replaceChildren();
+  for (const table of state.schema.tables) {
+    if (needle && !table.id.toLowerCase().includes(needle)) continue;
+    list.append(
+      el('li', {}, el('button', {
+        type: 'button',
+        'data-table': table.id,
+        /* Out of the tab order, in the arrow order.
+
+           Sixty-six tables in the tab sequence means Tab is useless for what
+           Tab is for — moving between the regions of the page. The list is a
+           single stop reached through the filter field, and moved within by
+           the arrow keys, which is the roving-tabindex pattern every real
+           listbox uses. Focus is still set programmatically when arrowing. */
+        tabindex: -1,
+        /* Stays on the tab you were reading.
+        
+           Comparing two tables' diagrams meant picking the next table and
+           landing back on Rows, then clicking Diagram again — the sidebar
+           was answering "show me this table" by also silently answering
+           "and go back to the default view of it". */
+        onclick: () => go(tableView(table.id, undefined, stickyTab()), 'reset'),
+      }, [
+        el('span', { text: table.name }),
+        table.isView
+          ? el('span', { class: 'view-tag', text: 'view' })
+          : table.approxRows != null
+            ? el('span', { class: 'rows', text: table.approxRows.toLocaleString() })
+            : null,
+      ])),
+    );
+  }
+  if (!list.childElementCount) list.append(el('li', {}, el('p', { class: 'note', text: 'No matches.' })));
+}
+
+/**
+ * Every page this connection has, as one command each.
+ *
+ * Registered rather than given a nav item: a database with one page does not
+ * deserve a permanent tab, and one with nine cannot fit them. `addMenuItem`
+ * puts each in the overflow menu and in ⌘K from a single registration, which
+ * is where someone looks for "the customer page" anyway.
+ */
+async function registerPages() {
+  try {
+    /* `onSelect` and `detail`, which is what the registry reads. It had been
+       `run` and `hint` — names nothing on the other side of this call knows —
+       so every page in ⌘K and in the overflow menu threw on click and did
+       nothing visible. The one command group built from data was the one
+       group nobody could use. */
+    const pages = await pagesFor();
+    landingPages = pages.filter((p) => !p.error);
+    /* The home screen is drawn before this arrives — it is the first paint —
+       so it is drawn again once the pages are known. Only there: anywhere
+       else the reader is looking at something, and redrawing it under them
+       to add a list they cannot see is worse than the wait. */
+    if (!currentEntry()) render();
+    setMenuGroup('Pages', pages.map((page) => ({
+      label: page.name,
+      detail: page.error ? page.error : `one ${page.base}`,
+      onSelect: () => {
+        if (page.error) {
+          toast(page.error, 'error');
+          return;
+        }
+        go(pageView(page.id, page.base), 'reset');
+      },
+    })));
+  } catch {
+    /* A connection whose pages cannot be read is a connection with no pages
+       in the menu. It is not a reason to stop starting up. */
+  }
+}
+
+/* ---------- boot ---------- */
+
+/**
+ * Switch connection, then rebuild the trail from the link.
+ *
+ * The order is the point: the hash is parsed only after the new schema has
+ * arrived, because a trail into another database names tables this one does
+ * not have and would parse to nothing.
+ */
+async function switchAndRestore(id, hash) {
+  try {
+    const { schema } = await api('/api/connections/select', { id });
+    state.schema = schema;
+    state.activeConnection = id;
+    /* The picker names this tab's connection, not the server's idea of an
+       active one. A link into one database with the sidebar naming another is
+       the interface disagreeing with itself about where you are — and now
+       that every request carries its own connection, the server's active is
+       not this tab's answer to anything. */
+    void refreshConnections();
+    // Layouts and saved pages are stored per connection, so the new
+    // connection's are pulled before anything is drawn with them — and
+    // before the menu is rebuilt, which reads the saved-pages mirror.
+    await loadTemplates();
+    await loadSavedPages();
+    await loadSavedSql();
+    // A different database has different pages.
+    void registerPages();
+    /* Same signal the picker sends, so a deep link into another database
+       rebuilds the long-lived surfaces the way a switch does. */
+    connectionChanged();
+    renderTableList();
+    const parsed = fromHash(
+      hash,
+      (t) => findTable(t) ?? state.schema.tables.find((x) => x.name === t),
+      { isBreakdown: looksLikeBreakdown },
+    );
+    whileApplying(() => {
+      state.stack = parsed?.stack ?? [];
+      state.page = 0;
+      state.navMode = 'replace';
+      render();
+    });
+    /* Written explicitly, after the suppressed render. Boot renders once
+       before the link is applied and stamps the *previous* connection into
+       the address bar; without this the URL keeps claiming a database the
+       page is no longer showing, and copying it hands someone the wrong
+       link. */
+    /* Open the address gate here, not in boot: on a cold deep link into
+       another database the boot deliberately left it shut so that no render
+       between then and now could stamp the outgoing connection into the bar.
+       Now the target is loaded and current, so its address is the right one
+       to write. Idempotent for the picker/popstate callers, where it is
+       already open. */
+    allowSync();
+    state.navMode = 'replace';
+    syncHash();
+    $('db-label').textContent = `${schema.label} · ${schema.dialect}`;
+    document.title = `${schema.label} — tablewalk`;
+    if (parsed?.stack.length) void resolveLabels(parsed.stack, (t) => findTable(t));
+  } catch (err) {
+    /* A dead end otherwise.
+    
+       A bookmarked link naming a connection that has since been removed used
+       to render this message and stop, on a page whose only way forward was
+       editing the URL by hand — while the database the session *is* connected
+       to sat there, loaded and unreachable. The fallback is made out loud
+       instead: say which link failed, then show the connection we do have.
+       Silently substituting it would be the other error, and the worse one. */
+    const said = el('p', {
+      class: 'note',
+      text: `${err.message} Showing ${state.schema?.label ?? 'the current database'} instead.`,
+    });
+    if (!state.schema) {
+      $('content').replaceChildren(said);
+      return;
+    }
+    state.stack = [];
+    state.page = 0;
+    allowSync();
+    state.navMode = 'replace';
+    render();
+    syncHash();
+    // Above the landing page rather than instead of it: the reason and the
+    // way forward want to be on screen together.
+    $('content').prepend(said);
+  }
+}
+
+async function boot() {
+  /* Captured before anything can render. The first paint calls syncHash and
+     would otherwise overwrite the incoming link with the empty state — the
+     deep link would be destroyed a few milliseconds before being read. */
+  /* The path, not the hash. A link written before these were paths still
+     arrives as `#/conn/...` — it is read here and rewritten to its path form
+     straight away, so the address bar agrees with what was restored and the
+     old spelling never reaches `syncHash` to be compared against. */
+  const legacy = window.location.hash;
+  const incoming = legacy.startsWith('#/') ? legacy.slice(1) : window.location.pathname;
+  if (legacy.startsWith('#/')) window.history.replaceState(null, '', incoming);
+
+  /* Before the first paint, so the page never flashes the wrong palette on
+     the way to the right one. */
+  initTheme();
+
+  setRenderer(paint);
+  setCrumbRenderer(() => {
+    const existing = $('content').querySelector('.crumbs');
+    if (existing) existing.replaceWith(breadcrumb());
+  });
+
+  try {
+    state.schema = await api('/api/schema');
+  } catch (err) {
+    /* A 409 here means there is no connection to read a schema *from*, which
+       is a screen rather than an error — and its message, "No connection is
+       open.", is true, unhelpful, and the last thing a first-time reader
+       should meet.
+    
+       Asked this way round rather than by checking the connection list first,
+       which is what this did: that put a second request in front of every
+       ordinary load to answer a question only the empty case ever asks. The
+       failure already carries the answer. */
+    if (err.status === 409) {
+      /* Unconditionally, and with whatever is listed. A 409 here means no
+         connection is *open* — which covers both an empty server and one
+         whose only connection failed to open. The second used to fall
+         through to "Could not read the schema: No connection is open.",
+         a true sentence with nothing to click. */
+      showWelcome(await listConnections());
+      return;
+    }
+    $('content').replaceChildren(el('p', { class: 'note', text: `Could not read the schema: ${err.message}` }));
+    return;
+  }
+  $('db-label').textContent = `${state.schema.label} · ${state.schema.dialect}`;
+  document.title = `${state.schema.label} — tablewalk`;
+  renderTableList();
+  initWriteMode();
+  initComplete();
+  initPalette();
+  initPeek();
+  /* Registered here rather than on a connection switch, which is where it
+     used to be — so on an ordinary boot nothing was listening, and a page
+     built in the builder did not appear in the menu or in ⌘K until the tab
+     was reloaded. The one place that runs on every start is this one. */
+  whenPagesChange(() => void registerPages());
+  initSidebarToggle();
+  initSql();
+  initUndo();
+  void refreshUndo();
+  /* Connections first, then the per-connection stores, then the first
+     render. The stores are keyed by connection id, and loading them before
+     `initConnections` has named one filed everything under a connection
+     called nothing — templates got away with it because every browser that
+     saved one also mirrored it locally under the right key; the pages file
+     restore was the first reader with no local copy to fall back on. */
+  await initConnections(() => renderTableList($('table-filter').value));
+  await loadTemplates();
+  await loadSavedPages();
+  await loadSavedSql();
+  /* After the saved-pages mirror is filled, or the menu and ⌘K are built
+     from an empty list and a page restored from the file is invisible until
+     something else rebuilds them. */
+  void registerPages();
+
+  /* A link present on load wins over the default view: someone arriving from
+     a pasted link should land where the link points, not on the schema.
+
+     The empty state is painted only when there is no link to honour. It used
+     to be painted unconditionally, first, which meant a deep link spent a
+     moment showing the *active* connection's landing page — and that paint
+     wrote its own address into the bar over the link that had not been read
+     yet. `allowSync` keeps the bar shut until this is done either way. */
+  const linked = Boolean(connectionFromHash(incoming));
+  if (!linked) render();
+
+  const restored = applyHash(incoming, {
+    findTableById: (id) => findTable(id) ?? state.schema.tables.find((t) => t.name === id),
+    selectConnection: switchAndRestore,
+  });
+  /* `'switching'` means applyHash handed off to an async connection switch.
+     That switch owns *both* the render and opening the address gate
+     (`switchAndRestore` calls `allowSync`), so the boot does neither here.
+     Opening the gate now would let any render that lands mid-switch — a
+     pages-change rebuild is the one that bit — write the OUTGOING connection
+     into the bar for a frame, which is the cold-tab `/demo` leak. */
+  if (restored !== 'switching') {
+    allowSync();
+    if (restored || linked) render();
+  }
+
+  /* Last, and after the first render: every stop measures an element that has
+     to exist, and the menu item it registers should sit below the ones the
+     features added rather than above them. */
+  initTour();
+
+  /* `popstate`, because the address is written with pushState and a path:
+     Back and Forward fire this, and a hash listener would never hear them
+     again. */
+  window.addEventListener('popstate', () => {
+    applyHash(window.location.pathname, {
+      findTableById: (id) => findTable(id) ?? state.schema.tables.find((t) => t.name === id),
+      selectConnection: switchAndRestore,
+    });
+  });
+
+  const filterInput = $('table-filter');
+  filterInput.addEventListener('input', (e) => renderTableList(e.target.value));
+
+  /* Filtering to one table and then having to reach for the mouse is the
+     kind of small friction that makes a tool feel unfinished. Typing narrows,
+     arrows choose, Enter opens — and with a single match, Enter alone is
+     enough. */
+  /* Bound on the whole sidebar rather than on the filter field.
+
+     Arrows only worked while the field had focus, so clicking a table and
+     then pressing Down scrolled the page instead of moving to the next
+     table — the list looked keyboard-navigable and was not, which is worse
+     than not offering it. */
+  document.querySelector('.sidebar').addEventListener('keydown', (e) => {
+    const buttons = sidebarButtons();
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      moveSidebar(1);
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      moveSidebar(-1);
+    } else if (e.key === 'ArrowRight' && e.target !== filterInput) {
+      /* Rightwards is where the table you highlighted is. The list chooses
+         what to show; the panel is where you then work, and reaching it
+         should not mean going back to the mouse. */
+      e.preventDefault();
+      focusContent();
+    } else if (e.key === 'Enter' && e.target === filterInput) {
+      e.preventDefault();
+      // No explicit highlight means "the obvious one": the only match, or
+      // the first of several.
+      const target = buttons[sidebarIndex >= 0 ? sidebarIndex : 0];
+      if (target) {
+        // Enter commits: a push, so the table you chose is a place you can
+        // come back to, unlike the ones you skimmed to reach it.
+        go(tableView(target.dataset.table, undefined, stickyTab()), 'reset');
+        filterInput.blur();
+      }
+    } else if (e.key === 'Escape' && e.target === filterInput) {
+      if (filterInput.value) {
+        // First Escape clears the filter, a second leaves the field. Clearing
+        // and blurring together loses the list you were about to pick from.
+        e.preventDefault();
+        e.stopPropagation();
+        filterInput.value = '';
+        renderTableList('');
+      } else {
+        filterInput.blur();
+      }
+    }
+  });
+
+  /* The schema diagram is reachable at any time, not only from the empty
+     state — it is how you re-orient after walking somewhere unfamiliar. */
+
+  $('search-button').addEventListener('click', openPalette);
+  /* The connection name is a link to the connections dialog. It is the only
+     way in when there is a single unconfigured database — the picker that
+     otherwise carries the gear is hidden in exactly that case. */
+  $('db-label').addEventListener('click', () => void openConnections());
+  // The wordmark is the one thing every web app makes a home link, and not
+  // doing it is a small surprise on every page.
+  $('home-button').addEventListener('click', goHome);
+
+  /**
+   * Run a line of the query language, from wherever it was written.
+   *
+   * The header's form and the ⌘/ modal both land here. Which endpoint answers
+   * a line is a decision with one home: a second copy in the modal would be
+   * the one that forgets about `by` the next time the language grows.
+   */
+  const runQueryText = (raw) => {
+    const text = String(raw ?? '').trim();
+    if (!text) return;
+    const tableName = text.split(/\s+/)[0];
+    const table = findTable(tableName) ?? state.schema.tables.find((t) => t.name === tableName);
+    /* `by` is the one keyword that changes which endpoint answers, so the
+       decision is made here rather than by letting the query parser fail on a
+       line it was never going to understand. That failure was the whole bug:
+       `invoice count, sum total as billed by status` came back as
+       `"billed" is not a column on invoice` — an error about a column nobody
+       claimed was one, with nothing to say that the thing being asked for
+       exists and has its own answer. */
+    const entry = looksLikeBreakdown(text)
+      ? breakdownView(table ? table.id : tableName, text)
+      : tableView(table ? table.id : tableName, text);
+    const top = currentEntry();
+    /* Refining the query you are already looking at replaces that crumb;
+       querying a different table is a fresh start, not a step in the walk. */
+    const sameTable = top && top.kind === entry.kind && top.table === entry.table;
+    go(entry, sameTable ? 'replace' : 'reset');
+  };
+
+  $('querybar').addEventListener('submit', (e) => {
+    e.preventDefault();
+    runQueryText($('query').value);
+  });
+
+  /**
+   * ⌘/ — the query bar with room to write in.
+   *
+   * Bound at the document with capture, the same way ⌘K is and for the same
+   * reason: it has to work from wherever the hands are, including from inside
+   * the header's bar. `/` still focuses that bar — it is documented and people
+   * use it — so this adds a surface rather than moving one.
+   */
+  document.addEventListener('keydown', (e) => {
+    if (e.key !== '/' || !(e.metaKey || e.ctrlKey)) return;
+    e.preventDefault();
+    openAsk({ initial: $('query').value, onRun: runQueryText });
+  }, true);
+
+  /* SQL stays in the header rather than going into the menu with the rest.
+
+     It is a state you leave on while you work — learning what the language
+     compiles to, or checking a query you are unsure of — not an action you
+     take once. A toggle you flip several times an hour does not belong two
+     clicks deep, and unlike the others it has to *show* whether it is on. */
+  const sqlToggle = $('sql-toggle');
+  sqlToggle.addEventListener('click', () => {
+    setExplaining(!explainVisible());
+    sqlToggle.setAttribute('aria-pressed', String(explainVisible()));
+  });
+  addMenuItem({
+    label: 'Schema',
+    detail: 'every table in this database',
+    onSelect: goHome,
+  });
+  /* Registers its own menu item, so it lands between Schema and Connections —
+     next to the other "what is this database" answer rather than at the end. */
+  initHelp();
+  addMenuItem({
+    /* Named rather than generic. "Undo" alone makes you remember what you did;
+       the label says it, so the decision does not need a memory. */
+    label: 'Undo the last edit',
+    // A function, so it describes the last edit rather than the state at boot.
+    detail: () => undoDescription() ?? 'nothing to undo',
+    onSelect: () => void undoLast().then(() => render()),
+  });
+  addMenuItem({
+    /* The palette has been in the stylesheet all along, reachable only by
+       changing your operating system. A function for the detail, so the menu
+       says what is in force rather than what was in force at boot. */
+    label: 'Theme',
+    detail: () => themeLabel(),
+    onSelect: () => { cycleTheme(); render(); },
+  });
+  addMenuItem({
+    /* The same surface the key opens. A shortcut nobody is told about is a
+       feature for whoever wrote it. */
+    label: 'Write a query…',
+    detail: 'the query bar, with room (⌘/)',
+    onSelect: () => openAsk({ initial: $('query').value, onRun: runQueryText }),
+  });
+  addMenuItem({
+    /* The question you have when a string arrives from somewhere else and
+       you cannot yet name the table it belongs to — which is the one search
+       every other search here cannot start. */
+    label: 'Find a value…',
+    detail: 'which table mentions this?',
+    /* Starting from the cell under the grid cursor when there is one: the
+       question nearly always arrives *while* looking at a value, and
+       retyping what is on screen is the tax this whole tool exists to
+       remove. `title` before `textContent`, because a shortened cell keeps
+       the whole value in its tooltip. */
+    onSelect: () => openFindValue(
+      document.querySelector('.cell-cursor')?.getAttribute('title')
+        ?? document.querySelector('.cell-cursor')?.textContent?.trim()
+        ?? '',
+    ),
+  });
+  addMenuItem({
+    /* The same question `lint` answers for an agent and `--lint` answers for
+       CI, asked by the person who can actually fix the unindexed key. */
+    label: 'Check the shape…',
+    detail: 'what this schema will cost',
+    onSelect: () => openShapeCheck(),
+  });
+  addMenuItem({
+    label: 'Agent console',
+    detail: 'drive the MCP tools by hand, see what an agent sees',
+    onSelect: () => openAgentConsole(),
+  });
+  addMenuItem({
+    label: 'Connections…',
+    detail: 'add, edit, save to a file',
+    onSelect: () => void openConnections(),
+  });
+  initMenu();
+
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape') $('query').blur();
+    const active = document.activeElement;
+    const typing = /input|textarea/i.test(active?.tagName ?? '')
+      || active?.getAttribute?.('contenteditable') === 'true';
+    /* And not while something is open over the page.
+    
+       These are single-key shortcuts on the document, so they fired through
+       any surface that did not stop them: Backspace with the focus on a
+       dialog's button walked the trail *behind* the modal, which then closed
+       onto a different record than the one it was opened from. A dialog is
+       modal by definition; the page under it is not taking keys. */
+    const covered = Boolean(
+      active?.closest?.('[role="dialog"], dialog[open], .pb, .help-panel, .palette, .conn-manager'),
+    );
+    if (covered) return;
+
+    // Backspace-as-back is a habit from file browsers, but only when the
+    // caret is not in a text field.
+    if (!typing && (e.key === 'Backspace' || (e.key === '[' && e.metaKey)) && state.stack.length > 1) {
+      e.preventDefault();
+      backTo(state.stack.length - 2);
+    }
+    if (e.key === '/' && !typing) {
+      e.preventDefault();
+      $('query').focus();
+    }
+    // `t` for tables, next to `/` for the query bar.
+    if (e.key === 'h' && !typing && !e.metaKey && !e.ctrlKey) {
+      e.preventDefault();
+      goHome();
+    }
+    if (e.key === 't' && !typing && !e.metaKey && !e.ctrlKey) {
+      e.preventDefault();
+      $('table-filter').focus();
+      $('table-filter').select();
+    }
+  });
+}
+
+void boot();