diff --git a/README.md b/README.md
index 657dc20..50fb28f 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,9 @@
 # Altinity SQL Browser
 
 An OAuth-gated **SQL browser for any ClickHouse cluster** — schema explorer,
-tabbed SQL editor with syntax highlighting, streaming results with table / JSON
-/ chart views, saved queries, history, and shareable links. It ships as a
+tabbed SQL editor with syntax highlighting, find/replace, bracket matching, and
+schema-aware autocomplete, streaming results with table / JSON / chart views,
+saved queries, history, and shareable links. It ships as a
 **single self-contained HTML file served from ClickHouse itself** (no Node
 server, no CDN, no external fonts) — the page makes **zero third-party
 requests** and renders in the OS's native UI font. Its only bundled runtime
@@ -27,6 +28,41 @@ The browser never holds a static credential — each user authenticates with you
 IdP and ClickHouse sees their JWT. There is **no app-specific backend**: the
 only moving parts are ClickHouse's HTTP handlers and your OAuth provider.
 
+## SQL editor
+
+The editor is a hand-rolled `<textarea>` over a syntax-highlighted `<pre>` (no
+editor library — it adds nothing to the single served file). On top of that:
+
+- **Find / replace** — `Cmd/Ctrl+F` opens a panel with a live match count,
+  prev/next (Enter / Shift+Enter), case / whole-word / regex toggles, and a
+  replace row. Matches highlight via a transparent overlay layered below the
+  syntax tokens, so highlighting and search never interfere.
+- **Bracket matching + auto-close** — typing `(` `[` or a quote inserts the
+  pair (or wraps the selection); typing a closer or quote steps over it;
+  Backspace inside an empty pair deletes both. The pair adjacent to the caret
+  is highlighted. (`{`/`}` auto-close is intentionally omitted.)
+- **Autocomplete** — typing a word (or after `table.`) opens a ranked dropdown
+  of keywords, functions, databases, tables, and already-loaded columns;
+  ↑/↓/Enter/Tab/Esc and click to accept; functions insert `name(`.
+- **Signature help + hover docs** — inside a function call, a popover shows the
+  signature with the active argument bolded; hovering a function or a
+  ClickHouse keyword shows its signature/description. Both read the same cached
+  reference data — `system.functions.{syntax,description}` (loaded with #25) and
+  a small built-in keyword-doc set — so they never query on the keystroke path.
+
+**The keystroke rule:** none of this runs SQL while you type. Reference data —
+the server's keyword and function lists — is fetched **once per connection**
+from `system.keywords` and `system.functions` (best-effort; it falls back to a
+built-in set on older ClickHouse), cached in memory, and merged with the
+in-memory schema. Highlighting then tracks the connected server's actual
+keyword/function set, so it's version-correct. Folding and multi-cursor are out
+of scope for a textarea and tracked separately (CodeMirror, issue #21).
+
+> Design source of truth: the handoff bundle under `design/` (imported from the
+> "Altinity Play" Claude Design project) — read `design/README.md` before UI
+> work. The `.jsx` files there are React prototypes; production is the vanilla
+> ES-module code under `src/`.
+
 ## Quick start (development)
 
 ```bash
@@ -197,16 +233,20 @@ Preview the rendered artifacts without touching ClickHouse:
 ```
 src/
   core/      pure logic — format, jwt, pkce, sql-highlight, share, sort,
-             stream, storage, chart-data (roles/autoChart/pivot + Chart.js
-             config builder; no DOM, no globals)
+             stream, storage, chart-data, and the editor logic: completions
+             (reference data + ranking), editor-search (find), editor-brackets
+             (match/auto-close), editor-marks (overlay), editor-geometry
+             (caret) — no DOM, no globals
   net/       oauth-config, oauth, ch-client (injected fetch seam)
-  ui/        dom (hyperscript), icons, + render modules (login, editor, tabs,
-             schema, results, saved-history, shortcuts, splitters, toast, app)
+  ui/        dom (hyperscript), icons, + render modules (login, editor +
+             editor-search/editor-complete, tabs, schema, results,
+             saved-history, shortcuts, splitters, toast, app)
   state.js   state model + pure operations
   main.js    bootstrap (OAuth callback, share-links, initial render)
   styles.css
 build/        esbuild → single-file dist/sql.html
 deploy/       install.sh, uninstall.sh, http_handlers.xml, config.json.example
+design/       imported design handoff bundle (UI spec; reference only, not built)
 tests/        vitest + happy-dom, one spec per module
 docs/         ARCHITECTURE.md, DEPLOYMENT.md, ASSET-DISTRIBUTION.md,
               CLICKHOUSE-OAUTH.md, CLICKHOUSE-OSS-OAUTH.md
diff --git a/design/Altinity Play.html b/design/Altinity Play.html
new file mode 100644
index 0000000..f069832
--- /dev/null
+++ b/design/Altinity Play.html	
@@ -0,0 +1,212 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Altinity Play — Redesigned</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+<style>
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; height: 100%; overflow: hidden; }
+  body {
+    font-family: 'Inter', -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+  #root { width: 100%; height: 100vh; }
+
+  :root {
+    --ui: 'Inter', -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+    --mono: 'JetBrains Mono', 'SF Mono', ui-monospace, Menlo, monospace;
+  }
+
+  /* DARK theme (default) */
+  [data-theme='dark'] {
+    --bg: #0E0E10;
+    --bg-header: #131316;
+    --bg-side: #131316;
+    --bg-tabs: #131316;
+    --bg-toolbar: #15151A;
+    --bg-editor: #0E0E10;
+    --bg-gutter: #131316;
+    --bg-table: #0E0E10;
+    --bg-th: #15151A;
+    --bg-input: #1A1A20;
+    --bg-chip: #1F1F26;
+    --bg-hover: rgba(255, 255, 255, .04);
+    --bg-highlight: rgba(255, 107, 53, .08);
+    --bg-modal: #1A1A20;
+    --fg: #E6E6E8;
+    --fg-mute: #A0A0A8;
+    --fg-faint: #6B6B74;
+    --num: #92E1D8;
+    --border: #1F1F26;
+    --border-faint: #1A1A20;
+  }
+
+  /* LIGHT theme */
+  [data-theme='light'] {
+    --bg: #FAFAFA;
+    --bg-header: #FFFFFF;
+    --bg-side: #F5F5F4;
+    --bg-tabs: #F5F5F4;
+    --bg-toolbar: #FAFAF9;
+    --bg-editor: #FFFFFF;
+    --bg-gutter: #FAFAF9;
+    --bg-table: #FFFFFF;
+    --bg-th: #F5F5F4;
+    --bg-input: #FFFFFF;
+    --bg-chip: #EEECE8;
+    --bg-hover: rgba(0, 0, 0, .04);
+    --bg-highlight: rgba(255, 107, 53, .12);
+    --bg-modal: #FFFFFF;
+    --fg: #1A1A1F;
+    --fg-mute: #57575E;
+    --fg-faint: #94949C;
+    --num: #0F766E;
+    --border: #E5E3DE;
+    --border-faint: #EEECE7;
+  }
+
+  /* SQL syntax */
+  .sql-keyword { color: #C586C0; font-weight: 500; }
+  [data-theme='light'] .sql-keyword { color: #AF00DB; }
+  .sql-func { color: #DCDCAA; }
+  [data-theme='light'] .sql-func { color: #795E26; }
+  .sql-string { color: #CE9178; }
+  [data-theme='light'] .sql-string { color: #A31515; }
+  .sql-number { color: #B5CEA8; }
+  [data-theme='light'] .sql-number { color: #098658; }
+  .sql-comment { color: #6A9955; font-style: italic; }
+  [data-theme='light'] .sql-comment { color: #008000; font-style: italic; }
+  .sql-ident { color: var(--fg); }
+  .sql-op { color: var(--fg-mute); }
+
+  /* Toolbar buttons */
+  .tb-btn {
+    height: 26px;
+    padding: 0 9px;
+    background: transparent;
+    color: var(--fg-mute);
+    border: 1px solid transparent;
+    border-radius: 5px;
+    font-size: 11.5px;
+    font-family: inherit;
+    cursor: pointer;
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    white-space: nowrap;
+    flex-shrink: 0;
+    transition: background .12s, color .12s;
+  }
+  .tb-btn:hover {
+    background: var(--bg-hover);
+    color: var(--fg);
+  }
+  .tb-select {
+    height: 26px;
+    padding: 0 22px 0 9px;
+    background-color: transparent;
+    background-repeat: no-repeat;
+    background-position: right 8px center;
+    color: var(--fg-mute);
+    border: 1px solid var(--border);
+    border-radius: 5px;
+    font-size: 11.5px;
+    font-family: inherit;
+    cursor: pointer;
+    white-space: nowrap;
+    flex-shrink: 0;
+    appearance: none;
+    -webkit-appearance: none;
+  }
+  [data-theme='dark'] .tb-select {
+    background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='8' height='5' viewBox='0 0 8 5'><path fill='%23A0A0A8' d='M0 0h8L4 5z'/></svg>");
+  }
+  [data-theme='light'] .tb-select {
+    background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='8' height='5' viewBox='0 0 8 5'><path fill='%2357575E' d='M0 0h8L4 5z'/></svg>");
+  }
+  .tb-select:hover { color: var(--fg); }
+
+  /* Header buttons */
+  .hd-btn {
+    width: 26px;
+    height: 26px;
+    border: none;
+    background: transparent;
+    color: var(--fg-mute);
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 5px;
+  }
+  .hd-btn:hover { background: var(--bg-hover); color: var(--fg); }
+
+  /* Row hover */
+  table.results tbody tr:hover td { background: var(--bg-hover); }
+  tr.row:hover td { background: var(--bg-hover); }
+
+  /* Scrollbars */
+  *::-webkit-scrollbar { width: 10px; height: 10px; }
+  *::-webkit-scrollbar-track { background: transparent; }
+  *::-webkit-scrollbar-thumb {
+    background: var(--border); border-radius: 5px;
+    border: 2px solid transparent; background-clip: content-box;
+  }
+  *::-webkit-scrollbar-thumb:hover { background: var(--fg-faint); background-clip: content-box; border: 2px solid transparent; }
+
+  /* Compact density tweaks */
+  [data-density='compact'] .qtabs { height: 28px; }
+
+  /* Query-running loader */
+  @keyframes twk-spin { to { transform: rotate(360deg); } }
+  .spin { animation: twk-spin .8s linear infinite; }
+  @keyframes twk-indet {
+    0% { left: -40%; }
+    100% { left: 100%; }
+  }
+  .indet { animation: twk-indet 1.1s ease-in-out infinite; }
+  @keyframes twk-runsweep {
+    0% { transform: translateX(-100%); }
+    100% { transform: translateX(350%); }
+  }
+  .runsweep { animation: twk-runsweep 1.1s ease-in-out infinite; }
+</style>
+</head>
+<body>
+<div id="root"></div>
+
+<script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+
+<script type="text/babel">
+const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
+  "theme": "dark",
+  "accent": "#3B82F6",
+  "density": "comfortable",
+  "sidebar": true,
+  "slowQuery": true
+}/*EDITMODE-END*/;
+window.TWEAK_DEFAULTS = TWEAK_DEFAULTS;
+</script>
+
+<script type="text/babel" src="tweaks-panel.jsx"></script>
+<script type="text/babel" src="data.jsx?v=6"></script>
+<script type="text/babel" src="editor-data.jsx?v=6"></script>
+<script type="text/babel" src="editor-search.jsx?v=6"></script>
+<script type="text/babel" src="editor-complete.jsx?v=7"></script>
+<script type="text/babel" src="sql-editor.jsx?v=7"></script>
+<script type="text/babel" src="components.jsx?v=6"></script>
+<script type="text/babel" src="app.jsx?v=6"></script>
+
+<script type="text/babel">
+  const root = ReactDOM.createRoot(document.getElementById('root'));
+  root.render(<App />);
+</script>
+</body>
+</html>
diff --git a/design/IMPORTED.md b/design/IMPORTED.md
new file mode 100644
index 0000000..38527e7
--- /dev/null
+++ b/design/IMPORTED.md
@@ -0,0 +1,14 @@
+# Design reference bundle (imported)
+
+This directory is a verbatim snapshot of the **"sql browser"** Claude Design
+project's `design_handoff_altinity_play/` handoff bundle — the UI source-of-truth
+for the editor-enhancement work (issues #23–#27).
+
+**Reference only — not shipped.** These are React/Babel prototypes. The production
+app is the zero-dependency vanilla-ES-module SPA under `src/`. esbuild bundles only
+`src/main.js` → `dist/sql.html`, so nothing here is built into the served artifact,
+and `tests/` coverage (`include: ['src/**/*.js']`) never sees it.
+
+Start with `README.md` (the full handoff: design tokens, region-by-region spec, and
+the per-issue editor-enhancement reference). The `.jsx` files are the reference
+implementations to port.
diff --git a/design/ISSUE-publish-as-markdown.md b/design/ISSUE-publish-as-markdown.md
new file mode 100644
index 0000000..e892fd7
--- /dev/null
+++ b/design/ISSUE-publish-as-markdown.md
@@ -0,0 +1,87 @@
+# Feature: "Publish" — export all saved queries as a Markdown cookbook
+
+## Summary
+
+Add a one-way **Markdown export** ("Publish" / "Copy as Markdown") that turns the
+user's saved queries into a single human-readable Markdown document they can paste
+into other tools (GitHub, GitLab, Notion, Obsidian, wikis, PRs, Slack) or download
+as a `.md` file.
+
+This complements — does **not** replace — the existing **JSON export/import**:
+
+| | JSON export | Markdown publish |
+|---|---|---|
+| Purpose | Backup / transfer / re-import | Share / document / paste elsewhere |
+| Round-trips back in? | ✅ lossless | ❌ one-way (metadata not recoverable) |
+| Human-readable | meh | ✅ great |
+
+**Markdown is strictly export-only.** Do not attempt to re-import it — `starred`,
+timestamps, and ids do not survive. JSON remains the canonical round-trip format.
+
+## Output format
+
+Each saved query becomes a heading + a fenced `sql` block (the fence gives free
+syntax highlighting wherever it's pasted). Group **starred first**, then the rest,
+and include a linked table of contents once there are more than ~10 queries
+(headings auto-anchor on GitHub).
+
+```markdown
+# Saved queries
+_42 queries · exported from Altinity SQL Browser · 2026-06-21_
+
+## ⭐ Starred
+
+### Worst-delay carriers (2023)
+​```sql
+SELECT Reporting_Airline, avg(DepDelayMinutes) AS avg_delay
+FROM airline.ontime
+WHERE Year = 2023 AND Cancelled = 0
+GROUP BY Reporting_Airline
+ORDER BY avg_delay DESC
+LIMIT 15
+​```
+
+## All queries
+
+### Busiest origin airports
+​```sql
+SELECT Origin, count() AS flights FROM airline.ontime ...
+​```
+```
+
+## UX
+
+- Primary action: **Copy to clipboard** (the stated use case is "cut it and use
+  elsewhere").
+- Secondary: **Download `.md`**.
+- Show a **preview modal** with the generated Markdown in a scrollable `<pre>` so
+  the user can eyeball it before copying — Markdown is reviewed-before-paste,
+  unlike the fire-and-forget JSON backup.
+- Sits alongside the existing Export / Import controls at the bottom of the Saved
+  panel.
+
+## Open decisions
+
+1. **Scope** — publish *all* saved queries, or let the user pick (starred-only, or
+   multi-select)?
+2. **Naming** — "Copy as Markdown" (honest about what it does) vs keep "Publish"
+   and eventually make it *actually* publish (create a GitHub Gist or a shareable
+   read-only URL, with copy/download as offline fallbacks).
+3. **`description` field (recommended)** — saved queries are currently `name` +
+   `sql` only. A published cookbook is far more useful if each query carries a
+   one-line description, rendered as prose under its heading. Consider adding an
+   optional `description` field to the saved-query schema as part of this work.
+
+## Implementation notes
+
+- **Fence safety**: SQL almost never contains a literal triple-backtick, but scan
+  each query and bump to a 4-backtick fence if one is present.
+- Clipboard via `navigator.clipboard.writeText`; download via
+  `Blob` + `URL.createObjectURL` (same pattern as the JSON export).
+- Suggested filename: `sql-browser-queries-YYYY-MM-DD.md`.
+
+## Context
+
+Discussed during the design handoff. Deferred from the current design round for
+more thought before committing. See the handoff README's "Export / Import saved
+queries" section for the JSON counterpart this builds on.
diff --git a/design/Login.html b/design/Login.html
new file mode 100644
index 0000000..2433d46
--- /dev/null
+++ b/design/Login.html
@@ -0,0 +1,304 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Altinity SQL Browser — Sign in</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+<style>
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; height: 100%; }
+  body {
+    font-family: 'Inter', -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+  #root { width: 100%; min-height: 100vh; }
+
+  :root {
+    --ui: 'Inter', -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+    --mono: 'JetBrains Mono', 'SF Mono', ui-monospace, Menlo, monospace;
+  }
+
+  [data-theme='dark'] {
+    --bg: #0E0E10;
+    --bg-2: #131316;
+    --bg-card: #15151A;
+    --bg-input: #0E0E10;
+    --bg-chip: #1F1F26;
+    --bg-hover: rgba(255,255,255,.05);
+    --fg: #E6E6E8;
+    --fg-mute: #A0A0A8;
+    --fg-faint: #6B6B74;
+    --border: #26262E;
+    --border-faint: #1C1C22;
+    --shadow: 0 24px 70px rgba(0,0,0,.55);
+  }
+  [data-theme='light'] {
+    --bg: #F4F3F0;
+    --bg-2: #FFFFFF;
+    --bg-card: #FFFFFF;
+    --bg-input: #FFFFFF;
+    --bg-chip: #EEECE8;
+    --bg-hover: rgba(0,0,0,.04);
+    --fg: #1A1A1F;
+    --fg-mute: #57575E;
+    --fg-faint: #94949C;
+    --border: #E2E0DA;
+    --border-faint: #EDEBE6;
+    --shadow: 0 24px 70px rgba(40,30,20,.14);
+  }
+
+  .fld {
+    width: 100%; height: 38px; padding: 0 11px;
+    background: var(--bg-input); border: 1px solid var(--border);
+    border-radius: 8px; color: var(--fg); font-size: 13px; outline: none;
+    font-family: var(--ui); transition: border-color .12s, box-shadow .12s;
+  }
+  .fld::placeholder { color: var(--fg-faint); }
+  .fld:focus { border-color: var(--accent); box-shadow: 0 0 0 3px color-mix(in oklab, var(--accent) 22%, transparent); }
+  .fld.mono { font-family: var(--mono); font-size: 12.5px; }
+
+  .btn {
+    width: 100%; height: 42px; border-radius: 9px; border: 1px solid transparent;
+    font-family: var(--ui); font-size: 13.5px; font-weight: 600; cursor: pointer;
+    display: flex; align-items: center; justify-content: center; gap: 9px;
+    transition: background .14s, border-color .14s, opacity .14s, transform .04s;
+  }
+  .btn:active { transform: translateY(1px); }
+  .btn-primary { background: var(--accent); color: #fff; }
+  .btn-primary:hover { background: color-mix(in oklab, var(--accent) 88%, #000); }
+  .btn-ghost { background: transparent; color: var(--fg); border-color: var(--border); }
+  .btn-ghost:hover { background: var(--bg-hover); }
+  .btn:disabled { opacity: .45; cursor: not-allowed; }
+  .btn:disabled:active { transform: none; }
+
+  .icon-btn {
+    position: absolute; right: 6px; top: 50%; transform: translateY(-50%);
+    width: 28px; height: 28px; border: none; background: transparent;
+    color: var(--fg-faint); cursor: pointer; border-radius: 6px;
+    display: flex; align-items: center; justify-content: center;
+  }
+  .icon-btn:hover { background: var(--bg-hover); color: var(--fg-mute); }
+
+  .lbl { font-size: 11.5px; font-weight: 500; color: var(--fg-mute); display: block; margin-bottom: 6px; }
+  .disc {
+    appearance: none; background: transparent; border: none; cursor: pointer;
+    color: var(--fg-mute); font-family: var(--ui); font-size: 12px; font-weight: 500;
+    display: flex; align-items: center; gap: 6px; padding: 4px 0;
+  }
+  .disc:hover { color: var(--fg); }
+  a { color: var(--accent); text-decoration: none; }
+  a:hover { text-decoration: underline; }
+
+  *::-webkit-scrollbar { width: 10px; height: 10px; }
+  *::-webkit-scrollbar-thumb { background: var(--border); border-radius: 5px; border: 2px solid transparent; background-clip: content-box; }
+</style>
+</head>
+<body>
+<div id="root"></div>
+
+<script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+
+<script type="text/babel">
+const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
+  "theme": "dark",
+  "accent": "#3B82F6"
+}/*EDITMODE-END*/;
+window.TWEAK_DEFAULTS = TWEAK_DEFAULTS;
+</script>
+
+<script type="text/babel" src="tweaks-panel.jsx"></script>
+
+<script type="text/babel">
+const { useState } = React;
+
+// The server currently serving this page (where SSO is configured).
+const CURRENT_HOST = 'otel.demo.altinity.cloud';
+
+const I = {
+  shield: (p={}) => <svg width="17" height="17" viewBox="0 0 18 18" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" {...p}><path d="M9 1.5l6 2.2v4.1c0 3.6-2.5 6.6-6 7.7-3.5-1.1-6-4.1-6-7.7V3.7z"/><path d="M6.4 9l1.9 1.9 3.4-3.6"/></svg>,
+  eye: (p={}) => <svg width="15" height="15" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" {...p}><path d="M1.5 8S4 3.5 8 3.5 14.5 8 14.5 8 12 12.5 8 12.5 1.5 8 1.5 8z"/><circle cx="8" cy="8" r="2"/></svg>,
+  eyeOff: (p={}) => <svg width="15" height="15" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" {...p}><path d="M6.2 3.7A6.6 6.6 0 0 1 8 3.5C12 3.5 14.5 8 14.5 8a11 11 0 0 1-2 2.4M9.8 9.8A2 2 0 0 1 6.2 6.2M1.5 8S4 3.5 8 3.5m-6.5 4.5a11 11 0 0 0 2 2.4M2 2l12 12"/></svg>,
+  chev: (p={}) => <svg width="11" height="11" viewBox="0 0 11 11" fill="none" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round" {...p}><path d="M2 4l3.5 3.5L9 4"/></svg>,
+  server: (p={}) => <svg width="12" height="12" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" {...p}><rect x="2" y="2" width="10" height="4" rx="1"/><rect x="2" y="8" width="10" height="4" rx="1"/><path d="M4.5 4h.01M4.5 10h.01"/></svg>,
+  arrow: (p={}) => <svg width="13" height="13" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round" {...p}><path d="M2.5 7h9M8 3.5L11.5 7 8 10.5"/></svg>,
+  github: (p={}) => <svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor" {...p}><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82a7.5 7.5 0 0 1 4 0c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg>,
+};
+
+function Field({ label, type='text', value, onChange, placeholder, mono, autoFocus, right, onKeyDown }) {
+  return (
+    <div>
+      {label && <label className="lbl">{label}</label>}
+      <div style={{ position: 'relative' }}>
+        <input className={'fld' + (mono ? ' mono' : '')} type={type} value={value}
+          onChange={(e) => onChange(e.target.value)} placeholder={placeholder}
+          autoFocus={autoFocus} onKeyDown={onKeyDown} spellCheck={false}
+          autoComplete="off" style={right ? { paddingRight: 38 } : undefined} />
+        {right}
+      </div>
+    </div>
+  );
+}
+
+function Login() {
+  const [t, setTweak] = useTweaks(TWEAK_DEFAULTS);
+  const [username, setUsername] = useState('');
+  const [password, setPassword] = useState('');
+  const [showPw, setShowPw] = useState(false);
+  const [host, setHost] = useState('');
+  const [advOpen, setAdvOpen] = useState(false);
+  const [busy, setBusy] = useState(null); // 'sso' | 'creds' | null
+
+  const hasCreds = username.trim().length > 0 && password.length > 0;
+  const hostOverride = host.trim();
+  const effectiveHost = hostOverride || CURRENT_HOST;
+
+  const go = (mode) => {
+    setBusy(mode);
+    setTimeout(() => setBusy(null), 1600); // demo only
+  };
+  const onCredsKey = (e) => { if (e.key === 'Enter' && hasCreds) go('creds'); };
+
+  return (
+    <div data-theme={t.theme} style={{
+      '--accent': t.accent,
+      minHeight: '100vh', width: '100%', background: 'var(--bg)', color: 'var(--fg)',
+      fontFamily: 'var(--ui)', display: 'flex', alignItems: 'center', justifyContent: 'center',
+      padding: 24, position: 'relative', overflow: 'hidden',
+    }}>
+      {/* subtle backdrop */}
+      <div style={{ position: 'absolute', inset: 0, pointerEvents: 'none',
+        background: 'radial-gradient(700px 380px at 50% -8%, color-mix(in oklab, var(--accent) 13%, transparent), transparent 70%)' }} />
+
+      <div style={{
+        position: 'relative', width: 400, maxWidth: '100%', background: 'var(--bg-card)',
+        border: '1px solid var(--border)', borderRadius: 16, boxShadow: 'var(--shadow)',
+        padding: '30px 30px 22px',
+      }}>
+        {/* Brand */}
+        <div style={{ display: 'flex', alignItems: 'center', gap: 10, marginBottom: 22 }}>
+          <div style={{ width: 30, height: 30, borderRadius: 8,
+            background: 'linear-gradient(135deg, var(--accent), color-mix(in oklab, var(--accent) 62%, #000))',
+            display: 'flex', alignItems: 'center', justifyContent: 'center',
+            color: '#fff', fontWeight: 700, fontSize: 15 }}>A</div>
+          <div style={{ display: 'flex', flexDirection: 'column', lineHeight: 1.2 }}>
+            <span style={{ fontSize: 14, fontWeight: 600 }}>Altinity SQL Browser</span>
+            <span style={{ fontSize: 11, color: 'var(--fg-faint)', fontFamily: 'var(--mono)' }}>ClickHouse query console</span>
+          </div>
+        </div>
+
+        <div style={{ fontSize: 19, fontWeight: 600, letterSpacing: -.3, marginBottom: 4 }}>Sign in</div>
+        <div style={{ fontSize: 12.5, color: 'var(--fg-mute)', marginBottom: 20, lineHeight: 1.5 }}>
+          Use single sign-on for this server, or connect with ClickHouse credentials.
+        </div>
+
+        {/* SSO */}
+        <button className={'btn ' + (hasCreds ? 'btn-ghost' : 'btn-primary')}
+          onClick={() => go('sso')} disabled={!!busy}>
+          {I.shield()} {busy === 'sso' ? 'Redirecting…' : 'Continue with SSO'}
+        </button>
+        <div style={{ fontSize: 11, color: 'var(--fg-faint)', marginTop: 7, display: 'flex', alignItems: 'center', gap: 5, justifyContent: 'center' }}>
+          {I.server()} Authenticates on <span style={{ color: 'var(--fg-mute)', fontFamily: 'var(--mono)' }}>{CURRENT_HOST}</span>
+        </div>
+
+        {/* divider */}
+        <div style={{ display: 'flex', alignItems: 'center', gap: 12, margin: '18px 0' }}>
+          <div style={{ flex: 1, height: 1, background: 'var(--border-faint)' }} />
+          <span style={{ fontSize: 10.5, color: 'var(--fg-faint)', textTransform: 'uppercase', letterSpacing: '.07em' }}>or use credentials</span>
+          <div style={{ flex: 1, height: 1, background: 'var(--border-faint)' }} />
+        </div>
+
+        {/* Credentials */}
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 13 }}>
+          <Field label="Username" value={username} onChange={setUsername}
+            placeholder="default" mono onKeyDown={onCredsKey} />
+          <Field label="Password" value={password} onChange={setPassword}
+            type={showPw ? 'text' : 'password'} placeholder="••••••••" mono onKeyDown={onCredsKey}
+            right={<button className="icon-btn" onClick={() => setShowPw(s => !s)}
+              tabIndex={-1} title={showPw ? 'Hide' : 'Show'}>{showPw ? I.eyeOff() : I.eye()}</button>} />
+        </div>
+
+        {/* Advanced: host override */}
+        <div style={{ marginTop: 12 }}>
+          <button className="disc" onClick={() => setAdvOpen(o => !o)}>
+            <span style={{ display: 'flex', transform: advOpen ? 'rotate(0deg)' : 'rotate(-90deg)', transition: 'transform .15s' }}>{I.chev()}</span>
+            Advanced — connect to another server
+          </button>
+          {advOpen && (
+            <div style={{ marginTop: 10 }}>
+              <Field label="Server address (host:port)" value={host} onChange={setHost}
+                placeholder={CURRENT_HOST + ':8443'} mono onKeyDown={onCredsKey} />
+              <div style={{ fontSize: 11, color: 'var(--fg-faint)', marginTop: 6, lineHeight: 1.5 }}>
+                Leave blank to use this server. A custom host applies to credential
+                sign-in only — SSO always authenticates on <span style={{ fontFamily: 'var(--mono)' }}>{CURRENT_HOST}</span>.
+              </div>
+            </div>
+          )}
+        </div>
+
+        {/* Connect with credentials */}
+        <button className={'btn ' + (hasCreds ? 'btn-primary' : 'btn-ghost')}
+          style={{ marginTop: 16 }}
+          onClick={() => go('creds')} disabled={!hasCreds || !!busy}>
+          {busy === 'creds' ? 'Connecting…' : <>Connect{I.arrow()}</>}
+        </button>
+
+        {/* Live target summary */}
+        <div style={{
+          marginTop: 14, padding: '9px 11px', background: 'var(--bg-input)',
+          border: '1px solid var(--border-faint)', borderRadius: 8,
+          fontSize: 11, color: 'var(--fg-mute)', fontFamily: 'var(--mono)',
+          display: 'flex', alignItems: 'center', gap: 7, lineHeight: 1.4,
+        }}>
+          <span style={{ width: 6, height: 6, borderRadius: 3, background: '#22c55e',
+            boxShadow: '0 0 6px #22c55e', flexShrink: 0 }} />
+          <span style={{ color: 'var(--fg-faint)' }}>Target</span>
+          <span style={{ color: 'var(--fg)', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+            {effectiveHost}
+          </span>
+          <span style={{ flex: 1 }} />
+          <span style={{ color: 'var(--fg-faint)' }}>
+            {hasCreds ? `as ${username.trim()}` : 'via SSO'}
+          </span>
+        </div>
+
+        {/* Footer */}
+        <div style={{ marginTop: 20, paddingTop: 16, borderTop: '1px solid var(--border-faint)',
+          display: 'flex', alignItems: 'center', justifyContent: 'space-between',
+          fontSize: 11, color: 'var(--fg-faint)' }}>
+          <a href="https://github.com/Altinity/altinity-sql-browser" target="_blank" rel="noopener noreferrer"
+            style={{ color: 'var(--fg-mute)', display: 'flex', alignItems: 'center', gap: 5 }}>
+            {I.github()} Source
+          </a>
+          <span style={{ fontFamily: 'var(--mono)' }}>ClickHouse 26.3.10</span>
+        </div>
+      </div>
+
+      <TweaksPanel title="Tweaks">
+        <TweakSection label="Theme">
+          <TweakRadio label="Mode" value={t.theme} options={['dark', 'light']}
+            onChange={(v) => setTweak('theme', v)} />
+          <TweakColor label="Accent" value={t.accent} onChange={(v) => setTweak('accent', v)} />
+          <div style={{ display: 'flex', gap: 6, padding: '2px 0' }}>
+            {['#3B82F6', '#FF6B35', '#10B981', '#F0A500', '#EC4899'].map(c => (
+              <button key={c} onClick={() => setTweak('accent', c)}
+                style={{ flex: 1, height: 22, border: 'none', background: c, borderRadius: 4,
+                  cursor: 'pointer', outline: t.accent === c ? '2px solid rgba(125,125,125,.7)' : 'none', outlineOffset: 1 }}
+                title={c} />
+            ))}
+          </div>
+        </TweakSection>
+      </TweaksPanel>
+    </div>
+  );
+}
+
+ReactDOM.createRoot(document.getElementById('root')).render(<Login />);
+</script>
+</body>
+</html>
diff --git a/design/README.md b/design/README.md
new file mode 100644
index 0000000..6747051
--- /dev/null
+++ b/design/README.md
@@ -0,0 +1,1006 @@
+# Handoff: Altinity Play — Redesigned Query Workbench
+
+## Overview
+
+This is a redesign of the Altinity Antalya `/play-a` page (the ClickHouse-flavored
+SQL playground at `https://antalya.demo.altinity.cloud/play-a`). The original
+page is essentially a single textarea + Run button + results table. This redesign
+turns it into a modern data workbench in the spirit of DataGrip / Postgres.app /
+Linear — schema-first, multi-tab, with polished results, charts, and history.
+
+The primary user is a **ClickHouse newcomer exploring the public demo data**;
+the experience should feel approachable but still pro-grade.
+
+---
+
+## About the Design Files
+
+The files in this bundle are **design references**. They are working HTML
+prototypes built with React + Babel inline transpilation, intended to demonstrate
+the intended **look, layout, behavior, and interactions** — not to be shipped as
+production code.
+
+**Your task is to recreate these designs in the target codebase's existing
+environment** (the live `/play-a` app, presumably a React/Vue/Svelte SPA served
+by ClickHouse + Altinity infra), using its established patterns, component
+library, routing, styling solution, and data layer. If the project has no
+existing frontend stack yet, choose the most appropriate framework — React +
+Vite + TypeScript is a reasonable default — and implement there.
+
+When you start, please:
+
+1. Open `Altinity Play.html` in a browser to see the design live.
+2. Read this README in full.
+3. Skim the `.jsx` files for the exact structure, props, and interaction logic
+   you'll need to mirror.
+4. Identify the equivalent components/primitives in the target codebase before
+   re-implementing from scratch.
+
+---
+
+## Fidelity
+
+**High-fidelity.** All colors, typography, spacing, border radii, and
+interactions are intentional and final. Recreate pixel-perfectly using the
+codebase's existing libraries and patterns. Do not substitute "close enough"
+values for the design tokens listed below.
+
+The one exception: the syntax-highlighted SQL editor in the prototype is
+hand-rolled (transparent textarea over a styled `<pre>` for highlighting). In
+production, **swap this for Monaco Editor or CodeMirror 6** — it's expected
+behavior, not a stylistic choice. Match the visual treatment (line gutter
+style, font, line height, color palette) to what the prototype shows.
+
+---
+
+## Screen: Sign in (`Login.html`)
+
+The connection/login screen shown before the workbench. Three auth paths,
+encoded directly in the UI. Centered 400px card on the app's dark bg
+(`radial` accent glow behind it), same tokens/fonts as the workbench.
+
+**The rules (this is the important part):**
+1. **SSO is the default.** A primary "Continue with SSO" button authenticates
+   on **the current host** (the server serving the page —
+   `CURRENT_HOST`, e.g. `otel.demo.altinity.cloud`). OAuth is configured
+   per-deployment, so SSO is always bound to the current host — it does **not**
+   honor the host override. Helper text states this.
+2. **Credentials override SSO.** When username **and** password are both
+   non-empty, the UI flips: **Connect** becomes the primary (accent) button and
+   SSO demotes to a secondary (`btn-ghost`) outline — visually encoding "these
+   are used instead of SSO." Enter submits; password has a show/hide toggle.
+3. **Optional host:port override.** Under an **Advanced** disclosure (collapsed
+   by default so the common SSO path stays clean): a single "Server address
+   (host:port)" field. Blank → use the current host. A value → connect there
+   **for the credential path only** (per rule 1, SSO ignores it).
+
+**Live target summary**: a mono status row pinned near the bottom always
+resolves the combined state — `Target: <effectiveHost>` on the left, and
+`as <username>` (credential path) or `via SSO` on the right — so the
+interaction of the three rules is never ambiguous. `effectiveHost =
+hostOverride.trim() || CURRENT_HOST`.
+
+**State / logic** (all local in the prototype):
+- `hasCreds = username.trim() && password` → drives the primary/secondary swap
+  and enables the Connect button.
+- `effectiveHost` as above.
+- `busy` ∈ {`'sso'`,`'creds'`,null} → button label becomes "Redirecting…" /
+  "Connecting…". The prototype just times out after 1.6s; **wire to the real
+  OAuth redirect / ClickHouse auth in production.**
+
+**Production wiring:**
+- **SSO** → kick off the existing OAuth flow against the current origin
+  (the same one used today at `/sql`).
+- **Credentials** → authenticate against ClickHouse at `effectiveHost`
+  (HTTP interface; `Authorization: Basic` or `X-ClickHouse-User` /
+  `X-ClickHouse-Key`). Validate host:port input; default the port if omitted
+  (8443 https / 9440 native-secure as appropriate).
+- Treat host override as untrusted input; constrain scheme/port as your
+  security model requires.
+- On success, hand off to the workbench (`Altinity Play.html` equivalent) with
+  the resolved connection in context.
+
+**Footer**: GitHub "Source" link + version chip, matching the workbench header.
+**Tweaks**: theme + accent (same as the workbench), so the login matches
+whatever palette the app ships with.
+
+---
+
+## Layout / Screens
+
+There is one main screen — the workbench — composed of four regions:
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│ HEADER (44px)                                                        │
+├────────────────┬─────────────────────────────────────────────────────┤
+│                │ TABS (34px)                                         │
+│   SIDEBAR      ├─────────────────────────────────────────────────────┤
+│   (resizable,  │ EDITOR TOOLBAR (38px)                               │
+│   180–420px,   ├─────────────────────────────────────────────────────┤
+│   default 248) │                                                     │
+│                │ SQL EDITOR  (top half, default 45%)                 │
+│   • Schema     │                                                     │
+│   • Saved/Hist ├──────── 4px draggable splitter ─────────────────────┤
+│   (vertical    │ RESULTS TOOLBAR (36px)                              │
+│   split, 60/40)├─────────────────────────────────────────────────────┤
+│                │ RESULTS PANE                                        │
+│                │ (table / chart / json view toggle)                  │
+└────────────────┴─────────────────────────────────────────────────────┘
+                              ⇣
+                  Floating Tweaks panel (dev tool;
+                  not shipped to end users)
+```
+
+Editor-first split: the editor gets 45% of vertical space by default; the
+horizontal splitter between editor and results is draggable (15–85%).
+
+---
+
+## Region 1: Header (44px tall)
+
+Background: `--bg-header`. Bottom border: 1px `--border`.
+Padding: `0 14px`. Flex row, 14px gap.
+
+**Left cluster:**
+- **Logo tile**: 22×22, `border-radius: 5`, gradient `linear-gradient(135deg,
+  var(--accent), color-mix(in oklab, var(--accent) 70%, #000))`. White "A" inside,
+  font-weight 700, 12px.
+- **Wordmark**: "Altinity Play", 13px / 600 / `--fg`.
+- **Connection chip**: `antalya.demo` in mono font, 11px / `--fg-faint`,
+  `--bg-chip` background, padding `2px 6px`, radius 4. `white-space: nowrap`.
+
+**Spacer (`flex: 1`)**
+
+**Right cluster:** (`flex-shrink: 0`, `white-space: nowrap`)
+- **Live status**: 7×7 green dot (`#22c55e`) with `box-shadow: 0 0 6px #22c55e`,
+  followed by mono text "ClickHouse 26.3.10" at 11.5px / `--fg-mute`.
+- **GitHub link** (`<a>`, github glyph): 26×26, transparent, hover `--bg-hover`.
+  `target="_blank" rel="noopener noreferrer"`, `aria-label`/title "View on GitHub".
+- **Shortcuts button** (`?` icon): 26×26, transparent, hover `--bg-hover`.
+- **User menu**: avatar chip (24×24, radius 12, `--bg-chip`, initials "DM") +
+  chevron, wrapped in a button. Click opens a dropdown (width 230) with:
+  identity header (accent-filled 32px avatar, name, email), a role line
+  ("Read-only · demo", mono, `--fg-faint`), and a red **Log out** item
+  (`#ef4444`, `Icon.logout`). Clicking Log out opens a **confirmation dialog**
+  (340px, centered, blurred backdrop) explaining that unsaved tabs stay in the
+  browser and saved queries are kept, with Cancel / Log out (red) buttons.
+  An invisible full-viewport overlay behind the dropdown closes it on outside
+  click.
+
+---
+
+## Region 2: Sidebar (resizable, default 248px wide, min 180, max 420)
+
+Background: `--bg-side`. Right border 1px `--border`. Vertical split into:
+
+### 2a. Schema browser (top, ~60% height)
+
+- **Search field**: 26px tall input with magnifier icon at left (12px, 8px from
+  left edge). Placeholder "Search tables, columns…", 11.5px. `--bg-input`
+  background, 1px `--border`, radius 5. Filters tree live.
+- **Tree** (4px vertical padding, scrollable):
+  - **Database row** (24px tall, 10px left padding + 14px per indent level):
+    - Chevron (right when collapsed, down when expanded) at left.
+    - Database icon, `--fg-mute`.
+    - Name, 12px / 600 / `--fg`.
+    - Child count, 10px mono / `--fg-faint`, right-aligned.
+  - **Table row** (24px tall, indent 1):
+    - Chevron if has columns.
+    - Table icon in `--accent` color.
+    - Name, 12px / 400 / `--fg-mute`.
+    - Row count (e.g. "198.3M"), 10px mono / `--fg-faint`.
+  - **Column row** (22px tall, indent 2):
+    - Column icon, `--fg-faint`.
+    - Name, 11px mono / `--fg-mute`. Click to insert into editor.
+    - Type badge (e.g. "UInt16"), 10px mono / `--fg-faint`.
+- Hover: `--bg-hover` background.
+- Search-match highlight: `--bg-highlight` (translucent accent).
+
+### 2b. Vertical resize handle (6px, `--border`, `cursor: row-resize`)
+
+### 2c. Saved / History panel (bottom, ~40% height)
+
+- **Tabs row** (30px): "★ Saved" and "⏱ History", each `flex: 1`, no border,
+  underline 2px in `--accent` on active. 11.5px / 500.
+- **Saved item**:
+  - Padding `8px 10px`, 1px `--border-faint` bottom.
+  - Star icon (filled if `starred`, in `--accent`); fallback `--fg-faint`.
+  - Name, 12px / 500 / `--fg`, single line + ellipsis.
+  - Below: SQL preview (first line), 10.5px mono / `--fg-faint`, 18px left
+    indent, single line + ellipsis.
+  - Click → opens as new tab.
+- **History item**:
+  - Padding `8px 10px`, 1px `--border-faint` bottom.
+  - SQL preview, 11px mono / `--fg`, single line + ellipsis.
+  - Below: meta row, 10px mono / `--fg-faint`, 10px gap: relative time, row
+    count, ms.
+  - Click → re-run as new tab.
+
+---
+
+## Region 3: Tabs row (34px)
+
+Background: `--bg-tabs`. Bottom 1px `--border`.
+
+- Each tab: 100px min-width, padding `0 8px 0 12px`, right border 1px.
+- Active tab: background `--bg-editor`, name 11.5px / 500 / `--fg`, **2px top
+  bar in `--accent`** (absolutely positioned).
+- Inactive tab: `--fg-mute`, 400 weight.
+- Tab name + (if dirty) 5px gray dot + (if multi) 16×16 close × button.
+- **+ button** at far right: 32px wide, 1px left border, plus icon centered,
+  `--fg-mute` → `--fg` on hover. ⌘T also creates new tab.
+
+---
+
+## Region 4: Editor toolbar (38px)
+
+Background: `--bg-toolbar`. Bottom 1px `--border`. `0 10px` padding, 8px gap.
+
+- **Run button**:
+  - 26px tall, padding `0 10px 0 8px`.
+  - Background: `--accent`, color: white.
+  - 11.5px / 600. Radius 5.
+  - Icon (play triangle) + "Run" + small `⌘↵` kbd inside (rgba(0,0,0,.2) bg,
+    9.5px mono).
+  - Disabled (running) state: opacity 0.7, label "Running…", cursor wait.
+- **Format button**: tb-btn class — transparent, `--fg-mute` → `--fg` on hover,
+  `--bg-hover`. Has `{ }` mono glyph + "Format". `white-space: nowrap`.
+- **Spacer**
+- **Share button**: tb-btn, share-graph icon + "Share".
+- **Format select**: dropdown for output format (TSV/CSV/JSON/Pretty), 1px
+  `--border` outline, custom chevron SVG.
+
+---
+
+## Region 5: SQL Editor
+
+- Mono font: `'JetBrains Mono', 'SF Mono', ui-monospace, monospace`. 13px (12.5px
+  in compact density). Line-height 1.7 (1.5 compact). Padding `12px 14px` (8px
+  vertical in compact).
+- Background: `--bg-editor`. Caret color: `--accent`.
+- **Line gutter**: 44px wide, right-aligned, padding `padY 8px padY 0`. Text
+  `--fg-faint`, mono, tabular-nums. Right border 1px `--border`. Background
+  `--bg-gutter`. Scrolls in lockstep with the editor.
+- **Tab key** inserts 2 spaces. (When swapping in Monaco/CodeMirror, this is
+  handled natively.)
+
+### SQL syntax highlight palette
+
+| Token   | Dark         | Light      |
+|---------|--------------|------------|
+| keyword | `#C586C0` 500| `#AF00DB`  |
+| func    | `#DCDCAA`    | `#795E26`  |
+| string  | `#CE9178`    | `#A31515`  |
+| number  | `#B5CEA8`    | `#098658`  |
+| comment | `#6A9955` italic | `#008000` italic |
+| ident   | `--fg`       | `--fg`     |
+| op      | `--fg-mute`  | `--fg-mute`|
+
+Keyword and function lists are in `sql-editor.jsx` (`SQL_KEYWORDS`, `SQL_FUNCS`)
+— they include the ClickHouse-flavored set (e.g. `PREWHERE`, `FINAL`,
+`toStartOfMonth`, `LowCardinality`, etc.).
+
+### 5b. Editor enhancements (issues #23–#27)
+
+Reference designs for the editor-enhancement track, all built on the existing
+**textarea-over-`<pre>`** surface (no editor library). Files: `editor-data.jsx`
+(reference data), `editor-search.jsx` (#23), `editor-complete.jsx` (#26/#27),
+and the rewired `sql-editor.jsx`. The prototype implementations are the visual
+spec; production keeps the same UX but sources data from ClickHouse system
+tables (see #25).
+
+**The keystroke rule (load-bearing):** none of these run SQL on the keystroke
+path. Autocomplete/hover/signature all read **in-memory reference data** fetched
+once per connection. Honor this in production.
+
+#### #23 — Find / replace (`editor-search.jsx`, `SearchPanel` + `findMatches`)
+- **Trigger**: `Cmd/Ctrl+F` bound on the **textarea keydown** (not a global
+  shortcut) so the browser's native find can't intercept it first.
+- **Panel**: floating, top-right of the editor. Find row = input + match counter
+  (`3/12`), prev/next, and three toggles — **Aa** case, **W** whole-word,
+  **.*** regex (active toggle filled with `--accent`). A disclosure chevron
+  expands the **Replace** row (input + Replace + Replace-all).
+- **Highlights**: drawn by a **second `color:transparent` `<pre>` overlay**
+  (`MarkOverlay`) layered *below* the token `<pre>`, carrying only background
+  spans — the token render path (`SqlHighlighter`) is never touched, exactly as
+  resolved in the issue. All matches use a translucent accent bg; the active
+  match a stronger accent. Same padding/font/scroll-sync as the other layers.
+- **Keys**: Enter = next, Shift+Enter = prev, Esc = close. Invalid regex →
+  counter shows "bad re", red field border, no marks.
+- **Behavior**: `findMatches(value, query, {caseSensitive, wholeWord, regex})`
+  returns `{start,end}[]`; navigation scrolls the textarea to center the active
+  match.
+
+#### #24 — Bracket matching + auto-close (`sql-editor.jsx`)
+- **Match highlight**: when the caret is adjacent to a bracket, both it and its
+  partner get an accent bg (via the same `MarkOverlay`). `matchBracketAt`
+  scans with nesting depth in either direction.
+- **Auto-close**: typing `(` `[` `{` inserts the pair and puts the caret
+  inside. Quotes `'` `"` `` ` `` auto-close too (double-quote included per the
+  resolved decision; `{`/`}` JSON context deliberately *excluded* from 1b).
+- **Wrap selection**: with text selected, typing an opener wraps the selection —
+  `(selected)`.
+- **Type-over**: typing a closing bracket/quote when the next char is already
+  that char just steps over it.
+- **Pair-delete**: Backspace inside an empty `()`/`''` removes both.
+
+#### #25 — Dynamic reference data + tokenizer API (`editor-data.jsx`)
+- **Tokenizer API**: `tokenize(sql, { keywords, funcs } = {})` — optional second
+  arg, backward-compatible (existing callers pass nothing → built-in sets). Lets
+  the server's `system.keywords` / `system.functions` drive highlighting so it's
+  version-correct.
+- **Reference payload** (`REF_KEYWORDS`, `REF_FUNCTIONS`, `REF_KEYWORD_DOCS`):
+  keyword list, function signatures + return types + descriptions, keyword docs.
+  `buildCompletions(schema)` merges these with the in-memory schema (databases,
+  tables, and **only already-loaded columns** — no on-demand column fetch from
+  the completion path) into a flat candidate list.
+- **Production**: load once per connection from `system.{keywords,functions,
+  completions,documentation}`, cache in memory for the session (localStorage
+  deferred until server-version-keyed invalidation is designed).
+
+#### #26 — Autocomplete dropdown (`editor-complete.jsx`, `AutocompleteDropdown`)
+- **Trigger**: typing word chars (≥1) or right after a `.`. `completionContext`
+  finds the word under the caret and whether it's **qualified** (`table.` →
+  only that table's columns).
+- **Ranking** (`rankCompletions`): prefix matches before substring; schema
+  (columns/tables) boosted; capped to 50. Empty word after no dot →
+  keywords + tables only.
+- **UI**: 350px popover at the caret (flips above when near the bottom). Each row
+  = a kind glyph chip (keyword `K` / function `ƒ` / aggregate `Σ` / cast `⇄` /
+  table `▦` / column `▪` / db `◈`, each color-coded), the label with the typed
+  substring bolded in accent, and a right-aligned detail (signature / type /
+  "table · N rows"). A footer shows the active item's signature → return type
+  and description.
+- **Keys**: ↑/↓ move, Enter/Tab accept, Esc dismiss; mouse click accepts.
+  Functions insert `name(`. Accepting replaces the `[from,to]` word range.
+
+#### #27 — Signature help + hover docs (`editor-complete.jsx`)
+- **Signature help**: while the caret is inside `fn(…)`, a popover above the
+  caret shows the signature with the **active argument bolded** (arg index from
+  `signatureContext`, which walks back counting commas at depth 0) and the return
+  type. Hidden while the autocomplete dropdown is open.
+- **Hover docs**: hovering a function or documented keyword (~350ms dwell) shows
+  a `HoverCard` with signature → return and description. Position is mapped from
+  mouse XY back to a token via `posFromXY` + `wordAt`. Phase 2c / optional;
+  in production source docs from `system.documentation` (load upfront with #25,
+  or lazily on first hover — open question).
+
+**Geometry note:** caret/hover positioning uses a monospace fast-path
+(`charWidthFor` via canvas + line/col arithmetic) rather than a mirror div,
+valid because the editor is `white-space: pre` in a monospace font. If a
+proportional font or wrapping is ever introduced, switch to a mirror-div
+measurement.
+
+**Not buildable on a textarea** (correctly deferred to the CodeMirror track,
+#21): code folding and multi-cursor — one caret, no line hiding.
+
+---
+
+## Region 6: Results pane
+
+### 6a. Results toolbar (36px)
+
+Background `--bg-toolbar`. Bottom 1px `--border`. `0 10px` padding, 10px gap.
+
+- **View segmented control** (3 options: Table / Chart / JSON):
+  - Container: `--bg-chip`, 5px radius, 2px padding.
+  - Each segment: 22px tall, 10px x-padding, 4px radius. Active: `--bg-editor`
+    bg, `--fg` text, 500 weight, subtle 1px shadow. Inactive: `--fg-mute`, 400.
+  - Each segment shows icon + label.
+- **Spacer**
+- **Stat chips** (right-aligned, separated by 1px `--border-faint`):
+  - clock icon + ms (e.g. "218 ms")
+  - rows icon + row count (e.g. "15 rows")
+  - bytes icon + scanned bytes (e.g. "2.41 GB"), title attr shows scanned row
+    count.
+  - 11px mono, `--fg-mute` for icons, `--fg` for values.
+- **Copy button** (tb-btn): copy icon + "Copy"
+- **Export button** (tb-btn): download icon + "Export"
+
+### 6b. Empty state
+
+When no result and not running: centered column with a 36×36 `--bg-chip` circle
+holding a faded play icon, then the message "Press `⌘↵` to run query" with a
+styled kbd.
+
+### 6b-running. Query-running state — progressive streaming (no blocking loader)
+
+While a query is in flight, **do not** block the pane with a full-screen
+spinner. Instead **stream partial results into the table as they arrive** and
+show live counters in the results toolbar. Showing data-so-far is materially
+better UX than a spinner, and it mirrors how ClickHouse actually returns data.
+
+**Results toolbar while running** (replaces the static stats):
+- **Live counters**, rendered in `--accent`, mono:
+  - clock/spinner + **elapsed ms**, ticking smoothly off a local
+    `performance.now()` clock (~50ms interval).
+  - rows icon + **rows read so far** (`fmt()` → 7.7M / 64.1M-style humanized).
+  - bytes icon + **bytes scanned so far**.
+- **Cancel** button (replaces Copy/Export while running): `Icon.close` +
+  "Cancel" + an `Esc` kbd. Hover turns red (`#ef4444`). **Esc also cancels**
+  (global key handler).
+
+**Results body while running:**
+- The **table renders the partial rows** that have streamed in (columns appear
+  immediately; rows fill progressively). Before the first batch, a brief
+  centered "Starting query…" with a small spinner (`EmptyResults streaming`).
+- A 2px **streaming strip** pins to the top of the body: an `--accent` fill at
+  `read / total` when totals are known, otherwise an indeterminate sweep
+  (`runsweep` keyframes).
+
+**On cancel:** stop the stream, **keep whatever rows already arrived**, and mark
+the result `cancelled`. The toolbar then shows a red **"Cancelled · partial"**
+badge next to the (frozen) final stats, and Copy/Export re-enable on the partial
+set.
+
+**Production wiring:** drive the streamed rows + counters from ClickHouse's
+**`X-ClickHouse-Progress`** headers (rows/bytes read + total estimate) and the
+streamed result body; wire **Cancel** / Esc to **`KILL QUERY`**. The prototype
+simulates the stream in `app.jsx` → `runQuery` (partial-row slices on a timer)
+and `cancelQuery`. A **"Slow query (~9s)"** toggle under Tweaks → Demo only
+slows the simulation so the streaming is easy to observe — no production
+meaning; remove it in the real build.
+
+### 6c. Table view
+
+- Mono font, 11.5px.
+- `border-collapse: collapse`. Width `max-content`, min `100%`.
+- **Header row** (`thead` is `position: sticky; top: 0`):
+  - 36px wide `#` column, centered, `--fg-faint`.
+  - Each data column: min-width 140px. Cell padding `7px 12px` (4px 10px in
+    compact). Background `--bg-th`. Font 11px / 500 / `--fg-mute`.
+  - Inside each cell: column name in `--fg`, then type badge in 9.5px /
+    `--fg-faint`. Spacer. If this column is the active sort, sort arrow in
+    `--accent`. Click toggles asc → desc → asc.
+- **Data row**:
+  - Hover: `--bg-hover` on every cell.
+  - Number cells: right-aligned, color `--num` (`#92E1D8` dark / `#0F766E`
+    light), shown to 2 decimals.
+  - String cells: left-aligned, `--fg`.
+  - **Special case**: column 0 in the demo result is an airline code like
+    "B6". Render as `<code>B6</code>` followed by faded carrier name (`JetBlue`,
+    etc) in `--fg-faint`. The lookup table is in `data.jsx` (`CARRIER_NAMES`).
+    In production, this should be a more general "dimension display" extension
+    (e.g. allow saved queries to declare lookup mappings).
+  - All cells: 1px `--border-faint` right + bottom borders.
+
+### 6d. Chart view (bar)
+
+For 2-column results where col 0 is a dimension and col 1 is a number.
+
+- Padding `20px 24px`. Background `--bg-table`.
+- Title: "{col1.name} by {col0.name}", 11px mono / `--fg-mute`, 14px bottom.
+- Each row, 18px tall:
+  - Label cell: 110px wide, mono, right-aligned. Code in `--fg`, expanded name
+    in `--fg-faint` (same dimension treatment as the table).
+  - Bar track: `flex: 1`, 18px tall, `--bg-chip` bg, 2px radius.
+  - Bar fill: gradient `linear-gradient(90deg, var(--accent),
+    color-mix(in oklab, var(--accent) 65%, transparent))`. Width = (value /
+    max) * 100%. Transition `width .4s cubic-bezier(.2,.7,.3,1)`.
+  - Value cell: 70px wide, mono, right-aligned, `--num`, 2 decimals.
+
+For other shapes (single-series line, pie, multi-series), follow the same
+visual language: accent-tinted, mono labels, dim grid, no chartjunk. Use
+visx / Recharts / d3 / Apache ECharts — whatever the codebase has.
+
+#### Implementing Chart view in production (answer to Boris)
+
+> **Now built in the prototype.** `ResultsChart` in `components.jsx` implements
+> the config bar + `autoChart()` defaults + SVG renderers + an HTML horizontal-bar
+> renderer (Bar=horizontal/Column=vertical/Line/Area/Pie, multi-series, group-by).
+> `autoChart` defaults categorical X → **horizontal Bar** (the ranked-list view
+> from the first design — best for category comparisons), temporal X → Line,
+> ordinal X → Column. `data.jsx` adds `RESULT_MONTHLY` (temporal → Line) and
+> `RESULT_DOW` (ordinal) demo sets, and `pickResult(sql)` chooses one by
+> inspecting the SQL so Bar↔Line is demonstrable. The renderers are
+> prototype-grade — **swap for a real charting library in production** (below);
+> keep the config-bar UX, the `autoChart` heuristic, and horizontal-bar default.
+
+The prototype's chart is deliberately the *minimum*: a CSS-only horizontal bar
+chart hardwired to `col[0]=dimension, col[1]=measure` (see `ResultsChart` in
+`components.jsx`). It demonstrates the look, not the real capability. Here's how
+to build the production version.
+
+**1. Don't hand-roll it — use a charting library.** CSS bars don't scale to
+line/area/pie, axes, tooltips, legends, log scales, or thousands of points.
+Pick one already in (or acceptable to) the codebase:
+- **Apache ECharts** — best for large/dense data and many chart types
+  (canvas-rendered, handles 10k+ points, built-in zoom/tooltip). Recommended
+  default for a data tool.
+- **Recharts / visx** — fine if the app is React-first and datasets stay small
+  (SVG; gets heavy past a few thousand points).
+- **Observable Plot** — terse grammar-of-graphics, great for quick exploratory
+  charts.
+
+**2. Infer column roles from ClickHouse types, then let the user override.**
+The result already carries `{name, type}` per column — use the type to
+classify, don't guess from values:
+- **Measures (Y / value)**: numeric types — `Int*`, `UInt*`, `Float*`,
+  `Decimal*`.
+- **Temporal (X, ordered)**: `Date`, `Date32`, `DateTime`, `DateTime64`.
+- **Dimensions (X / category / series)**: `String`, `LowCardinality(String)`,
+  `Enum*`, `Bool`.
+- Strip `Nullable(...)` / `LowCardinality(...)` wrappers before classifying.
+
+Auto-pick a sensible default encoding (first temporal or dimension → X; first
+measure → Y), then expose a small **chart-config bar** above the plot so the
+user can change it. That config is the real feature:
+- **Chart type**: Bar / Line / Area / Pie / (Scatter). Default by data shape:
+  temporal X → line; categorical X → bar; single dimension + single measure and
+  ≤ ~12 rows → pie is allowed.
+- **X axis** (dropdown of columns), **Y axis / measures** (one or many numeric
+  columns → multi-series), optional **Series/Group-by** (a dimension column →
+  splits into multiple lines/stacked bars).
+- Persist the chosen config per query tab.
+
+**3. Map result → chart data.** Transform the `rows: any[][]` + `columns[]` into
+the library's series format using the encoding above. For multi-series, pivot on
+the series column. Coerce `DateTime` strings to real dates for time axes.
+
+**4. Theme it to the tokens** so charts match the app in both themes:
+- Series color: `--accent` (single series); for multi-series derive a small
+  palette by rotating hue off the accent (e.g. OKLCH hue steps) rather than a
+  random rainbow.
+- Axes / grid: `--border` / `--border-faint`; labels `--fg-mute`, mono font
+  (`--mono`); tooltip surface `--bg-modal` + `--border`.
+- No gradients-as-decoration, no drop shadows, no 3D — keep the dense/technical
+  look.
+
+**5. Handle the realities of query output:**
+- **No chartable columns** (e.g. all strings, or a single column) → show an
+  empty-state hint ("Add a numeric column to chart these results"), not a broken
+  axis.
+- **Too many points** → the chart engine should downsample/aggregate, or prompt
+  to add `LIMIT` / `GROUP BY`. ECharts' `large` mode or server-side bucketing
+  handles this.
+- **Streaming**: only render the chart on completed (or paused) result sets;
+  re-rendering a chart on every streamed batch is wasteful — update the table
+  live, build the chart when the stream settles.
+- Respect the current sort, and format numbers like the table (`--num`, 2
+  decimals / humanized).
+
+**6. Keep the toggle contract.** Chart is one of the three result views
+(Table / Chart / JSON segmented control). Selecting it swaps the body only; the
+results toolbar (stats, copy/export) stays. "Export" on a chart view can offer
+PNG/SVG in addition to the data formats.
+
+### 6e. JSON view
+
+- `<pre>` over the full pane, padding `14px 16px`.
+- 11.5px mono, `--fg`, on `--bg-table`. Pretty-printed (2-space indent).
+- Built from the sorted rows + column names.
+
+---
+
+## Region 7: Tweaks panel (dev tool — DO NOT SHIP TO END USERS)
+
+This is a design-time controls panel from our prototyping kit. It exists so the
+designer can tweak theme/accent/density/sidebar live. It's **not part of the
+end-user product**.
+
+If you want a similar end-user "preferences" surface, that's a separate spec —
+ask before adding.
+
+---
+
+## Region 8: Shortcuts modal (`?` to open)
+
+- 480px wide centered modal, `--bg-modal` background, 1px `--border`, 10px
+  radius. Backdrop: `rgba(0,0,0,.5)` + 4px blur.
+- Title "Keyboard shortcuts", 14px / 600.
+- 3 groups (Editor, Navigation, Results) — each a small section header (10px /
+  600 / uppercase / `.06em` letter-spacing / `--fg-faint`) followed by rows.
+- Row: label in `--fg-mute` left, kbd badge right (10.5px mono, `--bg-chip`
+  bg, 4px radius, `--fg`).
+- Click outside closes. The exact shortcut list is in `components.jsx`
+  → `ShortcutsModal`.
+
+---
+
+## Interactions & behavior
+
+- **⌘↵ / Ctrl↵**: run query.
+- **⌘T / Ctrl T**: new tab.
+- **⌘W / Ctrl W**: close tab. (Wired to UI close × button; bind globally.)
+- **?**: toggle shortcuts modal (only when not in input/textarea).
+- **Click column in schema** → inserts column name at end of active tab's SQL.
+  In production, prefer "insert at cursor" via the editor's native API.
+- **Click table row in saved/history** → opens the SQL as a new tab.
+- **Tab dirty state**: any edit since load → small dot next to the tab name.
+  Save logic isn't designed yet — saved queries are a read-only catalog in
+  the prototype. Define save UX with the team.
+- **Run query** flow in the prototype just sleeps 600ms and returns the canned
+  result. In production, post to the ClickHouse HTTP interface
+  (`POST /?database=…` with `X-ClickHouse-Format` header) and stream/parse
+  results. Show running spinner state on the Run button (already wired —
+  `running={running}` prop).
+- **Sort columns**: clicking a header cycles asc → desc → asc (no neutral
+  state in the prototype). For real datasets larger than what's loaded,
+  re-issue the query with `ORDER BY` rather than client-sorting.
+- **Splitter drags**: editor/results split clamps to 15–85%. Sidebar width
+  clamps 180–420.
+- **Resizable sidebar inner split** (schema vs saved/history) — currently
+  uses flex; consider making it draggable too if users ask.
+- **Search in schema**: filters by substring across table and column names.
+  Tables that don't match but have matching columns stay visible (auto-expand).
+  Persist? — open question.
+
+---
+
+## Design Tokens
+
+All theme tokens live as CSS custom properties on the `[data-theme='dark']` /
+`[data-theme='light']` selectors. They drive every surface, border, and
+text color in the design.
+
+### Dark theme (default)
+
+| Token | Value | Purpose |
+|-------|-------|---------|
+| `--bg`           | `#0E0E10` | App background |
+| `--bg-header`    | `#131316` | Header & sidebar bg |
+| `--bg-side`      | `#131316` | Sidebar bg |
+| `--bg-tabs`      | `#131316` | Tabs row |
+| `--bg-toolbar`   | `#15151A` | Editor + results toolbars |
+| `--bg-editor`    | `#0E0E10` | Editor pane |
+| `--bg-gutter`    | `#131316` | Editor line numbers |
+| `--bg-table`     | `#0E0E10` | Results surface |
+| `--bg-th`        | `#15151A` | Table header |
+| `--bg-input`     | `#1A1A20` | Inputs |
+| `--bg-chip`      | `#1F1F26` | Chips, segmented control track |
+| `--bg-hover`     | `rgba(255,255,255,.04)` | Generic hover |
+| `--bg-highlight` | `rgba(255,107,53,.08)` | Search match |
+| `--bg-modal`     | `#1A1A20` | Modal surface |
+| `--fg`           | `#E6E6E8` | Primary text |
+| `--fg-mute`      | `#A0A0A8` | Secondary text |
+| `--fg-faint`     | `#6B6B74` | Tertiary text / icons |
+| `--num`          | `#92E1D8` | Numeric values in tables/charts |
+| `--border`       | `#1F1F26` | Hard borders |
+| `--border-faint` | `#1A1A20` | Soft cell/row dividers |
+
+### Light theme
+
+| Token | Value |
+|-------|-------|
+| `--bg`           | `#FAFAFA` |
+| `--bg-header`    | `#FFFFFF` |
+| `--bg-side`      | `#F5F5F4` |
+| `--bg-tabs`      | `#F5F5F4` |
+| `--bg-toolbar`   | `#FAFAF9` |
+| `--bg-editor`    | `#FFFFFF` |
+| `--bg-gutter`    | `#FAFAF9` |
+| `--bg-table`     | `#FFFFFF` |
+| `--bg-th`        | `#F5F5F4` |
+| `--bg-input`     | `#FFFFFF` |
+| `--bg-chip`      | `#EEECE8` |
+| `--bg-hover`     | `rgba(0,0,0,.04)` |
+| `--bg-highlight` | `rgba(255,107,53,.12)` |
+| `--bg-modal`     | `#FFFFFF` |
+| `--fg`           | `#1A1A1F` |
+| `--fg-mute`      | `#57575E` |
+| `--fg-faint`     | `#94949C` |
+| `--num`          | `#0F766E` |
+| `--border`       | `#E5E3DE` |
+| `--border-faint` | `#EEECE7` |
+
+### Accent
+
+`--accent` is a **theme-independent** brand color — same in dark and light:
+
+- **Default (Altinity orange)**: `#FF6B35`
+- Quick swatches in the design: `#FF6B35`, `#F0A500`, `#FFC700`, `#3B82F6`,
+  `#10B981`, `#EC4899`. The color picker stores the value; UI uses it
+  everywhere — Run button, table top accent, sort arrow, chart bars, search
+  highlight, logo gradient base.
+
+### Typography
+
+| Family | CSS |
+|---|---|
+| UI    | `'Inter', -apple-system, BlinkMacSystemFont, system-ui, sans-serif` |
+| Mono  | `'JetBrains Mono', 'SF Mono', ui-monospace, Menlo, monospace` |
+
+Type ramp (px / weight):
+- Modal title: 14 / 600
+- Sidebar header rows / tab name: 13 / 600 / 11.5 / 500
+- Body button: 11.5 / 500–600
+- Secondary text: 11 / 400
+- Small caps section labels: 10 / 600 / uppercase / `.06em` letter-spacing
+- Table cells / SQL editor: 11.5–13 mono / 400
+
+### Spacing & radii
+
+- Heights: header 44, tabs 34, toolbars 36–38, control buttons 26, segmented
+  control items 22, tree rows 22–24.
+- Padding: page rails `0 14px`, region toolbars `0 10px`, table cells
+  `7px 12px` comfortable / `4px 10px` compact.
+- Radii: 4 (small chips, kbd), 5 (buttons, inputs, selects), 10 (modal), 12
+  (avatar circle).
+- Shadows: very restrained. The active segment in the segmented control gets
+  `0 1px 2px rgba(0,0,0,.15)`. The modal: `0 20px 60px rgba(0,0,0,.4)`. The
+  status dot: `0 0 6px #22c55e`.
+
+### Density
+
+`compact` reduces editor line-height (1.7→1.5) and font (13→12.5), tabs row
+(34→28), and table cell padding (7×12 → 4×10). `comfortable` is default.
+
+---
+
+## State Management
+
+Minimal, all local:
+
+- `tabs: Tab[]` — open query tabs (id, name, sql, dirty).
+- `activeId` — id of focused tab.
+- `result` — current result-set (canned in prototype). In production: tied
+  to the active tab; cache last result per tab so switching tabs doesn't lose
+  it.
+- `running: bool` — query in flight.
+- `shortcutsOpen` — modal toggle.
+- Pane sizes — `editorPct` (vertical split %), `sidebarPx` (sidebar width).
+
+Persisting to URL/local storage suggestions:
+
+- The currently-loaded SQL → URL hash (so a query is shareable). The "Share"
+  button should generate this URL.
+- Sidebar/editor split sizes → localStorage.
+- Theme/density/accent → localStorage (or user account settings).
+
+## Data fetching
+
+Replace `runQuery` (currently a 600ms timeout) with the actual ClickHouse HTTP
+call:
+
+```
+POST {clickhouse-base}/?database={db}&default_format=JSONCompactEachRowWithNamesAndTypes
+Authorization: Basic …  // or whatever the existing /play uses
+Content-Type: text/plain
+
+{sql}
+```
+
+`JSONCompactEachRowWithNamesAndTypes` returns a streaming format that's easy
+to render into the table without re-parsing. The result-set shape used by
+the prototype (`{ columns: [{name, type}], rows: any[][], meta: {ms, rows,
+scanned, scannedRows}}`) maps cleanly: take the first two streamed objects
+as names + types, the rest as rows, and read the `X-ClickHouse-Summary`
+response header for stats.
+
+---
+
+## Schema for the "schema browser" data
+
+Currently hardcoded in `data.jsx` (`SCHEMA`). In production, fetch from
+ClickHouse:
+
+```sql
+SELECT database, name, total_rows, total_bytes
+FROM system.tables
+WHERE database NOT IN ('INFORMATION_SCHEMA', 'information_schema')
+ORDER BY database, name
+
+-- and for columns when a table is expanded:
+SELECT name, type
+FROM system.columns
+WHERE database = ? AND table = ?
+ORDER BY position
+```
+
+Lazy-load columns on table expand; cache per session.
+
+---
+
+## Saved queries & history
+
+The prototype hardcodes both. In production:
+
+- **Saved queries**: persist per-user to wherever Altinity Antalya stores user
+  state. Schema: `{id, name, sql, starred, created_at, updated_at}`.
+- **History**: write every executed query to a per-user log (capped, e.g. last
+  500) with `{sql, started_at, duration_ms, rows, error}`.
+
+> **Note on the current implementation:** saved queries live in browser
+> `localStorage` today. That makes them per-browser-profile — lost on a cache
+> clear, invisible on the user's other devices, and unshareable. The
+> export/import feature below is the agreed interim mitigation; account-backed
+> server storage is the eventual answer (and even then, export survives as a
+> backup / portability / no-lock-in feature, so this work is not throwaway).
+
+### Export / Import saved queries (JSON)
+
+**Goal:** let users back up, transfer between machines/browsers, and share
+their saved-query library. **JSON is the canonical format** — it round-trips
+losslessly (export → import reproduces the library exactly).
+
+(Decisions already made with the team: **JSON only** for round-trip
+import/export. Markdown may be added later as an *export-only* "share" format.
+CSV/TSV were explicitly rejected — SQL payloads contain newlines/commas/quotes
+that delimited formats handle badly.)
+
+#### File envelope
+
+Export the whole library (or a user-selected subset) as a single `.json` file.
+Wrap the array in a versioned envelope so the format can evolve:
+
+```json
+{
+  "format": "altinity-sql-browser/saved-queries",
+  "version": 1,
+  "exportedAt": "2026-06-21T17:52:53.000Z",
+  "queries": [
+    {
+      "id": "q_8f3a1c",
+      "name": "Worst-delay carriers (2023)",
+      "sql": "SELECT Reporting_Airline, avg(DepDelayMinutes) AS avg_delay\nFROM airline.ontime\nWHERE Year = 2023 AND Cancelled = 0\nGROUP BY Reporting_Airline\nORDER BY avg_delay DESC\nLIMIT 15",
+      "starred": true,
+      "createdAt": "2026-05-02T09:14:00.000Z",
+      "updatedAt": "2026-06-10T12:31:00.000Z"
+    }
+  ]
+}
+```
+
+- `format` + `version` let the importer reject foreign/garbage files and
+  migrate older exports. Bump `version` on any breaking schema change.
+- `id` should be **stable** (don't regenerate on every save) — it's what makes
+  re-import idempotent (see merge rules).
+- Suggested filename: `sql-browser-queries-YYYY-MM-DD.json`.
+
+#### Export UI
+
+- Primary: **Export all** → downloads the envelope above.
+- Nice-to-have: multi-select in the Saved list → **Export selected**. Same
+  envelope, filtered `queries[]`.
+- **Placement**: Export + Import are a two-button row **pinned at the bottom of
+  the Saved panel** (top border, `flex-shrink: 0`), below the scrolling query
+  list — not at the top. The import-result toast ("Added N · updated N ·
+  skipped N") appears just above the bar.
+- Implementation: serialize → `Blob` → `URL.createObjectURL` → anchor download.
+  No backend needed.
+
+#### Import UI + merge rules (this is the real design work)
+
+Export is trivial; **import is where the decisions live.** On file pick:
+
+1. **Validate** — parse JSON; reject if `format` doesn't match or `version` is
+   newer than the app understands. Validate each query's shape. Cap count/size
+   (e.g. ≤ 1000 queries, ≤ 1 MB) to avoid abuse.
+2. **Treat SQL as untrusted text** — never auto-run an imported query. It only
+   ever runs later when the user explicitly hits Run.
+3. **Collision handling** — for each incoming query, match against the existing
+   library **by `id`**:
+   - *No match* → add as new.
+   - *Match, identical `sql` + `name`* → skip (no-op; makes re-import
+     idempotent).
+   - *Match, differs* → resolve via the user's chosen strategy. Offer at minimum:
+     **Skip**, **Overwrite**, **Keep both** (import gets a new id +
+     "(imported)" suffix on the name). A per-conflict prompt is ideal; a
+     single global choice is the acceptable MVP.
+   - If `id`s aren't trustworthy across installs, fall back to matching on a
+     **hash of normalized SQL**, or on `name`.
+4. **Partial import** — show a preview list with checkboxes so users import a
+   subset, not all-or-nothing. MVP can skip this and import everything.
+5. **Report** — after import, summarize: "Added 6, updated 2, skipped 3."
+
+#### Markdown export (future, export-only)
+
+If/when a "share" export is added: render each query as a `## {name}` heading
+followed by a fenced ` ```sql ` block — renders perfectly in GitHub/wikis as a
+"query cookbook." **Do not** rely on parsing it back; metadata (starred,
+timestamps) doesn't survive without per-query YAML frontmatter, at which point
+JSON is the better round-trip format. Keep Markdown strictly one-directional.
+
+---
+
+## Assets
+
+- **Inter** and **JetBrains Mono** fonts loaded from Google Fonts in the
+  prototype. Self-host in production for performance/privacy.
+- **Icons** are inline SVGs in `components.jsx` → `Icon` map. Replace with
+  the codebase's icon library (lucide / phosphor / heroicons / etc.) using
+  the closest equivalents — they're all standard glyphs (chevron, database,
+  table, columns, play, star, plus, close, search, history, download, share,
+  copy, sortAsc, sortDesc, filter, clock, rows, bytes, etc.).
+
+---
+
+## Files in this bundle
+
+- `Altinity Play.html` — entry point. Open in a browser to see the design.
+- `Login.html` — the sign-in / connection screen (SSO + credentials + optional
+  host:port override). Self-contained; imports `tweaks-panel.jsx`.
+- `app.jsx` — top-level `<App />` component, layout assembly, splitters,
+  global keyboard handlers.
+- `components.jsx` — header, schema tree, saved/history panel, query tabs,
+  editor toolbar, results pane (table/chart/json), shortcuts modal, icon
+  set.
+- `sql-editor.jsx` — the syntax-highlighted SQL editor (textarea over `<pre>`)
+  + the editor enhancements (#23–#27): tokenizer dynamic-keyword API, bracket
+  matching/auto-close, find/replace wiring, autocomplete + signature + hover
+  wiring, caret geometry. **In production, the editing surface can stay as-is
+  for #23–#27; folding/multi-cursor need CodeMirror (#21).** Keep the visual
+  treatment (colors, gutter, font).
+- `editor-data.jsx` — reference data (keywords, function signatures/docs,
+  `buildCompletions`). Load from ClickHouse system tables in production (#25).
+- `editor-search.jsx` — find/replace panel + `findMatches` (#23).
+- `editor-complete.jsx` — autocomplete dropdown, signature help, hover card,
+  and their context/ranking helpers (#26/#27).
+- `data.jsx` — sample schema, saved queries, history, and a canned result-set
+  (worst-delay carriers query against the airline ontime dataset).
+- `tweaks-panel.jsx` — design-time controls. **Not part of the end-user
+  product.**
+
+---
+
+## Resolved since first handoff
+
+Decisions made with the team after the initial spec (implemented in the live
+app — recorded here so the README stays the source of truth):
+
+- **Save UX** — "Save" button in the editor toolbar (+ ⌘S) opens a name
+  popover; saved items appear in the ★ Saved list with inline rename (pencil),
+  delete (trash), and star toggle. Implemented.
+- **Format button** — pretty-prints SQL (⌘⇧F). Prototype uses a hand-rolled
+  formatter; production should use `sql-formatter` or the editor's native
+  format action.
+- **Column resize** — implemented in the live app.
+- **Column types in result header** — **removed by design.** Stored-column
+  types already live in the schema browser, so repeating them in the result
+  header is duplication. Trade-off: **computed/aliased columns**
+  (`avg(...) AS x`, `count()`, JOIN outputs) have their type nowhere else —
+  recommend exposing type on **hover** of the result column name to cover that
+  case without re-adding the duplication.
+- **GitHub link** — added to the header. Give it `aria-label="View source on
+  GitHub"` and `target="_blank" rel="noopener"`.
+- **User menu / Log Out** — header avatar is a button opening a dropdown
+  (identity + role + red Log out), which raises a confirmation dialog. See
+  Region 1 for the full spec.
+- **Export/Import placement** — the two-button row is pinned at the **bottom**
+  of the Saved panel, below the list.
+- **Markdown "Publish"** — deferred for more thought; captured as a separate
+  proposed issue (`ISSUE-publish-as-markdown.md` in this bundle).
+- **Saved-query export/import** — JSON, spec'd in "Export / Import saved
+  queries" above.
+
+---
+
+## Open questions for the design + product team
+
+(These came up while building the prototype / reviewing the live app and
+weren't fully resolved.)
+
+1. **`content`-style blob columns**: text cells holding large values (full HTML
+   documents, long JSON) are unreadable inline even with column resize. Add a
+   **cell-detail drawer**: click a cell → side panel/modal with the full value,
+   pretty-printed, and a **rendered-vs-source toggle** for HTML. Pair with
+   `max-width` + ellipsis truncation on text cells. **Highest-impact open item.**
+2. **Sticky first column(s)**: freeze `#` (and ideally the first data column)
+   during horizontal scroll so row identity isn't lost when reading wide
+   columns to the right.
+3. **NULL rendering**: render `NULL` distinctly (faint italic "null"), never as
+   an empty cell — otherwise NULL is indistinguishable from an empty string,
+   which matters on a tool people use to learn unfamiliar data.
+4. **Long version string in header**: e.g.
+   "ClickHouse 26.3.10.20001.altinityantalya" crowds the top bar and will
+   overflow on narrow widths. Truncate (e.g. `26.3.10`) with the full string on
+   hover.
+5. **Saved-query storage**: `localStorage` today (per-browser, fragile). JSON
+   export/import is the interim mitigation; account-backed server sync is the
+   roadmap answer (and unlocks real shared-query URLs via the existing Share
+   button).
+6. **Tab persistence**: should open tabs + their SQL survive a refresh? (Likely
+   yes — localStorage.)
+7. **Query cancellation**: ClickHouse supports `KILL QUERY`. Surface an inline
+   "Cancel" affordance on the running button?
+8. **Streaming results**: large result-sets — paginate, or virtual-scroll the
+   whole thing? Recommend virtual scroll (TanStack Virtual / react-window).
+9. **Errors**: error UI isn't in the prototype. Treat the result pane as the
+   surface (red banner + traceback in mono).
+10. **Auth**: the original page is auth-gated. Login screen design wasn't in
+    scope for this round. Coordinate with whoever owns it.
+11. **Accessibility**: contrast in dark mode is good (Inter @ `#E6E6E8` on
+    `#0E0E10` ≈ 14:1). Audit segmented control + chart bars in light mode.
+    Wire keyboard nav for the schema tree (↑↓ to move, → to expand). The
+    shortcuts modal needs a real `role="dialog"` with focus trap.
diff --git a/design/app.jsx b/design/app.jsx
new file mode 100644
index 0000000..8ae9676
--- /dev/null
+++ b/design/app.jsx
@@ -0,0 +1,340 @@
+// app.jsx — main app shell
+
+function App() {
+  const [t, setTweak] = useTweaks(TWEAK_DEFAULTS);
+  const accent = t.accent;
+  const dark = t.theme === 'dark';
+  const density = t.density;
+  const sidebarVisible = t.sidebar;
+
+  // Tabs
+  const [tabs, setTabs] = React.useState([
+    { id: 't1', name: 'Worst-delay carriers', sql: SAVED_QUERIES[0].sql, dirty: false, savedId: SAVED_QUERIES[0].id },
+    { id: 't2', name: 'Untitled query', sql: 'SELECT count() FROM airline.ontime\nWHERE Year = 2023', dirty: true },
+  ]);
+  const [activeId, setActiveId] = React.useState('t1');
+  const active = tabs.find(t => t.id === activeId) || tabs[0];
+
+  const [result, setResult] = React.useState(RESULT_DELAYS);
+  const [running, setRunning] = React.useState(false);
+  const [shortcutsOpen, setShortcutsOpen] = React.useState(false);
+  const [savedQueries, setSavedQueries] = React.useState(SAVED_QUERIES);
+  const [saveSignal, setSaveSignal] = React.useState(0);
+
+  const updateTabSql = (sql) => {
+    setTabs(ts => ts.map(t => t.id === activeId ? { ...t, sql, dirty: true } : t));
+  };
+  const newTab = () => {
+    const id = 't' + Date.now();
+    setTabs(ts => [...ts, { id, name: 'Untitled query', sql: '', dirty: false }]);
+    setActiveId(id);
+  };
+  const closeTab = (id) => {
+    setTabs(ts => {
+      const i = ts.findIndex(t => t.id === id);
+      const next = ts.filter(t => t.id !== id);
+      if (id === activeId) setActiveId(next[Math.max(0, i - 1)].id);
+      return next;
+    });
+  };
+  const loadQuery = (q) => {
+    const id = 't' + Date.now();
+    setTabs(ts => [...ts, { id, name: q.name, sql: q.sql, dirty: false, savedId: q.id }]);
+    setActiveId(id);
+  };
+  const insertColumn = (col) => {
+    setTabs(ts => ts.map(t => t.id === activeId ? { ...t, sql: t.sql + col, dirty: true } : t));
+  };
+  const formatCurrent = () => {
+    setTabs(ts => ts.map(t => t.id === activeId ? { ...t, sql: formatSql(t.sql), dirty: true } : t));
+  };
+  const saveCurrentQuery = (name) => {
+    const sql = active.sql;
+    const existingId = active.savedId && savedQueries.some(q => q.id === active.savedId) ? active.savedId : null;
+    const id = existingId || ('s' + Date.now());
+    setSavedQueries(qs => existingId
+      ? qs.map(q => q.id === id ? { ...q, name, sql } : q)
+      : [{ id, name, sql, starred: false }, ...qs]);
+    setTabs(ts => ts.map(t => t.id === activeId ? { ...t, name, dirty: false, savedId: id } : t));
+  };
+  const renameSaved = (id, name) => {
+    setSavedQueries(qs => qs.map(q => q.id === id ? { ...q, name } : q));
+    setTabs(ts => ts.map(t => t.savedId === id ? { ...t, name } : t));
+  };
+  const deleteSaved = (id) => {
+    setSavedQueries(qs => qs.filter(q => q.id !== id));
+    setTabs(ts => ts.map(t => t.savedId === id ? { ...t, savedId: undefined, dirty: true } : t));
+  };
+  const toggleStar = (id) => {
+    setSavedQueries(qs => qs.map(q => q.id === id ? { ...q, starred: !q.starred } : q));
+  };
+  const importQueries = (incoming) => {
+    let added = 0, updated = 0, skipped = 0;
+    setSavedQueries(qs => {
+      const next = [...qs];
+      const byId = new Map(next.map((q, i) => [q.id, i]));
+      for (const q of incoming) {
+        const existingIdx = q.id != null ? byId.get(q.id) : undefined;
+        if (existingIdx == null) {
+          // new query — keep its id if free, else mint one
+          const id = (q.id != null && !byId.has(q.id)) ? q.id : ('s' + Date.now() + Math.random().toString(36).slice(2, 6));
+          const rec = { id, name: q.name, sql: q.sql, starred: !!q.starred };
+          byId.set(id, next.length); next.push(rec); added++;
+        } else {
+          const cur = next[existingIdx];
+          if (cur.sql === q.sql && cur.name === q.name) { skipped++; }
+          else {
+            // collision with differing content → keep both (import gets a new id)
+            const id = 's' + Date.now() + Math.random().toString(36).slice(2, 6);
+            next.push({ id, name: q.name + ' (imported)', sql: q.sql, starred: !!q.starred });
+            added++;
+          }
+        }
+      }
+      return next;
+    });
+    return { added, updated, skipped };
+  };
+  const [progress, setProgress] = React.useState(null);
+  const runTimers = React.useRef([]);
+  const clearRunTimers = () => { runTimers.current.forEach(clearTimeout); runTimers.current = []; };
+
+  const runQuery = () => {
+    clearRunTimers();
+    setRunning(true);
+    const final = pickResult(active.sql);
+    // Simulate ClickHouse streaming: partial rows arrive while rows/bytes-read
+    // counters climb toward an estimated total (X-ClickHouse-Progress). Showing
+    // partial data beats a blocking spinner. Replace with real streamed parse.
+    const TOTAL = 64_100_000;
+    const allRows = final.rows;
+    const steps = [0.12, 0.3, 0.52, 0.71, 0.88, 1];
+    // Demo timing only — "Slow query" tweak stretches it so streaming is easy
+    // to observe. No production meaning.
+    const stepMs = t.slowQuery ? 1500 : 280;
+    const fmt = (n) => n >= 1e6 ? (n/1e6).toFixed(1)+'M' : n >= 1e3 ? (n/1e3).toFixed(0)+'K' : String(n);
+    setResult({ ...final, rows: [], partial: true,
+      meta: { rows: 0, ms: 0, scanned: '0 B', scannedRows: '0' } });
+    setProgress({ read: 0, total: TOTAL, bytes: '0 B' });
+    steps.forEach((frac, i) => {
+      runTimers.current.push(setTimeout(() => {
+        const nRows = Math.round(allRows.length * frac);
+        const read = Math.round(TOTAL * frac);
+        const bytes = (frac * 2.41).toFixed(2) + ' GB';
+        setProgress({ read, total: TOTAL, bytes });
+        setResult({ ...final, rows: allRows.slice(0, nRows), partial: frac < 1,
+          meta: { rows: nRows, ms: Math.round(stepMs * (i + 1)), scanned: bytes, scannedRows: fmt(read) } });
+      }, stepMs * (i + 1)));
+    });
+    runTimers.current.push(setTimeout(() => {
+      setResult(final);
+      setRunning(false);
+      setProgress(null);
+    }, stepMs * (steps.length + 1)));
+  };
+  const cancelQuery = () => {
+    clearRunTimers();
+    setRunning(false);
+    setProgress(null);
+    // Keep whatever streamed in, but mark it cancelled (partial + a flag the
+    // results pane surfaces). Production: also issue KILL QUERY.
+    setResult(r => r ? { ...r, partial: false, cancelled: true } : r);
+  };
+
+  React.useEffect(() => {
+    const onKey = (e) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') {
+        e.preventDefault(); runQuery();
+      }
+      if ((e.metaKey || e.ctrlKey) && e.key === 't') {
+        e.preventDefault(); newTab();
+      }
+      if ((e.metaKey || e.ctrlKey) && e.key === 's') {
+        e.preventDefault(); setSaveSignal(s => s + 1);
+      }
+      if ((e.metaKey || e.ctrlKey) && e.shiftKey && (e.key === 'F' || e.key === 'f')) {
+        e.preventDefault(); formatCurrent();
+      }
+      if (e.key === '?' && !['INPUT','TEXTAREA'].includes(e.target.tagName)) {
+        setShortcutsOpen(o => !o);
+      }
+      if (e.key === 'Escape' && running) {
+        e.preventDefault(); cancelQuery();
+      }
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  });
+
+  // Editor / results split
+  const [editorPct, setEditorPct] = React.useState(45);
+  const splitRef = React.useRef(null);
+  const onSplitDrag = (e) => {
+    e.preventDefault();
+    const onMove = (ev) => {
+      const r = splitRef.current.getBoundingClientRect();
+      const pct = ((ev.clientY - r.top) / r.height) * 100;
+      setEditorPct(Math.max(15, Math.min(85, pct)));
+    };
+    const onUp = () => {
+      window.removeEventListener('mousemove', onMove);
+      window.removeEventListener('mouseup', onUp);
+    };
+    window.addEventListener('mousemove', onMove);
+    window.addEventListener('mouseup', onUp);
+  };
+
+  const [sidebarPx, setSidebarPx] = React.useState(248);
+  const onSidebarDrag = (e) => {
+    e.preventDefault();
+    const onMove = (ev) => setSidebarPx(Math.max(180, Math.min(420, ev.clientX)));
+    const onUp = () => {
+      window.removeEventListener('mousemove', onMove);
+      window.removeEventListener('mouseup', onUp);
+    };
+    window.addEventListener('mousemove', onMove);
+    window.addEventListener('mouseup', onUp);
+  };
+
+  return (
+    <div data-theme={dark ? 'dark' : 'light'} data-density={density} style={{
+      '--accent': accent,
+      width: '100%',
+      height: '100vh',
+      display: 'flex',
+      flexDirection: 'column',
+      background: 'var(--bg)',
+      color: 'var(--fg)',
+      fontFamily: 'var(--ui)',
+      overflow: 'hidden',
+    }}>
+      <AppHeader accent={accent} onShortcuts={() => setShortcutsOpen(true)} />
+
+      <div style={{ flex: 1, display: 'flex', minHeight: 0, overflow: 'hidden' }}>
+        {/* Sidebar */}
+        {sidebarVisible && (
+          <>
+            <div style={{
+              width: sidebarPx,
+              flexShrink: 0,
+              display: 'flex',
+              flexDirection: 'column',
+              background: 'var(--bg-side)',
+              borderRight: '1px solid var(--border)',
+              minHeight: 0,
+            }}>
+              <div style={{ flex: 1.4, overflow: 'hidden', display: 'flex', flexDirection: 'column', minHeight: 0 }}>
+                <SchemaTree accent={accent} onInsertColumn={insertColumn} />
+              </div>
+              <div style={{
+                height: 6, background: 'var(--border)', cursor: 'row-resize',
+                flexShrink: 0,
+              }} />
+              <div style={{ flex: 1, overflow: 'hidden', display: 'flex', flexDirection: 'column', minHeight: 0 }}>
+                <SavedHistoryPanel accent={accent} onLoadQuery={loadQuery}
+                  savedQueries={savedQueries}
+                  onRename={renameSaved} onDelete={deleteSaved} onToggleStar={toggleStar}
+                  onImport={importQueries} />
+              </div>
+            </div>
+            <div
+              onMouseDown={onSidebarDrag}
+              style={{ width: 4, cursor: 'col-resize', background: 'transparent', marginLeft: -2, zIndex: 1 }}
+            />
+          </>
+        )}
+
+        {/* Main column */}
+        <div ref={splitRef} style={{ flex: 1, display: 'flex', flexDirection: 'column', minWidth: 0, minHeight: 0 }}>
+          <QueryTabs
+            tabs={tabs}
+            activeId={activeId}
+            onSelect={setActiveId}
+            onClose={closeTab}
+            onNew={newTab}
+            accent={accent}
+          />
+          <EditorToolbar
+            accent={accent}
+            onRun={runQuery}
+            running={running}
+            onFormat={formatCurrent}
+            onShare={() => {}}
+            onSave={saveCurrentQuery}
+            currentName={active.name}
+            isSaved={!!active.savedId && !active.dirty}
+            saveSignal={saveSignal}
+          />
+          <div style={{ height: `${editorPct}%`, minHeight: 0, overflow: 'hidden' }}>
+            <SqlEditor
+              value={active.sql}
+              onChange={updateTabSql}
+              accent={accent}
+              fontSize={density === 'compact' ? 12.5 : 13}
+              density={density}
+            />
+          </div>
+          <div
+            onMouseDown={onSplitDrag}
+            style={{
+              height: 4,
+              background: 'var(--border)',
+              cursor: 'row-resize',
+              flexShrink: 0,
+              position: 'relative',
+            }}
+          >
+            <div style={{
+              position: 'absolute', top: 1, bottom: 1, left: '50%', transform: 'translateX(-50%)',
+              width: 28, background: 'var(--fg-faint)', opacity: .4, borderRadius: 1,
+            }} />
+          </div>
+          <div style={{ flex: 1, minHeight: 0, overflow: 'hidden' }}>
+            <ResultsPane result={result} accent={accent} density={density}
+              running={running} progress={progress} onCancel={cancelQuery} />
+          </div>
+        </div>
+      </div>
+
+      <ShortcutsModal open={shortcutsOpen} onClose={() => setShortcutsOpen(false)} />
+
+      <TweaksPanel title="Tweaks">
+        <TweakSection label="Theme">
+          <TweakRadio label="Mode" value={t.theme}
+            options={['dark', 'light']}
+            onChange={(v) => setTweak('theme', v)} />
+          <TweakColor label="Accent" value={t.accent}
+            onChange={(v) => setTweak('accent', v)} />
+          <div style={{ display: 'flex', gap: 6, padding: '2px 0' }}>
+            {['#FF6B35', '#F0A500', '#FFC700', '#3B82F6', '#10B981', '#EC4899'].map(c => (
+              <button
+                key={c}
+                onClick={() => setTweak('accent', c)}
+                style={{
+                  flex: 1, height: 22, border: 'none',
+                  background: c, borderRadius: 4, cursor: 'pointer',
+                  outline: t.accent === c ? '2px solid rgba(0,0,0,.5)' : 'none',
+                  outlineOffset: 1,
+                }}
+                title={c}
+              />
+            ))}
+          </div>
+        </TweakSection>
+        <TweakSection label="Layout">
+          <TweakRadio label="Density" value={t.density}
+            options={['compact', 'comfortable']}
+            onChange={(v) => setTweak('density', v)} />
+          <TweakToggle label="Sidebar" value={t.sidebar}
+            onChange={(v) => setTweak('sidebar', v)} />
+        </TweakSection>
+        <TweakSection label="Demo">
+          <TweakToggle label="Slow query (~9s)" value={t.slowQuery}
+            onChange={(v) => setTweak('slowQuery', v)} />
+        </TweakSection>
+      </TweaksPanel>
+    </div>
+  );
+}
+
+Object.assign(window, { App });
diff --git a/design/components.jsx b/design/components.jsx
new file mode 100644
index 0000000..16a05f2
--- /dev/null
+++ b/design/components.jsx
@@ -0,0 +1,1429 @@
+// components.jsx — schema browser, results pane, header, history/saved
+
+// ─── ICONS ────────────────────────────────────────────────────────────
+const Icon = {
+  chev: (props) => <svg width="10" height="10" viewBox="0 0 10 10" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" {...props}><path d="M3 2l3 3-3 3"/></svg>,
+  chevDown: (props) => <svg width="10" height="10" viewBox="0 0 10 10" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" {...props}><path d="M2 3l3 3 3-3"/></svg>,
+  database: (props) => <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.4" {...props}><ellipse cx="7" cy="3" rx="5" ry="1.6"/><path d="M2 3v8c0 .9 2.2 1.6 5 1.6s5-.7 5-1.6V3M2 7c0 .9 2.2 1.6 5 1.6s5-.7 5-1.6"/></svg>,
+  table: (props) => <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.4" {...props}><rect x="2" y="2.5" width="10" height="9" rx="1"/><path d="M2 5.5h10M2 8.5h10M5.5 5.5v6"/></svg>,
+  col: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.4" {...props}><rect x="2" y="2" width="8" height="8" rx="1"/><path d="M2 5h8M2 8h8"/></svg>,
+  play: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="currentColor" {...props}><path d="M3 2l7 4-7 4z"/></svg>,
+  star: (filled, props={}) => <svg width="12" height="12" viewBox="0 0 12 12" fill={filled ? 'currentColor' : 'none'} stroke="currentColor" strokeWidth="1.2" strokeLinejoin="round" {...props}><path d="M6 1.5l1.4 2.9 3.1.4-2.3 2.2.6 3.1L6 8.6l-2.8 1.5.6-3.1-2.3-2.2 3.1-.4z"/></svg>,
+  plus: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" {...props}><path d="M6 2v8M2 6h8"/></svg>,
+  close: (props) => <svg width="10" height="10" viewBox="0 0 10 10" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" {...props}><path d="M2 2l6 6M8 2l-6 6"/></svg>,
+  search: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" {...props}><circle cx="5" cy="5" r="3"/><path d="M7.5 7.5L10 10"/></svg>,
+  history: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" {...props}><path d="M2.5 5.5a3.5 3.5 0 1 1 1 2.5"/><path d="M2 3v2.5h2.5"/><path d="M6 3.5V6l1.5 1"/></svg>,
+  download: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" {...props}><path d="M6 1.5v6.5M3 5.5L6 8l3-2.5M2 10h8"/></svg>,
+  share: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" {...props}><circle cx="9" cy="3" r="1.5"/><circle cx="3" cy="6" r="1.5"/><circle cx="9" cy="9" r="1.5"/><path d="M4.3 5.3l3.4-1.6M4.3 6.7l3.4 1.6"/></svg>,
+  copy: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.4" {...props}><rect x="3.5" y="3.5" width="6.5" height="7" rx="1"/><path d="M2 8.5V2.5a1 1 0 0 1 1-1h6"/></svg>,
+  table2: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.4" {...props}><rect x="1.5" y="2" width="9" height="8" rx=".5"/><path d="M1.5 4.5h9M1.5 7h9M4.5 4.5v5"/></svg>,
+  chart: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" {...props}><path d="M2 10V7M5 10V4M8 10V6M11 10V2"/></svg>,
+  json: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" {...props}><path d="M4 1.5C2.5 1.5 2.5 3 2.5 4S2.5 5 1.5 6c1 1 1 2 1 2s0 1.5 1.5 1.5M8 1.5c1.5 0 1.5 1.5 1.5 2.5s0 1 1 2c-1 1-1 2-1 2s0 1.5-1.5 1.5"/></svg>,
+  sortAsc: (props) => <svg width="10" height="10" viewBox="0 0 10 10" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" {...props}><path d="M5 8V2M2.5 4.5L5 2l2.5 2.5"/></svg>,
+  sortDesc: (props) => <svg width="10" height="10" viewBox="0 0 10 10" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" {...props}><path d="M5 2v6M2.5 5.5L5 8l2.5-2.5"/></svg>,
+  filter: (props) => <svg width="11" height="11" viewBox="0 0 11 11" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" {...props}><path d="M1.5 2h8L6.5 6v3l-2 1V6z"/></svg>,
+  shortcuts: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" {...props}><rect x="1.5" y="3" width="9" height="6" rx="1"/><path d="M3.5 5h.01M6 5h.01M8.5 5h.01M3.5 7h5"/></svg>,
+  clock: (props) => <svg width="11" height="11" viewBox="0 0 11 11" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" {...props}><circle cx="5.5" cy="5.5" r="4"/><path d="M5.5 3.5V5.5L7 6.5"/></svg>,
+  rows: (props) => <svg width="11" height="11" viewBox="0 0 11 11" fill="none" stroke="currentColor" strokeWidth="1.4" {...props}><rect x="1.5" y="2" width="8" height="7" rx=".5"/><path d="M1.5 4.5h8M1.5 7h8"/></svg>,
+  bytes: (props) => <svg width="11" height="11" viewBox="0 0 11 11" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" {...props}><path d="M2 8.5V3.5L5.5 6 9 3.5v5"/></svg>,
+  bookmark: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" {...props}><path d="M3 1.5h6v9L6 8.5 3 10.5z"/></svg>,
+  pencil: (props) => <svg width="11" height="11" viewBox="0 0 11 11" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" strokeLinejoin="round" {...props}><path d="M7.5 1.8l1.7 1.7L4 8.7l-2.2.5.5-2.2z"/></svg>,
+  trash: (props) => <svg width="11" height="11" viewBox="0 0 11 11" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" strokeLinejoin="round" {...props}><path d="M2 3h7M4 3V1.8h3V3M3 3l.4 6.2h4.2L8 3"/></svg>,
+  check: (props) => <svg width="11" height="11" viewBox="0 0 11 11" fill="none" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round" {...props}><path d="M2 5.5L4.3 8 9 3"/></svg>,
+  upload: (props) => <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" {...props}><path d="M6 8.5V2M3 4.5L6 2l3 2.5M2 10h8"/></svg>,
+  logout: (props) => <svg width="13" height="13" viewBox="0 0 13 13" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" {...props}><path d="M5 11H2.5A.5.5 0 0 1 2 10.5v-8A.5.5 0 0 1 2.5 2H5M8.5 9L11 6.5 8.5 4M11 6.5H5"/></svg>,
+  spinner: ({ size = 13, ...props } = {}) => <svg width={size} height={size} viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" {...props}><path d="M8 1.5a6.5 6.5 0 1 0 6.5 6.5" opacity="0.9"/><path d="M8 1.5a6.5 6.5 0 0 1 6.5 6.5" opacity="0.2"/></svg>,
+  github: (props) => <svg width="15" height="15" viewBox="0 0 16 16" fill="currentColor" {...props}><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg>,
+};
+
+// ─── HEADER ───────────────────────────────────────────────────────────
+function AppHeader({ accent, onShortcuts }) {
+  const USER = { name: 'Demo User', email: 'demo@antalya.altinity.cloud', initials: 'DM', role: 'Read-only · demo' };
+  const [menuOpen, setMenuOpen] = React.useState(false);
+  const [confirmOut, setConfirmOut] = React.useState(false);
+  return (
+    <div className="app-header" style={{
+      height: 44,
+      display: 'flex',
+      alignItems: 'center',
+      padding: '0 14px',
+      background: 'var(--bg-header)',
+      borderBottom: '1px solid var(--border)',
+      gap: 14,
+      flexShrink: 0,
+    }}>
+      {/* Logo */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        <div style={{
+          width: 22, height: 22, borderRadius: 5,
+          background: `linear-gradient(135deg, ${accent}, color-mix(in oklab, ${accent} 70%, #000))`,
+          display: 'flex', alignItems: 'center', justifyContent: 'center',
+          color: 'white', fontWeight: 700, fontSize: 12,
+        }}>A</div>
+        <div style={{ fontSize: 13, fontWeight: 600, color: 'var(--fg)' }}>Altinity Play</div>
+        <div style={{ fontSize: 11, color: 'var(--fg-faint)', padding: '2px 6px',
+          background: 'var(--bg-chip)', borderRadius: 4, fontFamily: 'var(--mono)' }}>
+          antalya.demo
+        </div>
+      </div>
+
+      <div style={{ flex: 1 }} />
+
+      {/* Connection status */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 6, fontSize: 11.5, color: 'var(--fg-mute)', whiteSpace: 'nowrap', flexShrink: 0 }}>
+        <div style={{ width: 7, height: 7, borderRadius: 4, background: '#22c55e', boxShadow: '0 0 6px #22c55e', flexShrink: 0 }} />
+        <span style={{ fontFamily: 'var(--mono)' }}>ClickHouse 26.3.10</span>
+      </div>
+
+      <a className="hd-btn" href="https://github.com/Altinity/ClickHouse" target="_blank" rel="noopener noreferrer" title="View on GitHub">
+        <Icon.github />
+      </a>
+
+      <button className="hd-btn" onClick={onShortcuts} title="Keyboard shortcuts (?)">
+        <Icon.shortcuts />
+      </button>
+
+      {/* User menu */}
+      <div style={{ position: 'relative' }}>
+        <button
+          onClick={() => setMenuOpen(o => !o)}
+          title={USER.email}
+          style={{
+            display: 'flex', alignItems: 'center', gap: 6, height: 30, padding: '0 4px',
+            border: 'none', background: 'transparent', cursor: 'pointer', borderRadius: 6,
+          }}
+          onMouseEnter={(e) => e.currentTarget.style.background = 'var(--bg-hover)'}
+          onMouseLeave={(e) => e.currentTarget.style.background = 'transparent'}
+        >
+          <span style={{ width: 24, height: 24, borderRadius: 12, background: 'var(--bg-chip)',
+            display: 'flex', alignItems: 'center', justifyContent: 'center',
+            fontSize: 10.5, fontWeight: 600, color: 'var(--fg-mute)' }}>{USER.initials}</span>
+          <span style={{ color: 'var(--fg-faint)', display: 'flex' }}><Icon.chevDown /></span>
+        </button>
+
+        {menuOpen && (
+          <>
+            <div onClick={() => setMenuOpen(false)} style={{ position: 'fixed', inset: 0, zIndex: 40 }} />
+            <div style={{
+              position: 'absolute', top: 'calc(100% + 6px)', right: 0, zIndex: 41,
+              width: 230, background: 'var(--bg-modal)', border: '1px solid var(--border)',
+              borderRadius: 9, boxShadow: '0 12px 36px rgba(0,0,0,.35)', overflow: 'hidden',
+            }}>
+              <div style={{ display: 'flex', alignItems: 'center', gap: 10, padding: '12px 13px', borderBottom: '1px solid var(--border-faint)' }}>
+                <span style={{ width: 32, height: 32, borderRadius: 16, background: accent,
+                  display: 'flex', alignItems: 'center', justifyContent: 'center',
+                  fontSize: 12, fontWeight: 700, color: '#fff', flexShrink: 0 }}>{USER.initials}</span>
+                <div style={{ minWidth: 0 }}>
+                  <div style={{ fontSize: 12.5, fontWeight: 600, color: 'var(--fg)', whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' }}>{USER.name}</div>
+                  <div style={{ fontSize: 11, color: 'var(--fg-faint)', whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' }}>{USER.email}</div>
+                </div>
+              </div>
+              <div style={{ padding: '6px 13px', fontSize: 10.5, color: 'var(--fg-faint)', borderBottom: '1px solid var(--border-faint)', fontFamily: 'var(--mono)' }}>
+                {USER.role}
+              </div>
+              <div style={{ padding: 5 }}>
+                <button
+                  onClick={() => { setMenuOpen(false); setConfirmOut(true); }}
+                  style={{
+                    width: '100%', display: 'flex', alignItems: 'center', gap: 8,
+                    padding: '8px 9px', border: 'none', background: 'transparent',
+                    color: '#ef4444', fontSize: 12, fontWeight: 500, fontFamily: 'inherit',
+                    cursor: 'pointer', borderRadius: 6, textAlign: 'left', whiteSpace: 'nowrap',
+                  }}
+                  onMouseEnter={(e) => e.currentTarget.style.background = 'color-mix(in oklab, #ef4444 12%, transparent)'}
+                  onMouseLeave={(e) => e.currentTarget.style.background = 'transparent'}
+                ><Icon.logout /> Log out</button>
+              </div>
+            </div>
+          </>
+        )}
+      </div>
+
+      {confirmOut && (
+        <div onClick={() => setConfirmOut(false)} style={{
+          position: 'fixed', inset: 0, zIndex: 120,
+          background: 'rgba(0,0,0,.5)', backdropFilter: 'blur(4px)',
+          display: 'flex', alignItems: 'center', justifyContent: 'center',
+        }}>
+          <div onClick={e => e.stopPropagation()} style={{
+            width: 340, background: 'var(--bg-modal)', borderRadius: 11,
+            border: '1px solid var(--border)', boxShadow: '0 20px 60px rgba(0,0,0,.45)',
+            padding: '20px 22px',
+          }}>
+            <div style={{ fontSize: 14.5, fontWeight: 600, color: 'var(--fg)', marginBottom: 6 }}>Log out?</div>
+            <div style={{ fontSize: 12.5, color: 'var(--fg-mute)', lineHeight: 1.5, marginBottom: 18 }}>
+              You'll be signed out of <span style={{ color: 'var(--fg)' }}>{USER.email}</span>. Unsaved query tabs stay in this browser; saved queries are kept.
+            </div>
+            <div style={{ display: 'flex', justifyContent: 'flex-end', gap: 8 }}>
+              <button onClick={() => setConfirmOut(false)} style={{
+                height: 30, padding: '0 14px', border: '1px solid var(--border)', borderRadius: 6,
+                background: 'transparent', color: 'var(--fg)', fontSize: 12, fontWeight: 500,
+                fontFamily: 'inherit', cursor: 'pointer',
+              }}>Cancel</button>
+              <button onClick={() => setConfirmOut(false)} style={{
+                height: 30, padding: '0 14px', border: 'none', borderRadius: 6,
+                background: '#ef4444', color: '#fff', fontSize: 12, fontWeight: 600,
+                fontFamily: 'inherit', cursor: 'pointer', whiteSpace: 'nowrap',
+              }}>Log out</button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ─── SCHEMA TREE ──────────────────────────────────────────────────────
+function SchemaTree({ accent, onInsertColumn }) {
+  const [tree, setTree] = React.useState(SCHEMA);
+  const [expandedTables, setExpandedTables] = React.useState(new Set(['ontime']));
+  const [filter, setFilter] = React.useState('');
+
+  const toggleDb = (name) => {
+    setTree(t => t.map(db => db.name === name ? { ...db, expanded: !db.expanded } : db));
+  };
+  const toggleTable = (name) => {
+    setExpandedTables(s => {
+      const n = new Set(s);
+      if (n.has(name)) n.delete(name); else n.add(name);
+      return n;
+    });
+  };
+
+  const matches = (s) => !filter || s.toLowerCase().includes(filter.toLowerCase());
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
+      <div style={{
+        padding: '8px 10px',
+        borderBottom: '1px solid var(--border)',
+        display: 'flex', alignItems: 'center', gap: 6,
+      }}>
+        <div style={{ flex: 1, position: 'relative' }}>
+          <span style={{ position: 'absolute', left: 8, top: '50%', transform: 'translateY(-50%)', color: 'var(--fg-faint)' }}>
+            <Icon.search />
+          </span>
+          <input
+            value={filter}
+            onChange={(e) => setFilter(e.target.value)}
+            placeholder="Search tables, columns…"
+            style={{
+              width: '100%',
+              height: 26,
+              padding: '0 8px 0 26px',
+              background: 'var(--bg-input)',
+              border: '1px solid var(--border)',
+              borderRadius: 5,
+              color: 'var(--fg)',
+              fontSize: 11.5,
+              outline: 'none',
+              fontFamily: 'inherit',
+            }}
+          />
+        </div>
+      </div>
+      <div style={{ flex: 1, overflow: 'auto', padding: '4px 0' }}>
+        {tree.map(db => (
+          <div key={db.name}>
+            <TreeRow
+              indent={0}
+              icon={<Icon.database style={{ color: 'var(--fg-mute)' }} />}
+              chevron={db.expanded ? <Icon.chevDown /> : <Icon.chev />}
+              onClick={() => toggleDb(db.name)}
+              label={db.name}
+              meta={`${db.children.length}`}
+              bold
+            />
+            {db.expanded && db.children.map(tb => {
+              const tkey = `${db.name}.${tb.name}`;
+              const open = expandedTables.has(tb.name);
+              const tableMatch = matches(tb.name);
+              const cols = tb.columns || [];
+              const visibleCols = cols.filter(c => matches(c.name));
+              if (filter && !tableMatch && visibleCols.length === 0) return null;
+              return (
+                <div key={tkey}>
+                  <TreeRow
+                    indent={1}
+                    icon={<Icon.table style={{ color: accent }} />}
+                    chevron={cols.length ? (open ? <Icon.chevDown /> : <Icon.chev />) : null}
+                    onClick={() => cols.length && toggleTable(tb.name)}
+                    label={tb.name}
+                    meta={tb.rows}
+                    highlight={filter && tableMatch}
+                  />
+                  {(open || (filter && visibleCols.length > 0)) && visibleCols.map(c => (
+                    <TreeRow
+                      key={c.name}
+                      indent={2}
+                      icon={<Icon.col style={{ color: 'var(--fg-faint)' }} />}
+                      label={c.name}
+                      meta={c.type}
+                      mono
+                      onClick={() => onInsertColumn?.(c.name)}
+                      highlight={filter && matches(c.name)}
+                      small
+                    />
+                  ))}
+                </div>
+              );
+            })}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function TreeRow({ indent, icon, chevron, label, meta, bold, mono, highlight, onClick, small }) {
+  const [hover, setHover] = React.useState(false);
+  return (
+    <div
+      onClick={onClick}
+      onMouseEnter={() => setHover(true)}
+      onMouseLeave={() => setHover(false)}
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 6,
+        height: small ? 22 : 24,
+        padding: `0 10px 0 ${10 + indent * 14}px`,
+        cursor: 'pointer',
+        background: hover ? 'var(--bg-hover)' : (highlight ? 'var(--bg-highlight)' : 'transparent'),
+        fontSize: small ? 11 : 12,
+        color: bold ? 'var(--fg)' : 'var(--fg-mute)',
+        fontWeight: bold ? 600 : 400,
+        fontFamily: mono ? 'var(--mono)' : 'inherit',
+        userSelect: 'none',
+      }}
+    >
+      <span style={{ width: 10, color: 'var(--fg-faint)', display: 'flex' }}>
+        {chevron}
+      </span>
+      <span style={{ display: 'flex', alignItems: 'center' }}>{icon}</span>
+      <span style={{ flex: 1, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>{label}</span>
+      {meta && <span style={{ fontSize: 10, color: 'var(--fg-faint)', fontFamily: 'var(--mono)', flexShrink: 0 }}>{meta}</span>}
+    </div>
+  );
+}
+
+// ─── SAVED QUERIES + HISTORY ──────────────────────────────────────────
+function SavedHistoryPanel({ accent, onLoadQuery, savedQueries, onRename, onDelete, onToggleStar, onImport }) {
+  const [tab, setTab] = React.useState('saved');
+  const [toast, setToast] = React.useState(null);
+  const fileRef = React.useRef(null);
+  const list = savedQueries || SAVED_QUERIES;
+
+  const flash = (msg) => { setToast(msg); setTimeout(() => setToast(null), 3200); };
+
+  const exportJson = () => {
+    const envelope = {
+      format: 'altinity-sql-browser/saved-queries',
+      version: 1,
+      exportedAt: new Date().toISOString(),
+      queries: list.map(q => ({
+        id: q.id, name: q.name, sql: q.sql, starred: !!q.starred,
+        createdAt: q.createdAt || null, updatedAt: q.updatedAt || null,
+      })),
+    };
+    const blob = new Blob([JSON.stringify(envelope, null, 2)], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = `sql-browser-queries-${new Date().toISOString().slice(0, 10)}.json`;
+    document.body.appendChild(a); a.click(); a.remove();
+    URL.revokeObjectURL(url);
+    flash(`Exported ${list.length} ${list.length === 1 ? 'query' : 'queries'}`);
+  };
+
+  const importJson = (e) => {
+    const file = e.target.files?.[0];
+    e.target.value = ''; // allow re-importing same file
+    if (!file) return;
+    const reader = new FileReader();
+    reader.onload = () => {
+      try {
+        const data = JSON.parse(reader.result);
+        if (data?.format !== 'altinity-sql-browser/saved-queries' || !Array.isArray(data.queries)) {
+          flash('✕ Not a valid saved-queries file'); return;
+        }
+        if (typeof data.version === 'number' && data.version > 1) {
+          flash('✕ File is from a newer version'); return;
+        }
+        const clean = data.queries
+          .filter(q => q && typeof q.sql === 'string' && typeof q.name === 'string')
+          .slice(0, 1000);
+        if (!clean.length) { flash('✕ No valid queries in file'); return; }
+        const summary = onImport?.(clean);
+        if (summary) flash(`Added ${summary.added} · updated ${summary.updated} · skipped ${summary.skipped}`);
+      } catch {
+        flash('✕ Could not parse JSON');
+      }
+    };
+    reader.readAsText(file);
+  };
+
+  const ioBtn = {
+    flex: 1, height: 24, border: '1px solid var(--border)', borderRadius: 5,
+    background: 'transparent', color: 'var(--fg-mute)', fontSize: 11,
+    fontFamily: 'inherit', cursor: 'pointer', display: 'flex',
+    alignItems: 'center', justifyContent: 'center', gap: 5,
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
+      <div style={{ display: 'flex', borderBottom: '1px solid var(--border)' }}>
+        {['saved', 'history'].map(t => (
+          <button
+            key={t}
+            onClick={() => setTab(t)}
+            style={{
+              flex: 1,
+              height: 30,
+              border: 'none',
+              background: 'transparent',
+              color: tab === t ? 'var(--fg)' : 'var(--fg-mute)',
+              fontSize: 11.5,
+              fontWeight: 500,
+              fontFamily: 'inherit',
+              cursor: 'pointer',
+              borderBottom: tab === t ? `2px solid ${accent}` : '2px solid transparent',
+              textTransform: 'capitalize',
+            }}
+          >{t === 'saved' ? `★ Saved${list.length ? ` · ${list.length}` : ''}` : '⏱ History'}</button>
+        ))}
+      </div>
+      {tab === 'saved' && (
+        <input ref={fileRef} type="file" accept="application/json,.json" onChange={importJson} style={{ display: 'none' }} />
+      )}
+      <div style={{ flex: 1, overflow: 'auto' }}>
+        {tab === 'saved' && list.length === 0 && (
+          <div style={{ padding: '20px 14px', fontSize: 11.5, color: 'var(--fg-faint)', lineHeight: 1.5, textAlign: 'center' }}>
+            No saved queries yet.<br />Write a query and hit <span style={{ color: 'var(--fg-mute)' }}>Save</span>, or <span style={{ color: 'var(--fg-mute)' }}>Import</span> a file.
+          </div>
+        )}
+        {tab === 'saved' && list.map(q => (
+          <SavedItem key={q.id} q={q} accent={accent}
+            onLoad={() => onLoadQuery(q)}
+            onRename={onRename} onDelete={onDelete} onToggleStar={onToggleStar} />
+        ))}
+        {tab === 'history' && HISTORY.map(h => (
+          <HistoryItem key={h.id} h={h} accent={accent} onLoad={() => onLoadQuery({ name: 'From history', sql: h.sql })} />
+        ))}
+      </div>
+      {tab === 'saved' && toast && (
+        <div style={{
+          padding: '6px 10px', fontSize: 10.5, color: 'var(--fg-mute)',
+          background: 'var(--bg-chip)', borderTop: '1px solid var(--border-faint)',
+          fontFamily: 'var(--mono)',
+        }}>{toast}</div>
+      )}
+      {tab === 'saved' && (
+        <div style={{ display: 'flex', gap: 6, padding: '6px 10px', borderTop: '1px solid var(--border)', flexShrink: 0 }}>
+          <button style={ioBtn} onClick={exportJson} disabled={!list.length}
+            title="Download all saved queries as JSON"
+            onMouseEnter={(e) => { if (list.length) { e.currentTarget.style.background = 'var(--bg-hover)'; e.currentTarget.style.color = 'var(--fg)'; } }}
+            onMouseLeave={(e) => { e.currentTarget.style.background = 'transparent'; e.currentTarget.style.color = 'var(--fg-mute)'; }}
+          ><Icon.download /> Export</button>
+          <button style={ioBtn} onClick={() => fileRef.current?.click()}
+            title="Import saved queries from a JSON file"
+            onMouseEnter={(e) => { e.currentTarget.style.background = 'var(--bg-hover)'; e.currentTarget.style.color = 'var(--fg)'; }}
+            onMouseLeave={(e) => { e.currentTarget.style.background = 'transparent'; e.currentTarget.style.color = 'var(--fg-mute)'; }}
+          ><Icon.upload /> Import</button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function SavedItem({ q, accent, onLoad, onRename, onDelete, onToggleStar }) {
+  const [hover, setHover] = React.useState(false);
+  const [editing, setEditing] = React.useState(false);
+  const [name, setName] = React.useState(q.name);
+  const inputRef = React.useRef(null);
+  React.useEffect(() => { setName(q.name); }, [q.name]);
+
+  const startEdit = (e) => {
+    e.stopPropagation();
+    setEditing(true);
+    requestAnimationFrame(() => { inputRef.current?.focus(); inputRef.current?.select(); });
+  };
+  const commit = () => {
+    setEditing(false);
+    const n = name.trim();
+    if (n && n !== q.name) onRename?.(q.id, n); else setName(q.name);
+  };
+
+  const actionBtn = {
+    width: 20, height: 20, borderRadius: 4, border: 'none', padding: 0,
+    background: 'transparent', color: 'var(--fg-faint)', cursor: 'pointer',
+    display: 'flex', alignItems: 'center', justifyContent: 'center',
+  };
+
+  return (
+    <div
+      onClick={() => !editing && onLoad()}
+      onMouseEnter={() => setHover(true)}
+      onMouseLeave={() => setHover(false)}
+      style={{
+        padding: '8px 10px',
+        cursor: editing ? 'default' : 'pointer',
+        background: hover ? 'var(--bg-hover)' : 'transparent',
+        borderBottom: '1px solid var(--border-faint)',
+        position: 'relative',
+      }}
+    >
+      <div style={{ display: 'flex', alignItems: 'center', gap: 6, marginBottom: 3 }}>
+        <span
+          onClick={(e) => { e.stopPropagation(); onToggleStar?.(q.id); }}
+          style={{ color: q.starred ? accent : 'var(--fg-faint)', display: 'flex', cursor: 'pointer', flexShrink: 0 }}
+          title={q.starred ? 'Unstar' : 'Star'}
+        >
+          {Icon.star(q.starred)}
+        </span>
+        {editing ? (
+          <input
+            ref={inputRef}
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+            onClick={(e) => e.stopPropagation()}
+            onBlur={commit}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') { e.preventDefault(); commit(); }
+              if (e.key === 'Escape') { setName(q.name); setEditing(false); }
+            }}
+            style={{
+              flex: 1, minWidth: 0, height: 20, padding: '0 5px',
+              background: 'var(--bg-input)', border: `1px solid ${accent}`,
+              borderRadius: 4, color: 'var(--fg)', fontSize: 12, fontWeight: 500,
+              outline: 'none', fontFamily: 'inherit',
+            }}
+          />
+        ) : (
+          <span style={{ fontSize: 12, fontWeight: 500, color: 'var(--fg)', flex: 1, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+            {q.name}
+          </span>
+        )}
+        {hover && !editing && (
+          <div style={{ display: 'flex', gap: 1, flexShrink: 0 }}>
+            <button style={actionBtn} title="Rename"
+              onClick={startEdit}
+              onMouseEnter={(e) => { e.currentTarget.style.background = 'var(--bg-chip)'; e.currentTarget.style.color = 'var(--fg)'; }}
+              onMouseLeave={(e) => { e.currentTarget.style.background = 'transparent'; e.currentTarget.style.color = 'var(--fg-faint)'; }}
+            ><Icon.pencil /></button>
+            <button style={actionBtn} title="Delete"
+              onClick={(e) => { e.stopPropagation(); onDelete?.(q.id); }}
+              onMouseEnter={(e) => { e.currentTarget.style.background = 'var(--bg-chip)'; e.currentTarget.style.color = '#ef4444'; }}
+              onMouseLeave={(e) => { e.currentTarget.style.background = 'transparent'; e.currentTarget.style.color = 'var(--fg-faint)'; }}
+            ><Icon.trash /></button>
+          </div>
+        )}
+      </div>
+      <div style={{
+        fontSize: 10.5,
+        fontFamily: 'var(--mono)',
+        color: 'var(--fg-faint)',
+        whiteSpace: 'nowrap',
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+        paddingLeft: 18,
+      }}>
+        {q.sql.split('\n')[0]}
+      </div>
+    </div>
+  );
+}
+
+function HistoryItem({ h, accent, onLoad }) {
+  const [hover, setHover] = React.useState(false);
+  return (
+    <div
+      onClick={onLoad}
+      onMouseEnter={() => setHover(true)}
+      onMouseLeave={() => setHover(false)}
+      style={{
+        padding: '8px 10px',
+        cursor: 'pointer',
+        background: hover ? 'var(--bg-hover)' : 'transparent',
+        borderBottom: '1px solid var(--border-faint)',
+      }}
+    >
+      <div style={{
+        fontSize: 11,
+        fontFamily: 'var(--mono)',
+        color: 'var(--fg)',
+        whiteSpace: 'nowrap',
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+        marginBottom: 3,
+      }}>
+        {h.sql}
+      </div>
+      <div style={{ display: 'flex', gap: 10, fontSize: 10, color: 'var(--fg-faint)', fontFamily: 'var(--mono)' }}>
+        <span>{h.when}</span>
+        <span>{h.rows} rows</span>
+        <span>{h.ms} ms</span>
+      </div>
+    </div>
+  );
+}
+
+// ─── QUERY TABS ───────────────────────────────────────────────────────
+function QueryTabs({ tabs, activeId, onSelect, onClose, onNew, accent }) {
+  return (
+    <div className="qtabs" style={{
+      display: 'flex',
+      alignItems: 'center',
+      height: 34,
+      background: 'var(--bg-tabs)',
+      borderBottom: '1px solid var(--border)',
+      flexShrink: 0,
+      overflow: 'hidden',
+    }}>
+      <div style={{ display: 'flex', flex: 1, overflow: 'auto', height: '100%' }}>
+        {tabs.map(t => {
+          const active = t.id === activeId;
+          return (
+            <div
+              key={t.id}
+              onClick={() => onSelect(t.id)}
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: 8,
+                padding: '0 8px 0 12px',
+                height: '100%',
+                background: active ? 'var(--bg-editor)' : 'transparent',
+                borderRight: '1px solid var(--border)',
+                cursor: 'pointer',
+                fontSize: 11.5,
+                color: active ? 'var(--fg)' : 'var(--fg-mute)',
+                fontWeight: active ? 500 : 400,
+                position: 'relative',
+                whiteSpace: 'nowrap',
+                minWidth: 100,
+              }}
+            >
+              {active && <div style={{
+                position: 'absolute', top: 0, left: 0, right: 0, height: 2, background: accent
+              }} />}
+              <span style={{ flex: 1, overflow: 'hidden', textOverflow: 'ellipsis' }}>{t.name}</span>
+              {t.dirty && <span style={{
+                width: 5, height: 5, borderRadius: 3, background: 'var(--fg-mute)'
+              }} />}
+              {tabs.length > 1 && (
+                <button
+                  onClick={(e) => { e.stopPropagation(); onClose(t.id); }}
+                  style={{
+                    width: 16, height: 16, borderRadius: 3, padding: 0,
+                    border: 'none', background: 'transparent', color: 'var(--fg-faint)',
+                    cursor: 'pointer', display: 'flex', alignItems: 'center', justifyContent: 'center',
+                  }}
+                  onMouseEnter={(e) => { e.currentTarget.style.background = 'var(--bg-hover)'; e.currentTarget.style.color = 'var(--fg)'; }}
+                  onMouseLeave={(e) => { e.currentTarget.style.background = 'transparent'; e.currentTarget.style.color = 'var(--fg-faint)'; }}
+                ><Icon.close /></button>
+              )}
+            </div>
+          );
+        })}
+      </div>
+      <button
+        onClick={onNew}
+        style={{
+          width: 32, height: '100%', border: 'none', background: 'transparent',
+          color: 'var(--fg-mute)', cursor: 'pointer',
+          display: 'flex', alignItems: 'center', justifyContent: 'center',
+          borderLeft: '1px solid var(--border)',
+        }}
+        onMouseEnter={(e) => e.currentTarget.style.color = 'var(--fg)'}
+        onMouseLeave={(e) => e.currentTarget.style.color = 'var(--fg-mute)'}
+        title="New query (⌘T)"
+      ><Icon.plus /></button>
+    </div>
+  );
+}
+
+// ─── EDITOR TOOLBAR ───────────────────────────────────────────────────
+function EditorToolbar({ accent, onRun, running, onFormat, onShare, onSave, currentName, isSaved, saveSignal }) {
+  const [saveOpen, setSaveOpen] = React.useState(false);
+  const [name, setName] = React.useState(currentName || '');
+  const inputRef = React.useRef(null);
+
+  const openSave = () => {
+    setName(currentName && currentName !== 'Untitled query' ? currentName : '');
+    setSaveOpen(true);
+    requestAnimationFrame(() => inputRef.current?.focus());
+  };
+  const commit = () => {
+    const n = name.trim();
+    if (n) { onSave(n); setSaveOpen(false); }
+  };
+
+  // ⌘S from the app raises saveSignal — open the popover (skip initial mount).
+  const firstSignal = React.useRef(true);
+  React.useEffect(() => {
+    if (firstSignal.current) { firstSignal.current = false; return; }
+    openSave();
+  }, [saveSignal]);
+
+  return (
+    <div style={{
+      height: 38,
+      display: 'flex',
+      alignItems: 'center',
+      padding: '0 10px',
+      gap: 8,
+      background: 'var(--bg-toolbar)',
+      borderBottom: '1px solid var(--border)',
+      flexShrink: 0,
+      position: 'relative',
+    }}>
+      <button
+        onClick={onRun}
+        disabled={running}
+        style={{
+          height: 26,
+          padding: '0 10px 0 8px',
+          background: accent,
+          color: 'white',
+          border: 'none',
+          borderRadius: 5,
+          fontSize: 11.5,
+          fontWeight: 600,
+          cursor: running ? 'wait' : 'pointer',
+          display: 'flex',
+          alignItems: 'center',
+          gap: 6,
+          fontFamily: 'inherit',
+          opacity: running ? 0.7 : 1,
+          flexShrink: 0,
+        }}
+      >
+        <Icon.play /> {running ? 'Running…' : 'Run'} <kbd style={{
+          fontSize: 9.5, opacity: .8, padding: '1px 4px', background: 'rgba(0,0,0,.2)',
+          borderRadius: 3, marginLeft: 4, fontFamily: 'var(--mono)'
+        }}>⌘↵</kbd>
+      </button>
+
+      <button className="tb-btn" onClick={onFormat} title="Format SQL (⌘⇧F)">
+        <span style={{ fontFamily: 'var(--mono)', fontSize: 11.5 }}>{ '{ }' }</span> Format
+      </button>
+
+      {/* Save + popover */}
+      <div style={{ position: 'relative' }}>
+        <button className="tb-btn" onClick={() => saveOpen ? setSaveOpen(false) : openSave()}
+          style={isSaved ? { color: accent } : undefined} title="Save query (⌘S)">
+          <Icon.bookmark /> {isSaved ? 'Saved' : 'Save'}
+        </button>
+        {saveOpen && (
+          <>
+            <div onClick={() => setSaveOpen(false)} style={{ position: 'fixed', inset: 0, zIndex: 30 }} />
+            <div style={{
+              position: 'absolute', top: 'calc(100% + 6px)', left: 0, zIndex: 31,
+              width: 260, padding: 12, background: 'var(--bg-modal)',
+              border: '1px solid var(--border)', borderRadius: 9,
+              boxShadow: '0 12px 36px rgba(0,0,0,.35)',
+            }}>
+              <div style={{ fontSize: 10, fontWeight: 600, letterSpacing: '.05em', textTransform: 'uppercase',
+                color: 'var(--fg-faint)', marginBottom: 7 }}>Save query as</div>
+              <input
+                ref={inputRef}
+                value={name}
+                onChange={(e) => setName(e.target.value)}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter') { e.preventDefault(); commit(); }
+                  if (e.key === 'Escape') setSaveOpen(false);
+                }}
+                placeholder="e.g. Worst-delay carriers"
+                style={{
+                  width: '100%', height: 30, padding: '0 9px', boxSizing: 'border-box',
+                  background: 'var(--bg-input)', border: '1px solid var(--border)',
+                  borderRadius: 6, color: 'var(--fg)', fontSize: 12, outline: 'none',
+                  fontFamily: 'inherit',
+                }}
+              />
+              <div style={{ display: 'flex', justifyContent: 'flex-end', gap: 6, marginTop: 10 }}>
+                <button className="tb-btn" onClick={() => setSaveOpen(false)}>Cancel</button>
+                <button
+                  onClick={commit}
+                  disabled={!name.trim()}
+                  style={{
+                    height: 26, padding: '0 12px', border: 'none', borderRadius: 5,
+                    background: accent, color: 'white', fontSize: 11.5, fontWeight: 600,
+                    fontFamily: 'inherit', cursor: name.trim() ? 'pointer' : 'not-allowed',
+                    opacity: name.trim() ? 1 : 0.5,
+                  }}
+                >Save</button>
+              </div>
+            </div>
+          </>
+        )}
+      </div>
+
+      <div style={{ flex: 1 }} />
+
+      <button className="tb-btn" onClick={onShare}>
+        <Icon.share /> Share
+      </button>
+
+      <select className="tb-select">
+        <option>Format: TSV</option>
+        <option>Format: CSV</option>
+        <option>Format: JSON</option>
+        <option>Format: Pretty</option>
+      </select>
+    </div>
+  );
+}
+
+// ─── RESULTS ──────────────────────────────────────────────────────────
+function ResultsPane({ result, accent, density, running, progress, onCancel }) {
+  const [view, setView] = React.useState('table');
+  const [sort, setSort] = React.useState({ col: null, dir: 'asc' });
+
+  const sorted = React.useMemo(() => {
+    if (!result || sort.col == null) return result?.rows;
+    const idx = sort.col;
+    const r = [...result.rows].sort((a, b) => {
+      const av = a[idx], bv = b[idx];
+      if (typeof av === 'number') return sort.dir === 'asc' ? av - bv : bv - av;
+      return sort.dir === 'asc'
+        ? String(av).localeCompare(String(bv))
+        : String(bv).localeCompare(String(av));
+    });
+    return r;
+  }, [result, sort]);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', height: '100%', minHeight: 0 }}>
+      {/* Results toolbar */}
+      <div style={{
+        height: 36,
+        display: 'flex',
+        alignItems: 'center',
+        padding: '0 10px',
+        gap: 10,
+        background: 'var(--bg-toolbar)',
+        borderBottom: '1px solid var(--border)',
+        flexShrink: 0,
+      }}>
+        <div style={{ display: 'flex', background: 'var(--bg-chip)', borderRadius: 5, padding: 2 }}>
+          {[
+            { id: 'table', label: 'Table', icon: <Icon.table2 /> },
+            { id: 'chart', label: 'Chart', icon: <Icon.chart /> },
+            { id: 'json', label: 'JSON', icon: <Icon.json /> },
+          ].map(v => (
+            <button
+              key={v.id}
+              onClick={() => setView(v.id)}
+              style={{
+                height: 22,
+                padding: '0 10px',
+                border: 'none',
+                background: view === v.id ? 'var(--bg-editor)' : 'transparent',
+                color: view === v.id ? 'var(--fg)' : 'var(--fg-mute)',
+                fontSize: 11,
+                fontWeight: view === v.id ? 500 : 400,
+                cursor: 'pointer',
+                borderRadius: 4,
+                display: 'flex',
+                alignItems: 'center',
+                gap: 5,
+                fontFamily: 'inherit',
+                boxShadow: view === v.id ? '0 1px 2px rgba(0,0,0,.15)' : 'none',
+              }}
+            >{v.icon}{v.label}</button>
+          ))}
+        </div>
+
+        <div style={{ flex: 1 }} />
+
+        {running ? (
+          <>
+            <LiveRunStats progress={progress} accent={accent} />
+            <button className="tb-btn" onClick={onCancel} title="Cancel query (Esc)"
+              style={{ color: 'var(--fg-mute)' }}
+              onMouseEnter={(e) => { e.currentTarget.style.background = 'color-mix(in oklab, #ef4444 14%, transparent)'; e.currentTarget.style.color = '#ef4444'; }}
+              onMouseLeave={(e) => { e.currentTarget.style.background = 'transparent'; e.currentTarget.style.color = 'var(--fg-mute)'; }}
+            ><Icon.close /> Cancel <kbd style={{
+              fontSize: 9.5, opacity: .7, padding: '1px 4px', background: 'var(--bg-chip)',
+              borderRadius: 3, fontFamily: 'var(--mono)', marginLeft: 2 }}>Esc</kbd></button>
+          </>
+        ) : result ? (
+          <>
+            {result.cancelled && (
+              <span style={{ fontSize: 10.5, color: '#ef4444', fontFamily: 'var(--mono)',
+                padding: '2px 7px', borderRadius: 4, background: 'color-mix(in oklab, #ef4444 12%, transparent)' }}>
+                Cancelled · partial
+              </span>
+            )}
+            <Stat icon={<Icon.clock />} value={`${result.meta.ms} ms`} />
+            <Stat icon={<Icon.rows />} value={`${result.meta.rows} rows`} />
+            <Stat icon={<Icon.bytes />} value={result.meta.scanned} sub={`${result.meta.scannedRows} scanned`} />
+            <button className="tb-btn"><Icon.copy /> Copy</button>
+            <button className="tb-btn"><Icon.download /> Export</button>
+          </>
+        ) : null}
+      </div>
+
+      <div style={{ flex: 1, overflow: 'hidden', minHeight: 0, position: 'relative' }}>
+        {/* Streaming progress strip atop the partial table */}
+        {running && (
+          <div style={{ position: 'absolute', top: 0, left: 0, right: 0, height: 2, zIndex: 2,
+            background: 'var(--bg-chip)', overflow: 'hidden' }}>
+            {progress && progress.total ? (
+              <div style={{ height: '100%', width: `${Math.min(100, (progress.read / progress.total) * 100)}%`,
+                background: accent, transition: 'width .3s linear' }} />
+            ) : (
+              <div className="runsweep" style={{ height: '100%', width: '40%', background: accent }} />
+            )}
+          </div>
+        )}
+        {!result && !running && <EmptyResults />}
+        {!result && running && <EmptyResults streaming />}
+        {result && view === 'table' && (
+          <ResultsTable result={result} sorted={sorted} sort={sort} setSort={setSort} accent={accent} density={density} streaming={running} />
+        )}
+        {result && view === 'chart' && <ResultsChart result={result} sorted={sorted} accent={accent} />}
+        {result && view === 'json' && <ResultsJson result={result} sorted={sorted} accent={accent} />}
+      </div>
+    </div>
+  );
+}
+
+// Live ms/rows/bytes counters shown in the toolbar while a query streams.
+// ms ticks smoothly off a local clock; rows/bytes come from `progress`.
+function LiveRunStats({ progress, accent }) {
+  const [ms, setMs] = React.useState(0);
+  React.useEffect(() => {
+    const t0 = performance.now();
+    const id = setInterval(() => setMs(performance.now() - t0), 50);
+    return () => clearInterval(id);
+  }, []);
+  const fmt = (n) => n >= 1e9 ? (n/1e9).toFixed(2)+'B' : n >= 1e6 ? (n/1e6).toFixed(1)+'M' : n >= 1e3 ? (n/1e3).toFixed(0)+'K' : String(n);
+  const liveStat = {
+    display: 'flex', alignItems: 'center', gap: 5, fontSize: 11, color: accent,
+    fontFamily: 'var(--mono)', padding: '0 8px', borderRight: '1px solid var(--border-faint)',
+  };
+  return (
+    <>
+      <div style={liveStat}><span className="spin" style={{ display: 'flex' }}><Icon.spinner /></span><span>{ms.toFixed(0)} ms</span></div>
+      {progress && <div style={liveStat}><Icon.rows /><span>{fmt(progress.read)} rows</span></div>}
+      {progress && <div style={liveStat}><Icon.bytes /><span>{progress.bytes}</span></div>}
+    </>
+  );
+}
+
+function Stat({ icon, value, sub }) {
+  return (
+    <div style={{
+      display: 'flex', alignItems: 'center', gap: 5,
+      fontSize: 11, color: 'var(--fg-mute)', fontFamily: 'var(--mono)',
+      padding: '0 8px', borderRight: '1px solid var(--border-faint)',
+    }} title={sub}>
+      <span style={{ color: 'var(--fg-faint)' }}>{icon}</span>
+      <span style={{ color: 'var(--fg)' }}>{value}</span>
+    </div>
+  );
+}
+
+function EmptyResults({ streaming }) {
+  return (
+    <div style={{
+      height: '100%', display: 'flex', alignItems: 'center', justifyContent: 'center',
+      flexDirection: 'column', gap: 6, color: 'var(--fg-faint)', fontSize: 12,
+      background: 'var(--bg-table)',
+    }}>
+      <div style={{
+        width: 36, height: 36, borderRadius: 18, background: 'var(--bg-chip)',
+        display: 'flex', alignItems: 'center', justifyContent: 'center',
+      }}>{streaming ? <span className="spin" style={{ display: 'flex' }}><Icon.spinner /></span> : <Icon.play style={{ opacity: .5 }} />}</div>
+      {streaming ? <div>Starting query…</div> : (
+        <div>Press <kbd style={{
+          padding: '1px 5px', background: 'var(--bg-chip)', borderRadius: 3,
+          fontFamily: 'var(--mono)', fontSize: 10.5,
+        }}>⌘↵</kbd> to run query</div>
+      )}
+    </div>
+  );
+}
+
+function ResultsTable({ result, sorted, sort, setSort, accent, density }) {
+  const cellPad = density === 'compact' ? '4px 10px' : '7px 12px';
+  return (
+    <div style={{ height: '100%', overflow: 'auto', background: 'var(--bg-table)' }}>
+      <table style={{
+        borderCollapse: 'collapse',
+        fontFamily: 'var(--mono)',
+        fontSize: 11.5,
+        width: 'max-content',
+        minWidth: '100%',
+      }}>
+        <thead style={{ position: 'sticky', top: 0, zIndex: 1 }}>
+          <tr>
+            <th style={{
+              ...thStyle, width: 36, textAlign: 'center', color: 'var(--fg-faint)',
+              padding: cellPad,
+            }}>#</th>
+            {result.columns.map((c, i) => {
+              const isSort = sort.col === i;
+              return (
+                <th
+                  key={c.name}
+                  title={c.type}
+                  onClick={() => setSort({ col: i, dir: isSort && sort.dir === 'asc' ? 'desc' : 'asc' })}
+                  style={{
+                    ...thStyle,
+                    cursor: 'pointer',
+                    padding: cellPad,
+                    minWidth: 140,
+                  }}
+                >
+                  <div style={{ display: 'flex', alignItems: 'center', gap: 5 }}>
+                    <span style={{ color: 'var(--fg)' }}>{c.name}</span>
+                    <span style={{ flex: 1 }} />
+                    {isSort && <span style={{ color: accent }}>
+                      {sort.dir === 'asc' ? <Icon.sortAsc /> : <Icon.sortDesc />}
+                    </span>}
+                  </div>
+                </th>
+              );
+            })}
+          </tr>
+        </thead>
+        <tbody>
+          {sorted.map((row, ri) => (
+            <tr key={ri} className="row" style={{ }}>
+              <td style={{ ...tdStyle, padding: cellPad, color: 'var(--fg-faint)', textAlign: 'center', userSelect: 'none' }}>
+                {ri + 1}
+              </td>
+              {row.map((v, ci) => {
+                const col = result.columns[ci];
+                const empty = v === null || v === undefined || v === '';
+                return (
+                  <td key={ci} style={{
+                    ...tdStyle,
+                    padding: cellPad,
+                    textAlign: empty ? 'center' : (typeof v === 'number' ? 'right' : 'left'),
+                    color: empty ? 'var(--fg-faint)' : (typeof v === 'number' ? 'var(--num)' : 'var(--fg)'),
+                  }}>
+                    {empty ? (
+                      <span style={{ opacity: .55 }} title="NULL">—</span>
+                    ) : ci === 0 && CARRIER_NAMES[v] ? (
+                      <span><span style={{ color: 'var(--fg)' }}>{v}</span>
+                        <span style={{ color: 'var(--fg-faint)', marginLeft: 6, fontFamily: 'inherit' }}>{CARRIER_NAMES[v]}</span></span>
+                    ) : (
+                      typeof v === 'number' ? v.toFixed(2) : String(v)
+                    )}
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+const thStyle = {
+  position: 'sticky', top: 0,
+  background: 'var(--bg-th)',
+  borderBottom: '1px solid var(--border)',
+  borderRight: '1px solid var(--border-faint)',
+  textAlign: 'left',
+  fontWeight: 500,
+  fontSize: 11,
+  color: 'var(--fg-mute)',
+  whiteSpace: 'nowrap',
+  userSelect: 'none',
+};
+const tdStyle = {
+  borderBottom: '1px solid var(--border-faint)',
+  borderRight: '1px solid var(--border-faint)',
+  whiteSpace: 'nowrap',
+};
+
+// ─── CHART HELPERS ────────────────────────────────────────────────────
+const CHART_NUM = /^(U?Int|Float|Decimal)/;
+const CHART_TIME = /^(Date|DateTime)/;
+const CHART_ORDINAL = /^(year|quarter|month|week|day|hour|dayofweek|minute)/i;
+const chartStrip = (t) => {
+  let p = t;
+  let m;
+  while ((m = /^(Nullable|LowCardinality)\((.*)\)$/.exec(p))) p = m[2];
+  return p;
+};
+function chartRole(col) {
+  const t = chartStrip(col.type);
+  if (CHART_TIME.test(t)) return 'time';
+  if (CHART_NUM.test(t)) return CHART_ORDINAL.test(col.name) ? 'ordinal' : 'measure';
+  return 'category';
+}
+// Good-enough default — the config bar lets the user override the 10% it
+// gets wrong, so this stays a ~10-line heuristic, not a rule engine.
+function autoChart(columns) {
+  const roles = columns.map((c, i) => ({ i, role: chartRole(c) }));
+  const measures = roles.filter((r) => r.role === 'measure').map((r) => r.i);
+  const x = (roles.find((r) => r.role === 'time')
+    || roles.find((r) => r.role === 'ordinal')
+    || roles.find((r) => r.role === 'category')
+    || roles[0]);
+  if (!measures.length || !x) return null;
+  const type = x.role === 'time' ? 'line' : x.role === 'category' ? 'hbar' : 'bar';
+  return { type, x: x.i, y: measures, series: null };
+}
+const CHART_PALETTE = (accent) => [accent, '#22C55E', '#E0B341', '#EC4899', '#14B8A6', '#A78BFA', '#F97316'];
+
+function useSize() {
+  const ref = React.useRef(null);
+  const [size, setSize] = React.useState({ w: 600, h: 300 });
+  React.useEffect(() => {
+    if (!ref.current || typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver((es) => {
+      const r = es[0].contentRect;
+      setSize({ w: Math.max(120, r.width), h: Math.max(120, r.height) });
+    });
+    ro.observe(ref.current);
+    return () => ro.disconnect();
+  }, []);
+  return [ref, size];
+}
+
+function ChartSelect({ label, value, options, onChange, multi }) {
+  return (
+    <label style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+      <span style={{ fontSize: 10.5, color: 'var(--fg-faint)', textTransform: 'uppercase', letterSpacing: '.05em' }}>{label}</span>
+      <select className="tb-select" value={multi ? undefined : value}
+        onChange={(e) => onChange(e.target.value)} style={{ height: 24, maxWidth: 170 }}>
+        {options.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
+      </select>
+    </label>
+  );
+}
+
+function ResultsChart({ result, sorted, accent }) {
+  const cols = result.columns;
+  const auto = React.useMemo(() => autoChart(cols), [cols]);
+  const [cfg, setCfg] = React.useState(auto);
+  // Re-derive defaults when the result schema changes (different query).
+  const schemaKey = cols.map((c) => c.name + c.type).join('|');
+  React.useEffect(() => { setCfg(autoChart(cols)); }, [schemaKey]);
+  const [chartRef, size] = useSize();
+
+  if (!cfg) {
+    return (
+      <div style={{ height: '100%', display: 'flex', alignItems: 'center', justifyContent: 'center',
+        flexDirection: 'column', gap: 8, color: 'var(--fg-faint)', fontSize: 12, background: 'var(--bg-table)', textAlign: 'center', padding: 24 }}>
+        <Icon.chart style={{ opacity: .5 }} />
+        <div>These results aren't chartable.<br />Add a numeric column to plot them.</div>
+      </div>
+    );
+  }
+
+  const set = (patch) => setCfg((c) => ({ ...c, ...patch }));
+  const numericIdx = cols.map((c, i) => ({ c, i })).filter(({ c }) => chartRole(c) === 'measure' || chartRole(c) === 'ordinal').map(({ i }) => i);
+  const catIdx = cols.map((c, i) => ({ c, i })).filter(({ c }) => chartRole(c) !== 'measure').map(({ i }) => i);
+  const colOpts = cols.map((c, i) => ({ value: String(i), label: c.name }));
+  const yOpts = numericIdx.map((i) => ({ value: String(i), label: cols[i].name }));
+  const seriesOpts = [{ value: '', label: 'None' }, ...catIdx.filter((i) => i !== cfg.x).map((i) => ({ value: String(i), label: cols[i].name }))];
+
+  const types = [
+    { value: 'hbar', label: 'Bar' },
+    { value: 'bar', label: 'Column' },
+    { value: 'line', label: 'Line' },
+    { value: 'area', label: 'Area' },
+    { value: 'pie', label: 'Pie' },
+  ];
+
+  return (
+    <div style={{ height: '100%', display: 'flex', flexDirection: 'column', background: 'var(--bg-table)', minHeight: 0 }}>
+      {/* Config bar */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: 16, padding: '7px 14px', flexWrap: 'wrap',
+        borderBottom: '1px solid var(--border-faint)', flexShrink: 0 }}>
+        <ChartSelect label="Type" value={cfg.type} options={types} onChange={(v) => set({ type: v })} />
+        <ChartSelect label="X" value={String(cfg.x)} options={colOpts} onChange={(v) => set({ x: +v })} />
+        <ChartSelect label="Y" value={String(cfg.y[0])} options={yOpts} onChange={(v) => set({ y: [+v] })} />
+        {cfg.type !== 'pie' && yOpts.length > 1 && (
+          <button className="tb-btn" onClick={() => set({ y: cfg.y.length === yOpts.length ? [cfg.y[0]] : yOpts.map((o) => +o.value) })}
+            title="Toggle plotting all numeric columns as series">
+            {cfg.y.length > 1 ? 'Single series' : 'All measures'}
+          </button>
+        )}
+        {cfg.type !== 'pie' && seriesOpts.length > 1 && (
+          <ChartSelect label="Series" value={String(cfg.series ?? '')} options={seriesOpts} onChange={(v) => set({ series: v === '' ? null : +v })} />
+        )}
+      </div>
+      {/* Plot */}
+      <div ref={chartRef} style={{ flex: 1, minHeight: 0, position: 'relative' }}>
+        <ChartCanvas result={result} sorted={sorted} cfg={cfg} accent={accent} w={size.w} h={size.h} />
+      </div>
+    </div>
+  );
+}
+
+function ChartCanvas({ result, sorted, cfg, accent, w, h }) {
+  const cols = result.columns;
+  const palette = CHART_PALETTE(accent);
+  const fmtNum = (n) => typeof n !== 'number' ? n : Math.abs(n) >= 1e6 ? (n / 1e6).toFixed(1) + 'M' : Math.abs(n) >= 1e3 ? (n / 1e3).toLocaleString() : (Number.isInteger(n) ? n : n.toFixed(2));
+  const xLabel = (v) => {
+    const s = String(v);
+    return /^\d{4}-\d{2}-\d{2}/.test(s) ? s.slice(0, 7) : (CARRIER_NAMES[v] ? v : s);
+  };
+
+  // Build series: either group-by a category column, or one series per Y measure.
+  let series; // [{name, color, points:[{x, y}]}]
+  const xs = sorted.map((r) => r[cfg.x]);
+  if (cfg.series != null) {
+    const yi = cfg.y[0];
+    const groups = {};
+    const order = [];
+    sorted.forEach((r) => {
+      const k = String(r[cfg.series]);
+      if (!(k in groups)) { groups[k] = {}; order.push(k); }
+      groups[k][String(r[cfg.x])] = r[yi];
+    });
+    const xCats = [...new Set(xs.map(String))];
+    series = order.map((k, i) => ({ name: k, color: palette[i % palette.length],
+      points: xCats.map((xc) => ({ x: xc, y: groups[k][xc] ?? 0 })) }));
+  } else {
+    series = cfg.y.map((yi, i) => ({ name: cols[yi].name, color: palette[i % palette.length],
+      points: sorted.map((r) => ({ x: r[cfg.x], y: r[yi] })) }));
+  }
+
+  const PAD = { l: 52, r: 16, t: 16, b: 38 };
+
+  // Horizontal bars — best for ranked categorical data (the original design).
+  // Rendered as HTML rows so labels read naturally; supports grouped series.
+  if (cfg.type === 'hbar') {
+    const hmax = Math.max(0, ...series.flatMap((s) => s.points.map((p) => p.y))) || 1;
+    const cats = series[0]?.points.map((p) => p.x) ?? [];
+    const single = series.length === 1;
+    return (
+      <div style={{ height: h, overflow: 'auto', padding: '14px 16px' }}>
+        {!single && (
+          <div style={{ display: 'flex', gap: 16, marginBottom: 12, paddingLeft: 124 }}>
+            {series.map((s, i) => (
+              <span key={i} style={{ display: 'flex', alignItems: 'center', gap: 6, fontSize: 11, color: 'var(--fg-mute)', fontFamily: 'var(--mono)' }}>
+                <span style={{ width: 9, height: 9, borderRadius: 2, background: s.color }} />{s.name}
+              </span>
+            ))}
+          </div>
+        )}
+        <div style={{ display: 'flex', flexDirection: 'column', gap: single ? 6 : 10 }}>
+          {cats.map((cat, ri) => (
+            <div key={ri} style={{ display: 'flex', alignItems: 'center', gap: 12, fontSize: 11.5 }}>
+              <div style={{ width: 112, flexShrink: 0, textAlign: 'right', fontFamily: 'var(--mono)', color: 'var(--fg-mute)', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                <span style={{ color: 'var(--fg)' }}>{xLabel(cat)}</span>
+                {CARRIER_NAMES[cat] && <span style={{ marginLeft: 6, color: 'var(--fg-faint)' }}>{CARRIER_NAMES[cat]}</span>}
+              </div>
+              <div style={{ flex: 1, display: 'flex', flexDirection: 'column', gap: 2, minWidth: 0 }}>
+                {series.map((s, si) => {
+                  const val = s.points[ri]?.y ?? 0;
+                  const pct = Math.max(0, (val / hmax) * 100);
+                  return (
+                    <div key={si} style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+                      <div style={{ flex: 1, height: single ? 18 : 11, background: 'var(--bg-chip)', borderRadius: 2, position: 'relative', overflow: 'hidden' }}>
+                        <div style={{ position: 'absolute', inset: '0 auto 0 0', width: `${pct}%`,
+                          background: single
+                            ? `linear-gradient(90deg, ${s.color}, color-mix(in oklab, ${s.color} 65%, transparent))`
+                            : s.color,
+                          borderRadius: 2, transition: 'width .4s cubic-bezier(.2,.7,.3,1)' }} />
+                      </div>
+                      <div style={{ width: 64, flexShrink: 0, textAlign: 'right', fontFamily: 'var(--mono)', color: 'var(--num)' }}>{fmtNum(val)}</div>
+                    </div>
+                  );
+                })}
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  const iw = Math.max(10, w - PAD.l - PAD.r);
+  const ih = Math.max(10, h - PAD.t - PAD.b);
+  const allY = series.flatMap((s) => s.points.map((p) => p.y));
+  const maxY = Math.max(0, ...allY);
+  const minY = Math.min(0, ...allY);
+  const yToPx = (v) => PAD.t + ih - ((v - minY) / (maxY - minY || 1)) * ih;
+  const cats = series[0]?.points.map((p) => p.x) ?? [];
+  const n = cats.length;
+
+  // Y gridlines (4)
+  const ticks = 4;
+  const gridY = Array.from({ length: ticks + 1 }, (_, i) => minY + (i / ticks) * (maxY - minY));
+
+  const axisColor = 'var(--border)';
+  const labelColor = 'var(--fg-faint)';
+  const fontMono = 'var(--mono)';
+
+  if (cfg.type === 'pie') {
+    const pts = series[0]?.points ?? [];
+    const total = pts.reduce((a, p) => a + Math.max(0, p.y), 0) || 1;
+    const cx = w / 2, cy = h / 2, rad = Math.max(20, Math.min(w, h) / 2 - 60);
+    let a0 = -Math.PI / 2;
+    const arcs = pts.map((p, i) => {
+      const frac = Math.max(0, p.y) / total;
+      const a1 = a0 + frac * Math.PI * 2;
+      const large = a1 - a0 > Math.PI ? 1 : 0;
+      const x0 = cx + rad * Math.cos(a0), y0 = cy + rad * Math.sin(a0);
+      const x1 = cx + rad * Math.cos(a1), y1 = cy + rad * Math.sin(a1);
+      const d = `M${cx},${cy} L${x0},${y0} A${rad},${rad} 0 ${large} 1 ${x1},${y1} Z`;
+      a0 = a1;
+      return { d, color: palette[i % palette.length], label: xLabel(p.x), pct: (frac * 100).toFixed(0) };
+    });
+    return (
+      <svg width={w} height={h} style={{ display: 'block' }}>
+        {arcs.map((a, i) => <path key={i} d={a.d} fill={a.color} stroke="var(--bg-table)" strokeWidth="1.5" />)}
+        {/* legend */}
+        {arcs.map((a, i) => (
+          <g key={'l' + i} transform={`translate(${w - 130}, ${PAD.t + i * 18})`}>
+            <rect width="9" height="9" rx="2" fill={a.color} />
+            <text x="14" y="8.5" fontSize="11" fill="var(--fg-mute)" fontFamily={fontMono}>{a.label} · {a.pct}%</text>
+          </g>
+        ))}
+      </svg>
+    );
+  }
+
+  return (
+    <svg width={w} height={h} style={{ display: 'block' }}>
+      {/* gridlines + y labels */}
+      {gridY.map((gv, i) => (
+        <g key={i}>
+          <line x1={PAD.l} y1={yToPx(gv)} x2={w - PAD.r} y2={yToPx(gv)} stroke={axisColor} strokeWidth="1" strokeOpacity={i === 0 ? 1 : 0.5} />
+          <text x={PAD.l - 8} y={yToPx(gv) + 3.5} textAnchor="end" fontSize="10" fill={labelColor} fontFamily={fontMono}>{fmtNum(gv)}</text>
+        </g>
+      ))}
+      {/* x labels */}
+      {cats.map((c, i) => {
+        const step = iw / n;
+        const cxp = PAD.l + step * (i + 0.5);
+        if (n > 14 && i % Math.ceil(n / 12) !== 0) return null;
+        return <text key={i} x={cxp} y={h - PAD.b + 14} textAnchor="middle" fontSize="10" fill={labelColor} fontFamily={fontMono}>{xLabel(c)}</text>;
+      })}
+
+      {/* bars */}
+      {cfg.type === 'bar' && series.map((s, si) => {
+        const step = iw / n;
+        const bw = (step * 0.7) / series.length;
+        return s.points.map((p, i) => {
+          const x = PAD.l + step * (i + 0.5) - (bw * series.length) / 2 + si * bw;
+          const y = yToPx(p.y), y0 = yToPx(0);
+          return <rect key={si + '-' + i} x={x} y={Math.min(y, y0)} width={Math.max(1, bw - 1)} height={Math.abs(y0 - y)} fill={s.color} rx="1.5">
+            <title>{xLabel(p.x)}: {fmtNum(p.y)}</title>
+          </rect>;
+        });
+      })}
+
+      {/* line / area */}
+      {(cfg.type === 'line' || cfg.type === 'area') && series.map((s, si) => {
+        const step = iw / n;
+        const px = (i) => PAD.l + step * (i + 0.5);
+        const path = s.points.map((p, i) => `${i === 0 ? 'M' : 'L'}${px(i)},${yToPx(p.y)}`).join(' ');
+        const areaPath = `${path} L${px(s.points.length - 1)},${yToPx(0)} L${px(0)},${yToPx(0)} Z`;
+        return (
+          <g key={si}>
+            {cfg.type === 'area' && <path d={areaPath} fill={s.color} fillOpacity="0.14" />}
+            <path d={path} fill="none" stroke={s.color} strokeWidth="2" strokeLinejoin="round" strokeLinecap="round" />
+            {s.points.map((p, i) => <circle key={i} cx={px(i)} cy={yToPx(p.y)} r="2.5" fill={s.color}><title>{xLabel(p.x)}: {fmtNum(p.y)}</title></circle>)}
+          </g>
+        );
+      })}
+
+      {/* legend (multi-series) */}
+      {series.length > 1 && series.map((s, i) => (
+        <g key={'lg' + i} transform={`translate(${PAD.l + i * 120}, ${PAD.t - 4})`}>
+          <rect width="9" height="9" rx="2" fill={s.color} />
+          <text x="14" y="8.5" fontSize="10.5" fill="var(--fg-mute)" fontFamily={fontMono}>{s.name}</text>
+        </g>
+      ))}
+    </svg>
+  );
+}
+
+function ResultsJson({ result, sorted }) {
+  const json = sorted.map(row => {
+    const obj = {};
+    result.columns.forEach((c, i) => obj[c.name] = row[i]);
+    return obj;
+  });
+  return (
+    <pre style={{
+      margin: 0, height: '100%', overflow: 'auto', padding: '14px 16px',
+      fontFamily: 'var(--mono)', fontSize: 11.5, color: 'var(--fg)',
+      background: 'var(--bg-table)',
+    }}>
+      <code>{JSON.stringify(json, null, 2)}</code>
+    </pre>
+  );
+}
+
+// ─── SHORTCUTS DRAWER ─────────────────────────────────────────────────
+function ShortcutsModal({ open, onClose }) {
+  if (!open) return null;
+  const groups = [
+    { title: 'Editor', items: [
+      ['Run query', '⌘ ↵'],
+      ['Save query', '⌘ S'],
+      ['Format SQL', '⌘ ⇧ F'],
+      ['New tab', '⌘ T'],
+      ['Close tab', '⌘ W'],
+      ['Comment line', '⌘ /'],
+    ]},
+    { title: 'Navigation', items: [
+      ['Toggle sidebar', '⌘ B'],
+      ['Focus editor', '⌘ E'],
+      ['Search schema', '⌘ K'],
+      ['Show shortcuts', '?'],
+    ]},
+    { title: 'Results', items: [
+      ['Copy as TSV', '⌘ ⇧ C'],
+      ['Export CSV', '⌘ ⇧ E'],
+      ['Switch to chart', '⌘ 2'],
+    ]},
+  ];
+  return (
+    <div onClick={onClose} style={{
+      position: 'fixed', inset: 0, zIndex: 100,
+      background: 'rgba(0,0,0,.5)', backdropFilter: 'blur(4px)',
+      display: 'flex', alignItems: 'center', justifyContent: 'center',
+    }}>
+      <div onClick={e => e.stopPropagation()} style={{
+        width: 480, background: 'var(--bg-modal)', borderRadius: 10,
+        border: '1px solid var(--border)', boxShadow: '0 20px 60px rgba(0,0,0,.4)',
+        padding: '18px 22px',
+      }}>
+        <div style={{ fontSize: 14, fontWeight: 600, color: 'var(--fg)', marginBottom: 14 }}>
+          Keyboard shortcuts
+        </div>
+        {groups.map(g => (
+          <div key={g.title} style={{ marginBottom: 12 }}>
+            <div style={{ fontSize: 10, fontWeight: 600, letterSpacing: '.06em', textTransform: 'uppercase',
+              color: 'var(--fg-faint)', marginBottom: 6 }}>{g.title}</div>
+            {g.items.map(([label, key]) => (
+              <div key={label} style={{
+                display: 'flex', justifyContent: 'space-between',
+                padding: '5px 0', fontSize: 12, color: 'var(--fg-mute)',
+              }}>
+                <span>{label}</span>
+                <kbd style={{
+                  fontFamily: 'var(--mono)', fontSize: 10.5,
+                  padding: '2px 7px', background: 'var(--bg-chip)', borderRadius: 4,
+                  color: 'var(--fg)',
+                }}>{key}</kbd>
+              </div>
+            ))}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+Object.assign(window, {
+  AppHeader, SchemaTree, SavedHistoryPanel, QueryTabs, EditorToolbar, ResultsPane,
+  ShortcutsModal, Icon,
+});
diff --git a/design/data.jsx b/design/data.jsx
new file mode 100644
index 0000000..1bd1317
--- /dev/null
+++ b/design/data.jsx
@@ -0,0 +1,188 @@
+// data.jsx — sample airline ontime data, schema, queries
+
+const SCHEMA = [
+  {
+    name: 'airline',
+    type: 'database',
+    expanded: true,
+    children: [
+      { name: 'ontime', type: 'table', rows: '198.3M', size: '94.1 GB',
+        columns: [
+          { name: 'Year', type: 'UInt16' },
+          { name: 'Quarter', type: 'UInt8' },
+          { name: 'Month', type: 'UInt8' },
+          { name: 'DayofMonth', type: 'UInt8' },
+          { name: 'DayOfWeek', type: 'UInt8' },
+          { name: 'FlightDate', type: 'Date' },
+          { name: 'Reporting_Airline', type: 'LowCardinality(String)' },
+          { name: 'Tail_Number', type: 'String' },
+          { name: 'Flight_Number_Reporting_Airline', type: 'String' },
+          { name: 'OriginAirportID', type: 'UInt32' },
+          { name: 'Origin', type: 'LowCardinality(String)' },
+          { name: 'OriginCityName', type: 'String' },
+          { name: 'OriginState', type: 'LowCardinality(String)' },
+          { name: 'DestAirportID', type: 'UInt32' },
+          { name: 'Dest', type: 'LowCardinality(String)' },
+          { name: 'DestCityName', type: 'String' },
+          { name: 'DestState', type: 'LowCardinality(String)' },
+          { name: 'CRSDepTime', type: 'UInt16' },
+          { name: 'DepTime', type: 'Nullable(UInt16)' },
+          { name: 'DepDelay', type: 'Nullable(Int16)' },
+          { name: 'DepDelayMinutes', type: 'Nullable(UInt16)' },
+          { name: 'TaxiOut', type: 'Nullable(UInt16)' },
+          { name: 'WheelsOff', type: 'Nullable(UInt16)' },
+          { name: 'WheelsOn', type: 'Nullable(UInt16)' },
+          { name: 'TaxiIn', type: 'Nullable(UInt16)' },
+          { name: 'CRSArrTime', type: 'UInt16' },
+          { name: 'ArrTime', type: 'Nullable(UInt16)' },
+          { name: 'ArrDelay', type: 'Nullable(Int16)' },
+          { name: 'ArrDelayMinutes', type: 'Nullable(UInt16)' },
+          { name: 'Cancelled', type: 'UInt8' },
+          { name: 'CancellationCode', type: 'LowCardinality(String)' },
+          { name: 'Diverted', type: 'UInt8' },
+          { name: 'AirTime', type: 'Nullable(UInt16)' },
+          { name: 'Flights', type: 'UInt8' },
+          { name: 'Distance', type: 'UInt16' },
+          { name: 'CarrierDelay', type: 'Nullable(UInt16)' },
+          { name: 'WeatherDelay', type: 'Nullable(UInt16)' },
+          { name: 'NASDelay', type: 'Nullable(UInt16)' },
+          { name: 'SecurityDelay', type: 'Nullable(UInt16)' },
+          { name: 'LateAircraftDelay', type: 'Nullable(UInt16)' },
+        ]},
+      { name: 'airports', type: 'table', rows: '6.4K', size: '892 KB',
+        columns: [
+          { name: 'AirportID', type: 'UInt32' },
+          { name: 'Code', type: 'LowCardinality(String)' },
+          { name: 'Name', type: 'String' },
+          { name: 'City', type: 'String' },
+          { name: 'State', type: 'LowCardinality(String)' },
+          { name: 'Country', type: 'LowCardinality(String)' },
+          { name: 'Lat', type: 'Float64' },
+          { name: 'Lon', type: 'Float64' },
+        ]},
+      { name: 'carriers', type: 'table', rows: '1.5K', size: '124 KB',
+        columns: [
+          { name: 'Code', type: 'LowCardinality(String)' },
+          { name: 'Description', type: 'String' },
+        ]},
+    ],
+  },
+  {
+    name: 'system',
+    type: 'database',
+    expanded: false,
+    children: [
+      { name: 'tables', type: 'table', rows: '142', size: '—' },
+      { name: 'columns', type: 'table', rows: '1.8K', size: '—' },
+      { name: 'parts', type: 'table', rows: '4.2K', size: '—' },
+      { name: 'query_log', type: 'table', rows: '892K', size: '218 MB' },
+      { name: 'metrics', type: 'table', rows: '320', size: '—' },
+    ],
+  },
+  {
+    name: 'default',
+    type: 'database',
+    expanded: false,
+    children: [],
+  },
+];
+
+const SAVED_QUERIES = [
+  { id: 'q1', name: 'Worst-delay carriers (2023)', starred: true,
+    sql: `SELECT Reporting_Airline, avg(DepDelayMinutes) AS avg_delay\nFROM airline.ontime\nWHERE Year = 2023 AND Cancelled = 0\nGROUP BY Reporting_Airline\nORDER BY avg_delay DESC\nLIMIT 15` },
+  { id: 'q2', name: 'Busiest origin airports', starred: true,
+    sql: `SELECT Origin, count() AS flights\nFROM airline.ontime\nWHERE Year = 2023\nGROUP BY Origin\nORDER BY flights DESC\nLIMIT 20` },
+  { id: 'q3', name: 'Monthly cancellations 2019–2023', starred: false,
+    sql: `SELECT toStartOfMonth(FlightDate) AS month, sum(Cancelled) AS cancellations\nFROM airline.ontime\nWHERE Year BETWEEN 2019 AND 2023\nGROUP BY month\nORDER BY month` },
+  { id: 'q4', name: 'On-time % by day of week', starred: false,
+    sql: `SELECT DayOfWeek, round(avg(DepDelayMinutes < 15) * 100, 2) AS ontime_pct\nFROM airline.ontime\nWHERE Year = 2023 AND Cancelled = 0\nGROUP BY DayOfWeek\nORDER BY DayOfWeek` },
+];
+
+const HISTORY = [
+  { id: 'h1', sql: 'SELECT count() FROM airline.ontime', when: '2 min ago', rows: 1, ms: 12 },
+  { id: 'h2', sql: 'SELECT Reporting_Airline, avg(DepDelayMinutes) ...', when: '14 min ago', rows: 15, ms: 218 },
+  { id: 'h3', sql: 'DESCRIBE TABLE airline.ontime', when: '32 min ago', rows: 39, ms: 4 },
+  { id: 'h4', sql: 'SELECT Origin, count() FROM airline.ontime ...', when: '1 h ago', rows: 20, ms: 184 },
+  { id: 'h5', sql: 'SHOW DATABASES', when: '2 h ago', rows: 3, ms: 2 },
+  { id: 'h6', sql: 'SELECT * FROM airline.ontime LIMIT 100', when: 'Yesterday', rows: 100, ms: 38 },
+];
+
+// Result for "worst-delay carriers" query
+const RESULT_DELAYS = {
+  columns: [
+    { name: 'Reporting_Airline', type: 'String' },
+    { name: 'avg_delay', type: 'Float64' },
+  ],
+  rows: [
+    ['B6', 22.41],   // JetBlue
+    ['F9', 19.83],   // Frontier
+    ['NK', 18.92],   // Spirit
+    ['G4', 17.20],   // Allegiant
+    ['UA', 14.55],   // United
+    ['AA', 13.87],   // American
+    ['WN', 13.04],   // Southwest
+    ['MQ', 12.61],   // Envoy
+    ['9E', 11.98],   // Endeavor
+    ['YX', 11.42],   // Republic
+    ['OO', 10.85],   // SkyWest
+    ['DL', 10.21],   // Delta
+    ['AS', 9.76],    // Alaska
+    ['HA', 8.93],    // Hawaiian
+    ['QX', 7.41],    // Horizon
+  ],
+  meta: { rows: 15, ms: 218, scanned: '2.41 GB', scannedRows: '64.1M' },
+};
+
+const CARRIER_NAMES = {
+  B6: 'JetBlue', F9: 'Frontier', NK: 'Spirit', G4: 'Allegiant',
+  UA: 'United', AA: 'American', WN: 'Southwest', MQ: 'Envoy',
+  '9E': 'Endeavor', YX: 'Republic', OO: 'SkyWest', DL: 'Delta',
+  AS: 'Alaska', HA: 'Hawaiian', QX: 'Horizon',
+};
+
+// Temporal result — monthly, two measures (drives Line/Area + multi-series demo)
+const RESULT_MONTHLY = {
+  columns: [
+    { name: 'month', type: 'Date' },
+    { name: 'cancellations', type: 'UInt32' },
+    { name: 'diversions', type: 'UInt32' },
+  ],
+  rows: [
+    ['2023-01-01', 18420, 3210],
+    ['2023-02-01', 15880, 2870],
+    ['2023-03-01', 14110, 2640],
+    ['2023-04-01', 12950, 2510],
+    ['2023-05-01', 13670, 2730],
+    ['2023-06-01', 21030, 3980],
+    ['2023-07-01', 23510, 4320],
+    ['2023-08-01', 19980, 3760],
+    ['2023-09-01', 11240, 2190],
+    ['2023-10-01', 10870, 2050],
+    ['2023-11-01', 13320, 2480],
+    ['2023-12-01', 22760, 4110],
+  ],
+  meta: { rows: 12, ms: 96, scanned: '1.18 GB', scannedRows: '31.2M' },
+};
+
+// Ordinal-numeric X (DayOfWeek 1–7) + one measure
+const RESULT_DOW = {
+  columns: [
+    { name: 'DayOfWeek', type: 'UInt8' },
+    { name: 'ontime_pct', type: 'Float64' },
+  ],
+  rows: [
+    [1, 79.4], [2, 82.1], [3, 83.6], [4, 80.2], [5, 76.8], [6, 85.3], [7, 81.0],
+  ],
+  meta: { rows: 7, ms: 142, scanned: '2.05 GB', scannedRows: '58.7M' },
+};
+
+// Pick a result by inspecting the SQL — lets the demo show different chart
+// shapes (bar vs line) depending on what the query looks like.
+function pickResult(sql) {
+  const s = (sql || '').toLowerCase();
+  if (/month|tostartof|flightdate|group by .*\bdate\b/.test(s)) return RESULT_MONTHLY;
+  if (/dayofweek/.test(s)) return RESULT_DOW;
+  return RESULT_DELAYS;
+}
+
+Object.assign(window, { SCHEMA, SAVED_QUERIES, HISTORY, RESULT_DELAYS, RESULT_MONTHLY, RESULT_DOW, CARRIER_NAMES, pickResult });
diff --git a/design/editor-complete.jsx b/design/editor-complete.jsx
new file mode 100644
index 0000000..50f497a
--- /dev/null
+++ b/design/editor-complete.jsx
@@ -0,0 +1,215 @@
+// editor-complete.jsx — autocomplete (#26), signature help + hover docs (#27)
+// All client-side off cached reference data — never runs SQL on the keystroke
+// path. Popovers are positioned by the editor via caret coordinates.
+
+// ── completion context ──────────────────────────────────────────────────────
+// What word is being typed at the caret, and is it qualified (after a dot)?
+function completionContext(value, pos) {
+  let s = pos;
+  while (s > 0 && /[A-Za-z0-9_]/.test(value[s - 1])) s--;
+  const word = value.slice(s, pos);
+  const qualified = value[s - 1] === '.';
+  let parent = null;
+  if (qualified) {
+    let p = s - 1;
+    while (p > 0 && /[A-Za-z0-9_]/.test(value[p - 1])) p--;
+    parent = value.slice(p, s - 1);
+  }
+  return { word, from: s, to: pos, qualified, parent };
+}
+
+const KIND_META = {
+  keyword: { glyph: 'K', color: '#C586C0', label: 'keyword' },
+  fn:      { glyph: 'ƒ', color: '#DCDCAA', label: 'function' },
+  agg:     { glyph: 'Σ', color: '#E0B341', label: 'aggregate' },
+  cast:    { glyph: '⇄', color: '#4FC1FF', label: 'cast' },
+  table:   { glyph: '▦', color: '#FF6B35', label: 'table' },
+  column:  { glyph: '▪', color: '#92E1D8', label: 'column' },
+  db:      { glyph: '◈', color: '#A0A0A8', label: 'database' },
+};
+
+// Rank candidates: qualified → only that table's columns. Otherwise prefix
+// matches first, then substring; columns/tables rank above keywords when the
+// user has typed ≥1 char. Caps the list for a tight dropdown.
+function rankCompletions(items, ctx) {
+  const w = ctx.word.toLowerCase();
+  if (ctx.qualified) {
+    const cols = items.filter((it) => it.kind === 'column' && it.parent === ctx.parent);
+    return (w ? cols.filter((c) => c.label.toLowerCase().includes(w)) : cols).slice(0, 50);
+  }
+  if (!w) {
+    return items.filter((it) => it.kind === 'keyword' || it.kind === 'table').slice(0, 40);
+  }
+  const scored = [];
+  for (const it of items) {
+    const l = it.label.toLowerCase();
+    const idx = l.indexOf(w);
+    if (idx === -1) continue;
+    let score = idx === 0 ? 0 : 100 + idx;              // prefix beats substring
+    if (it.kind === 'column' || it.kind === 'table') score -= 10; // boost schema
+    if (it.kind === 'keyword') score += 5;
+    score += (l.length - w.length) * 0.1;               // prefer closer length
+    scored.push({ it, score });
+  }
+  scored.sort((a, b) => a.score - b.score || a.it.label.localeCompare(b.it.label));
+  return scored.slice(0, 50).map((s) => s.it);
+}
+
+function HiMatch({ text, q }) {
+  if (!q) return text;
+  const i = text.toLowerCase().indexOf(q.toLowerCase());
+  if (i === -1) return text;
+  return (
+    <>{text.slice(0, i)}<span style={{ color: 'var(--accent, #FF6B35)', fontWeight: 700 }}>{text.slice(i, i + q.length)}</span>{text.slice(i + q.length)}</>
+  );
+}
+
+function AutocompleteDropdown({ items, active, query, coords, onPick, accent }) {
+  const listRef = React.useRef(null);
+  React.useEffect(() => {
+    const el = listRef.current?.children[active];
+    if (el) el.scrollIntoView({ block: 'nearest' });
+  }, [active]);
+  if (!items.length) return null;
+
+  // position:fixed in a body portal so the editor's overflow:hidden can't clip
+  // it. Flip above the caret only when there's more room above; clamp to the
+  // viewport so a short editor pane can't push it off-screen.
+  const W = 350;
+  const { cx, cy, lhPx, vw, vh } = coords;
+  const spaceBelow = vh - (cy + lhPx);
+  const spaceAbove = cy;
+  const below = spaceBelow > 248 || spaceBelow >= spaceAbove;
+  const maxH = Math.max(120, Math.min(248, (below ? spaceBelow : spaceAbove) - 10));
+  const left = Math.max(8, Math.min(cx, vw - W - 8));
+  const pos = below
+    ? { top: Math.round(cy + lhPx + 2) }
+    : { bottom: Math.round(vh - cy + 2) };
+  const cur = items[active];
+
+  return ReactDOM.createPortal(
+    <div style={{
+      position: 'fixed', left, ...pos, zIndex: 2147483600, maxHeight: maxH,
+      display: 'flex', flexDirection: 'column',
+      background: 'var(--bg-modal)', border: '1px solid var(--border)', borderRadius: 8,
+      boxShadow: '0 12px 34px rgba(0,0,0,.4)', overflow: 'hidden', width: W,
+      fontFamily: 'var(--ui)', '--accent': accent,
+    }}>
+      <div ref={listRef} style={{ flex: 1, minHeight: 0, overflowY: 'auto', padding: 4 }}>
+        {items.map((it, i) => {
+          const m = KIND_META[it.kind] || KIND_META.fn;
+          const on = i === active;
+          return (
+            <div key={it.label + i} onMouseDown={(e) => { e.preventDefault(); onPick(it); }}
+              style={{
+                display: 'flex', alignItems: 'center', gap: 9, padding: '5px 8px',
+                borderRadius: 5, cursor: 'pointer',
+                background: on ? `color-mix(in oklab, ${accent} 20%, transparent)` : 'transparent',
+              }}>
+              <span style={{
+                width: 17, height: 17, flexShrink: 0, borderRadius: 4, fontSize: 11, fontWeight: 700,
+                display: 'flex', alignItems: 'center', justifyContent: 'center',
+                background: 'var(--bg-chip)', color: m.color, fontFamily: 'var(--mono)',
+              }}>{m.glyph}</span>
+              <span style={{ fontFamily: 'var(--mono)', fontSize: 12.5, color: 'var(--fg)', flexShrink: 0 }}>
+                <HiMatch text={it.label} q={query} />
+              </span>
+              <span style={{
+                marginLeft: 'auto', fontSize: 10.5, color: 'var(--fg-faint)', fontFamily: 'var(--mono)',
+                overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', maxWidth: 150, textAlign: 'right',
+              }}>{it.detail}</span>
+            </div>
+          );
+        })}
+      </div>
+      {(cur.doc || cur.ret) && (
+        <div style={{
+          borderTop: '1px solid var(--border-faint)', padding: '7px 10px',
+          fontSize: 11, color: 'var(--fg-mute)', lineHeight: 1.45, flexShrink: 0,
+          display: 'flex', flexDirection: 'column', gap: 3, background: 'var(--bg-chip)',
+        }}>
+          {cur.detail && cur.kind !== 'keyword' && <span style={{ fontFamily: 'var(--mono)', color: 'var(--fg)' }}>{cur.detail}{cur.ret ? ` → ${cur.ret}` : ''}</span>}
+          {cur.doc && <span>{cur.doc}</span>}
+        </div>
+      )}
+    </div>,
+    document.body,
+  );
+}
+
+// ── signature help ───────────────────────────────────────────────────────────
+// Walk back from caret to find an unclosed "fnName(" and which arg index we're on.
+function signatureContext(value, pos) {
+  let depth = 0, i = pos - 1, argIdx = 0;
+  while (i >= 0) {
+    const c = value[i];
+    if (c === ')') depth++;
+    else if (c === '(') {
+      if (depth === 0) {
+        let e = i;
+        while (e > 0 && /[A-Za-z0-9_]/.test(value[e - 1])) e--;
+        const name = value.slice(e, i);
+        if (name) return { name, argIdx };
+        return null;
+      }
+      depth--;
+    } else if (c === ',' && depth === 0) argIdx++;
+    else if ((c === ';' || c === '\n') && depth === 0) return null;
+    i--;
+  }
+  return null;
+}
+
+function SignatureHelp({ sig, name, argIdx, ret, coords }) {
+  if (!sig) return null;
+  const { cx, cy, lhPx, vw, vh } = coords;
+  // Split args to bold the active one.
+  const open = sig.indexOf('(');
+  const inner = sig.slice(open + 1, sig.lastIndexOf(')'));
+  const args = inner.split(',');
+  // Prefer above the caret; drop below if there's no room up top. Clamp left.
+  const above = cy > 40;
+  const left = Math.max(8, Math.min(cx, vw - 320));
+  const pos = above ? { bottom: Math.round(vh - cy + 4) } : { top: Math.round(cy + lhPx + 4) };
+  return ReactDOM.createPortal(
+    <div style={{
+      position: 'fixed', left, ...pos, zIndex: 2147483599, maxWidth: 340,
+      background: 'var(--bg-modal)', border: '1px solid var(--border)', borderRadius: 7,
+      boxShadow: '0 8px 24px rgba(0,0,0,.35)', padding: '7px 10px',
+      fontFamily: 'var(--mono)', fontSize: 12, color: 'var(--fg-mute)', whiteSpace: 'nowrap',
+      '--accent': coords.accent,
+    }}>
+      <span style={{ color: 'var(--fg)' }}>{name}</span>(
+      {args.map((a, i) => (
+        <span key={i}>
+          <span style={{ color: i === argIdx ? (coords.accent || '#FF6B35') : 'var(--fg-mute)', fontWeight: i === argIdx ? 700 : 400 }}>{a.trim()}</span>
+          {i < args.length - 1 ? ', ' : ''}
+        </span>
+      ))})
+      {ret && <span style={{ color: 'var(--fg-faint)' }}> → {ret}</span>}
+    </div>,
+    document.body,
+  );
+}
+
+// ── hover card ────────────────────────────────────────────────────────────────
+function HoverCard({ title, sig, ret, doc, x, y }) {
+  return (
+    <div style={{
+      position: 'fixed', left: x, top: y + 16, zIndex: 60, width: 280,
+      background: 'var(--bg-modal)', border: '1px solid var(--border)', borderRadius: 8,
+      boxShadow: '0 12px 34px rgba(0,0,0,.4)', padding: '9px 11px',
+      fontFamily: 'var(--ui)', pointerEvents: 'none',
+    }}>
+      <div style={{ fontFamily: 'var(--mono)', fontSize: 12, color: 'var(--fg)', marginBottom: doc ? 5 : 0 }}>
+        {sig || title}{ret ? <span style={{ color: 'var(--fg-faint)' }}> → {ret}</span> : null}
+      </div>
+      {doc && <div style={{ fontSize: 11.5, color: 'var(--fg-mute)', lineHeight: 1.5 }}>{doc}</div>}
+    </div>
+  );
+}
+
+Object.assign(window, {
+  completionContext, rankCompletions, AutocompleteDropdown,
+  signatureContext, SignatureHelp, HoverCard, KIND_META,
+});
diff --git a/design/editor-data.jsx b/design/editor-data.jsx
new file mode 100644
index 0000000..0d8ed7b
--- /dev/null
+++ b/design/editor-data.jsx
@@ -0,0 +1,102 @@
+// editor-data.jsx — reference data for autocomplete, hover docs, signature help
+//
+// In production this is loaded ONCE per connection (the "keystroke rule" —
+// never run SQL on the keystroke path) from ClickHouse system tables:
+//   • system.keywords      → dynamic keyword list (feeds the tokenizer too)
+//   • system.functions     → names + (where available) signatures
+//   • system.completions   → context/belongs-aware completion candidates
+//   • system.documentation → hover docs / descriptions (Phase 2c, lazy)
+// then cached in memory for the session. Here we hardcode a representative
+// slice so the design is concrete and the UX is exercisable offline.
+
+// Keyword list (a superset of the tokenizer's built-in set). The tokenizer
+// now accepts these dynamically: tokenize(sql, { keywords, funcs }).
+const REF_KEYWORDS = [
+  'SELECT','FROM','WHERE','AND','OR','NOT','IN','BETWEEN','LIKE','ILIKE','IS','NULL',
+  'GROUP BY','ORDER BY','HAVING','LIMIT','OFFSET','AS','ON','USING','JOIN','INNER',
+  'LEFT','RIGHT','OUTER','FULL','CROSS','UNION','ALL','DISTINCT','CASE','WHEN',
+  'THEN','ELSE','END','WITH','INSERT','INTO','VALUES','UPDATE','SET','DELETE',
+  'CREATE','TABLE','VIEW','MATERIALIZED','INDEX','DROP','ALTER','SHOW','DESCRIBE',
+  'EXPLAIN','USE','SETTINGS','FORMAT','PREWHERE','FINAL','SAMPLE','ARRAY JOIN',
+  'TOP','ANTI','SEMI','ANY','ASOF','GLOBAL','INTERVAL','TTL','PARTITION BY',
+];
+
+// Function reference: name → { sig, ret, desc, kind }
+// kind drives the icon/category in the autocomplete dropdown.
+const REF_FUNCTIONS = {
+  count:          { sig: 'count([x])', ret: 'UInt64', kind: 'agg', desc: 'Counts rows or non-NULL values of x.' },
+  sum:            { sig: 'sum(x)', ret: 'numeric', kind: 'agg', desc: 'Sum of values across the group.' },
+  avg:            { sig: 'avg(x)', ret: 'Float64', kind: 'agg', desc: 'Arithmetic mean across the group.' },
+  min:            { sig: 'min(x)', ret: 'same as x', kind: 'agg', desc: 'Minimum value across the group.' },
+  max:            { sig: 'max(x)', ret: 'same as x', kind: 'agg', desc: 'Maximum value across the group.' },
+  uniq:           { sig: 'uniq(x, …)', ret: 'UInt64', kind: 'agg', desc: 'Approximate number of distinct values (adaptive HLL).' },
+  uniqExact:      { sig: 'uniqExact(x)', ret: 'UInt64', kind: 'agg', desc: 'Exact number of distinct values. Uses more memory than uniq.' },
+  quantile:       { sig: 'quantile(level)(x)', ret: 'Float64', kind: 'agg', desc: 'Approximate quantile at level∈[0,1] over x (reservoir sampling).' },
+  groupArray:     { sig: 'groupArray([max])(x)', ret: 'Array', kind: 'agg', desc: 'Collects values of x into an array.' },
+  any:            { sig: 'any(x)', ret: 'same as x', kind: 'agg', desc: 'Returns the first value encountered in the group.' },
+  round:          { sig: 'round(x[, N])', ret: 'numeric', kind: 'fn', desc: 'Rounds x to N decimal places (banker’s rounding).' },
+  floor:          { sig: 'floor(x[, N])', ret: 'numeric', kind: 'fn', desc: 'Rounds x down toward negative infinity.' },
+  ceil:           { sig: 'ceil(x[, N])', ret: 'numeric', kind: 'fn', desc: 'Rounds x up toward positive infinity.' },
+  abs:            { sig: 'abs(x)', ret: 'numeric', kind: 'fn', desc: 'Absolute value of x.' },
+  length:         { sig: 'length(x)', ret: 'UInt64', kind: 'fn', desc: 'Number of bytes in a string, or elements in an array.' },
+  lower:          { sig: 'lower(s)', ret: 'String', kind: 'fn', desc: 'Lowercases an ASCII string.' },
+  upper:          { sig: 'upper(s)', ret: 'String', kind: 'fn', desc: 'Uppercases an ASCII string.' },
+  concat:         { sig: 'concat(s1, s2, …)', ret: 'String', kind: 'fn', desc: 'Concatenates the string arguments.' },
+  substring:      { sig: 'substring(s, off[, len])', ret: 'String', kind: 'fn', desc: 'Substring starting at 1-based offset.' },
+  splitByChar:    { sig: 'splitByChar(sep, s)', ret: 'Array(String)', kind: 'fn', desc: 'Splits s by a single-character separator.' },
+  toString:       { sig: 'toString(x)', ret: 'String', kind: 'cast', desc: 'Converts any value to its String representation.' },
+  toDate:         { sig: 'toDate(x)', ret: 'Date', kind: 'cast', desc: 'Converts a value or string to a Date.' },
+  toDateTime:     { sig: 'toDateTime(x)', ret: 'DateTime', kind: 'cast', desc: 'Converts a value or string to a DateTime.' },
+  toUInt32:       { sig: 'toUInt32(x)', ret: 'UInt32', kind: 'cast', desc: 'Casts x to UInt32 (throws on overflow).' },
+  toFloat64:      { sig: 'toFloat64(x)', ret: 'Float64', kind: 'cast', desc: 'Casts x to Float64.' },
+  toStartOfMonth: { sig: 'toStartOfMonth(d)', ret: 'Date', kind: 'fn', desc: 'Rounds a date/datetime down to the first day of its month.' },
+  toStartOfWeek:  { sig: 'toStartOfWeek(d[, mode])', ret: 'Date', kind: 'fn', desc: 'Rounds a date down to the start of its week.' },
+  toStartOfDay:   { sig: 'toStartOfDay(d)', ret: 'DateTime', kind: 'fn', desc: 'Rounds a datetime down to 00:00:00 of its day.' },
+  formatDateTime: { sig: 'formatDateTime(t, fmt)', ret: 'String', kind: 'fn', desc: 'Formats a datetime using a strftime-like pattern.' },
+  now:            { sig: 'now()', ret: 'DateTime', kind: 'fn', desc: 'Current server date and time.' },
+  today:          { sig: 'today()', ret: 'Date', kind: 'fn', desc: 'Current server date.' },
+  if:             { sig: 'if(cond, then, else)', ret: 'inferred', kind: 'fn', desc: 'Branchless ternary; returns then when cond is non-zero.' },
+  multiIf:        { sig: 'multiIf(c1, v1, …, else)', ret: 'inferred', kind: 'fn', desc: 'Chained conditionals — like CASE WHEN, as a function.' },
+  coalesce:       { sig: 'coalesce(x, …)', ret: 'inferred', kind: 'fn', desc: 'First non-NULL argument, or NULL if all are NULL.' },
+  isNull:         { sig: 'isNull(x)', ret: 'UInt8', kind: 'fn', desc: 'Returns 1 if x is NULL, else 0.' },
+  greatest:       { sig: 'greatest(a, b, …)', ret: 'inferred', kind: 'fn', desc: 'Largest of the arguments.' },
+  least:          { sig: 'least(a, b, …)', ret: 'inferred', kind: 'fn', desc: 'Smallest of the arguments.' },
+  arrayJoin:      { sig: 'arrayJoin(arr)', ret: 'rows', kind: 'fn', desc: 'Unfolds an array, emitting one row per element.' },
+};
+
+// Short docs for a few keywords (hover docs, Phase 2c).
+const REF_KEYWORD_DOCS = {
+  PREWHERE: 'ClickHouse-specific filter applied before reading other columns — an optimization over WHERE for selective predicates.',
+  FINAL: 'Forces merge of rows with the same key at read time (ReplacingMergeTree etc.). Expensive; avoid on hot paths.',
+  SAMPLE: 'Reads a deterministic fraction of data for approximate results. Requires a SAMPLE BY key on the table.',
+  'ARRAY JOIN': 'Joins each row with the elements of one of its array columns, multiplying rows.',
+  LIMIT: 'Caps the number of returned rows. LIMIT n BY expr limits per group.',
+  SETTINGS: 'Per-query settings override, e.g. SETTINGS max_threads = 4.',
+};
+
+// Build the completion candidate list. In production this merges
+// system.completions with the loaded schema; here we assemble from
+// REF_KEYWORDS + REF_FUNCTIONS + the in-memory SCHEMA (databases, tables,
+// and ONLY already-loaded columns — no on-demand column fetch).
+function buildCompletions(schema) {
+  const items = [];
+  REF_KEYWORDS.forEach((k) => items.push({ label: k, kind: 'keyword', insert: k, detail: 'keyword' }));
+  Object.entries(REF_FUNCTIONS).forEach(([name, m]) =>
+    items.push({ label: name, kind: m.kind === 'agg' ? 'agg' : m.kind === 'cast' ? 'cast' : 'fn',
+      insert: name + '(', detail: m.sig, doc: m.desc, ret: m.ret }));
+  (schema || []).forEach((db) => {
+    items.push({ label: db.name, kind: 'db', insert: db.name, detail: 'database' });
+    (db.children || []).forEach((tb) => {
+      items.push({ label: tb.name, kind: 'table', insert: tb.name, detail: `table · ${tb.rows} rows` });
+      // Only already-loaded columns (table.columns !== null) — matches the
+      // resolved decision in #25/#26.
+      (tb.columns || []).forEach((c) =>
+        items.push({ label: c.name, kind: 'column', insert: c.name, detail: c.type, parent: tb.name }));
+    });
+  });
+  return items;
+}
+
+Object.assign(window, {
+  REF_KEYWORDS, REF_FUNCTIONS, REF_KEYWORD_DOCS, buildCompletions,
+});
diff --git a/design/editor-search.jsx b/design/editor-search.jsx
new file mode 100644
index 0000000..5050889
--- /dev/null
+++ b/design/editor-search.jsx
@@ -0,0 +1,143 @@
+// editor-search.jsx — in-editor find/replace (#23)
+// Pure match-finder + the floating panel UI. Highlights are drawn by the
+// editor's transparent overlay <pre> (see sql-editor.jsx), per the resolved
+// design: a second color:transparent <pre> carrying only mark spans, never
+// splitting the token render path.
+
+function findMatches(value, query, opts = {}) {
+  if (!query) return [];
+  const { caseSensitive = false, regex = false, wholeWord = false } = opts;
+  const matches = [];
+  try {
+    let re;
+    if (regex) {
+      re = new RegExp(query, caseSensitive ? 'g' : 'gi');
+    } else {
+      let pat = query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      if (wholeWord) pat = `\\b${pat}\\b`;
+      re = new RegExp(pat, caseSensitive ? 'g' : 'gi');
+    }
+    let m;
+    let guard = 0;
+    while ((m = re.exec(value)) !== null) {
+      if (m.index === re.lastIndex) re.lastIndex++; // zero-width guard
+      matches.push({ start: m.index, end: m.index + m[0].length });
+      if (++guard > 10000) break;
+    }
+  } catch (e) {
+    return []; // invalid regex → no matches (panel shows the error state)
+  }
+  return matches;
+}
+
+function validRegex(query, regex) {
+  if (!regex || !query) return true;
+  try { new RegExp(query); return true; } catch { return false; }
+}
+
+function SearchPanel({
+  accent, query, setQuery, replace, setReplace, opts, setOpts,
+  matchCount, activeIndex, showReplace, setShowReplace,
+  onNext, onPrev, onReplace, onReplaceAll, onClose, inputRef,
+}) {
+  const badQuery = !validRegex(query, opts.regex);
+  const tog = (k) => setOpts({ ...opts, [k]: !opts[k] });
+
+  const toggleBtn = (active, label, title, onClick) => (
+    <button title={title} onClick={onClick} style={{
+      width: 24, height: 22, border: 'none', borderRadius: 4, cursor: 'pointer',
+      fontFamily: 'var(--mono)', fontSize: 11, fontWeight: 600,
+      background: active ? accent : 'var(--bg-chip)',
+      color: active ? '#fff' : 'var(--fg-mute)',
+      display: 'flex', alignItems: 'center', justifyContent: 'center',
+    }}>{label}</button>
+  );
+
+  const iconBtn = (children, title, onClick, disabled) => (
+    <button title={title} onClick={onClick} disabled={disabled} style={{
+      width: 24, height: 22, border: 'none', borderRadius: 4,
+      cursor: disabled ? 'default' : 'pointer',
+      background: 'transparent', color: 'var(--fg-mute)', opacity: disabled ? .4 : 1,
+      display: 'flex', alignItems: 'center', justifyContent: 'center',
+    }}
+      onMouseEnter={(e) => { if (!disabled) e.currentTarget.style.background = 'var(--bg-hover)'; }}
+      onMouseLeave={(e) => e.currentTarget.style.background = 'transparent'}
+    >{children}</button>
+  );
+
+  const fieldWrap = { display: 'flex', alignItems: 'center', gap: 4 };
+  const field = {
+    width: 190, height: 26, padding: '0 8px', background: 'var(--bg-input)',
+    border: `1px solid ${badQuery ? '#ef4444' : 'var(--border)'}`, borderRadius: 6,
+    color: 'var(--fg)', fontSize: 12, fontFamily: 'var(--mono)', outline: 'none',
+  };
+
+  return (
+    <div style={{
+      position: 'absolute', top: 8, right: 14, zIndex: 20,
+      display: 'flex', gap: 8, alignItems: 'flex-start',
+      background: 'var(--bg-modal)', border: '1px solid var(--border)',
+      borderRadius: 9, boxShadow: '0 10px 30px rgba(0,0,0,.32)', padding: 8,
+    }}>
+      {/* expand replace toggle */}
+      <button title={showReplace ? 'Hide replace' : 'Show replace'}
+        onClick={() => setShowReplace(!showReplace)} style={{
+          width: 18, alignSelf: 'stretch', border: 'none', background: 'transparent',
+          color: 'var(--fg-faint)', cursor: 'pointer', borderRadius: 4,
+          display: 'flex', alignItems: 'center', justifyContent: 'center',
+        }}>
+        <span style={{ display: 'flex', transform: showReplace ? 'none' : 'rotate(-90deg)', transition: 'transform .15s' }}>
+          <svg width="10" height="10" viewBox="0 0 10 10" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round"><path d="M2 3.5L5 6.5l3-3"/></svg>
+        </span>
+      </button>
+
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+        {/* find row */}
+        <div style={fieldWrap}>
+          <input ref={inputRef} value={query} onChange={(e) => setQuery(e.target.value)}
+            placeholder="Find" style={field} spellCheck={false}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') { e.preventDefault(); e.shiftKey ? onPrev() : onNext(); }
+              if (e.key === 'Escape') { e.preventDefault(); onClose(); }
+            }} />
+          <span style={{
+            minWidth: 52, textAlign: 'center', fontSize: 11, fontFamily: 'var(--mono)',
+            color: badQuery ? '#ef4444' : 'var(--fg-faint)',
+          }}>
+            {badQuery ? 'bad re' : matchCount ? `${activeIndex + 1}/${matchCount}` : '0/0'}
+          </span>
+          {iconBtn(<svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round"><path d="M8 2L4 6l4 4"/></svg>, 'Previous (⇧⏎)', onPrev, !matchCount)}
+          {iconBtn(<svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round"><path d="M4 2l4 4-4 4"/></svg>, 'Next (⏎)', onNext, !matchCount)}
+          <div style={{ display: 'flex', gap: 2, marginLeft: 2 }}>
+            {toggleBtn(opts.caseSensitive, 'Aa', 'Match case', () => tog('caseSensitive'))}
+            {toggleBtn(opts.wholeWord, 'W', 'Whole word', () => tog('wholeWord'))}
+            {toggleBtn(opts.regex, '.*', 'Regular expression', () => tog('regex'))}
+          </div>
+          {iconBtn(<svg width="11" height="11" viewBox="0 0 11 11" fill="none" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round"><path d="M2 2l7 7M9 2l-7 7"/></svg>, 'Close (Esc)', onClose)}
+        </div>
+
+        {/* replace row */}
+        {showReplace && (
+          <div style={fieldWrap}>
+            <input value={replace} onChange={(e) => setReplace(e.target.value)}
+              placeholder="Replace" style={field} spellCheck={false}
+              onKeyDown={(e) => { if (e.key === 'Enter') { e.preventDefault(); onReplace(); } if (e.key === 'Escape') onClose(); }} />
+            <button onClick={onReplace} disabled={!matchCount} title="Replace (⏎)" style={{
+              height: 22, padding: '0 8px', border: 'none', borderRadius: 4,
+              background: 'var(--bg-chip)', color: matchCount ? 'var(--fg)' : 'var(--fg-faint)',
+              fontSize: 11, fontWeight: 500, cursor: matchCount ? 'pointer' : 'default', fontFamily: 'inherit',
+            }}>Replace</button>
+            <button onClick={onReplaceAll} disabled={!matchCount} title="Replace all" style={{
+              height: 22, padding: '0 8px', border: 'none', borderRadius: 4,
+              background: matchCount ? accent : 'var(--bg-chip)',
+              color: matchCount ? '#fff' : 'var(--fg-faint)',
+              fontSize: 11, fontWeight: 600, cursor: matchCount ? 'pointer' : 'default', fontFamily: 'inherit',
+            }}>All</button>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+Object.assign(window, { findMatches, validRegex, SearchPanel });
diff --git a/design/sql-editor.jsx b/design/sql-editor.jsx
new file mode 100644
index 0000000..a795425
--- /dev/null
+++ b/design/sql-editor.jsx
@@ -0,0 +1,514 @@
+// sql-editor.jsx — syntax-highlighted SQL editor (textarea over <pre>)
+// Enhancements (issues #23–#27), all built on the textarea surface:
+//   #23 find/replace  #24 bracket match+auto-close  #25 dynamic-keyword API
+//   #26 autocomplete   #27 signature help + hover docs
+// Reference data, search UI, and completion UI live in editor-data.jsx,
+// editor-search.jsx, editor-complete.jsx.
+
+// ── default token sets (tokenizer also accepts dynamic ones, see #25) ────────
+const SQL_KEYWORDS = new Set([
+  'SELECT','FROM','WHERE','AND','OR','NOT','IN','BETWEEN','LIKE','IS','NULL',
+  'GROUP','BY','ORDER','HAVING','LIMIT','OFFSET','AS','ON','JOIN','INNER',
+  'LEFT','RIGHT','OUTER','FULL','CROSS','UNION','ALL','DISTINCT','CASE','WHEN',
+  'THEN','ELSE','END','WITH','INSERT','INTO','VALUES','UPDATE','SET','DELETE',
+  'CREATE','TABLE','VIEW','INDEX','DROP','ALTER','SHOW','DESCRIBE','DESC','ASC',
+  'EXPLAIN','USE','SETTINGS','FORMAT','ARRAY','TUPLE','MAP','PREWHERE','FINAL',
+  'SAMPLE','TOP','ANTI','SEMI','ANY','ASOF','GLOBAL','LOCAL','ILIKE','USING',
+]);
+const SQL_FUNCS = new Set([
+  'count','sum','avg','min','max','round','floor','ceil','abs','length',
+  'lower','upper','substring','concat','toString','toDate','toDateTime',
+  'toStartOfMonth','toStartOfWeek','toStartOfDay','toStartOfHour','now',
+  'today','yesterday','formatDateTime','if','multiIf','coalesce','isNull',
+  'isNotNull','quantile','quantiles','uniq','uniqExact','any','anyLast',
+  'groupArray','groupUniqArray','arrayJoin','arrayMap','arrayFilter',
+  'splitByChar','toUInt32','toInt64','toFloat64','toUInt8','greatest','least',
+]);
+
+// #25: backward-compatible optional second arg. Existing callers (formatter,
+// highlighter) pass nothing and get the built-in sets.
+function tokenize(sql, opts = {}) {
+  const keywords = opts.keywords || SQL_KEYWORDS;
+  const funcs = opts.funcs || SQL_FUNCS;
+  const out = [];
+  let i = 0;
+  const n = sql.length;
+  while (i < n) {
+    const c = sql[i];
+    if (c === '-' && sql[i + 1] === '-') {
+      let j = i; while (j < n && sql[j] !== '\n') j++;
+      out.push({ t: 'comment', v: sql.slice(i, j), i }); i = j; continue;
+    }
+    if (c === '/' && sql[i + 1] === '*') {
+      let j = i + 2; while (j < n - 1 && !(sql[j] === '*' && sql[j + 1] === '/')) j++;
+      j = Math.min(n, j + 2);
+      out.push({ t: 'comment', v: sql.slice(i, j), i }); i = j; continue;
+    }
+    if (c === "'" || c === '"' || c === '`') {
+      let j = i + 1;
+      while (j < n && sql[j] !== c) { if (sql[j] === '\\') j++; j++; }
+      j = Math.min(n, j + 1);
+      out.push({ t: c === '`' ? 'ident' : 'string', v: sql.slice(i, j), i }); i = j; continue;
+    }
+    if (/[0-9]/.test(c)) {
+      let j = i;
+      while (j < n && /[0-9.eE+\-]/.test(sql[j])) {
+        if ((sql[j] === '+' || sql[j] === '-') && !/[eE]/.test(sql[j - 1])) break;
+        j++;
+      }
+      out.push({ t: 'number', v: sql.slice(i, j), i }); i = j; continue;
+    }
+    if (/[a-zA-Z_]/.test(c)) {
+      let j = i;
+      while (j < n && /[a-zA-Z0-9_]/.test(sql[j])) j++;
+      const word = sql.slice(i, j);
+      const upper = word.toUpperCase();
+      let type = 'ident';
+      if (keywords.has(upper)) type = 'keyword';
+      else if (funcs.has(word)) type = 'func';
+      out.push({ t: type, v: word, i }); i = j; continue;
+    }
+    if (/[=<>!+\-*/%(),.;]/.test(c)) { out.push({ t: 'op', v: c, i }); i++; continue; }
+    let j = i;
+    while (j < n && /\s/.test(sql[j])) j++;
+    if (j > i) { out.push({ t: 'ws', v: sql.slice(i, j), i }); i = j; continue; }
+    out.push({ t: 'other', v: c, i }); i++;
+  }
+  return out;
+}
+const highlightSql = (sql, opts) => tokenize(sql, opts);
+
+function SqlHighlighter({ sql }) {
+  const tokens = React.useMemo(() => tokenize(sql), [sql]);
+  return (
+    <>
+      {tokens.map((tk, i) => tk.t === 'ws' ? tk.v : <span key={i} className={`sql-${tk.t}`}>{tk.v}</span>)}
+      {'\n'}
+    </>
+  );
+}
+
+// ── caret/position geometry (monospace fast-path; whitespace:pre, no wrap) ────
+let _measCanvas;
+function charWidthFor(px) {
+  _measCanvas = _measCanvas || document.createElement('canvas');
+  const ctx = _measCanvas.getContext('2d');
+  ctx.font = `${px}px "JetBrains Mono","SF Mono",ui-monospace,monospace`;
+  return ctx.measureText('0').width;
+}
+function caretXY(value, pos, ta, fontSize, lhPx, padX, padY) {
+  const before = value.slice(0, pos);
+  const line = before.split('\n').length - 1;
+  const col = pos - (before.lastIndexOf('\n') + 1);
+  const cw = charWidthFor(fontSize);
+  return { x: padX + col * cw - (ta ? ta.scrollLeft : 0), y: padY + line * lhPx - (ta ? ta.scrollTop : 0) };
+}
+function posFromXY(value, clientX, clientY, rect, ta, fontSize, lhPx, padX, padY) {
+  const x = clientX - rect.left + ta.scrollLeft - padX;
+  const y = clientY - rect.top + ta.scrollTop - padY;
+  const line = Math.floor(y / lhPx);
+  const lines = value.split('\n');
+  if (line < 0 || line >= lines.length) return null;
+  const col = Math.round(x / charWidthFor(fontSize));
+  let pos = 0;
+  for (let k = 0; k < line; k++) pos += lines[k].length + 1;
+  return pos + Math.max(0, Math.min(col, lines[line].length));
+}
+function wordAt(value, pos) {
+  if (pos == null) return null;
+  let s = pos, e = pos;
+  while (s > 0 && /[A-Za-z0-9_]/.test(value[s - 1])) s--;
+  while (e < value.length && /[A-Za-z0-9_]/.test(value[e])) e++;
+  if (s === e) return null;
+  return { word: value.slice(s, e), from: s, to: e };
+}
+
+// ── bracket matching (#24) ───────────────────────────────────────────────────
+const OPEN = { '(': ')', '[': ']', '{': '}' };
+const CLOSE = { ')': '(', ']': '[', '}': '{' };
+function matchBracketAt(value, caret) {
+  const tryFrom = (idx, dir) => {
+    const ch = value[idx];
+    if (dir === 1 && OPEN[ch]) {
+      let depth = 0;
+      for (let k = idx; k < value.length; k++) {
+        if (value[k] === ch) depth++;
+        else if (value[k] === OPEN[ch]) { depth--; if (depth === 0) return [idx, k]; }
+      }
+    } else if (dir === -1 && CLOSE[ch]) {
+      let depth = 0;
+      for (let k = idx; k >= 0; k--) {
+        if (value[k] === ch) depth++;
+        else if (value[k] === CLOSE[ch]) { depth--; if (depth === 0) return [k, idx]; }
+      }
+    }
+    return null;
+  };
+  return tryFrom(caret, 1) || (caret > 0 ? tryFrom(caret - 1, -1) : null);
+}
+
+// ── transparent overlay: only mark backgrounds, never the token render path ──
+function MarkOverlay({ value, marks, accent }) {
+  if (!marks.length) return null;
+  const bgFor = (cls) =>
+    cls === 'active' ? `color-mix(in oklab, ${accent} 62%, transparent)`
+    : cls === 'match' ? `color-mix(in oklab, ${accent} 26%, transparent)`
+    : `color-mix(in oklab, ${accent} 34%, transparent)`; // bracket
+  const pts = new Set([0, value.length]);
+  marks.forEach((m) => { pts.add(m.start); pts.add(m.end); });
+  const sorted = [...pts].filter((p) => p >= 0 && p <= value.length).sort((a, b) => a - b);
+  const out = [];
+  for (let i = 0; i < sorted.length - 1; i++) {
+    const a = sorted[i], b = sorted[i + 1];
+    if (a === b) continue;
+    const seg = value.slice(a, b);
+    const cover = marks.filter((m) => m.start <= a && m.end >= b);
+    if (cover.length) {
+      const cls = cover.some((m) => m.cls === 'active') ? 'active'
+        : cover.some((m) => m.cls === 'match') ? 'match' : cover[0].cls;
+      out.push(<span key={i} style={{ background: bgFor(cls), borderRadius: 2 }}>{seg}</span>);
+    } else out.push(seg);
+  }
+  out.push('\n');
+  return out;
+}
+
+function SqlEditor({ value, onChange, accent = '#FF6B35', fontSize = 13, density = 'comfortable' }) {
+  const taRef = React.useRef(null);
+  const preRef = React.useRef(null);
+  const overlayRef = React.useRef(null);
+  const lineRef = React.useRef(null);
+  const wrapRef = React.useRef(null);
+  const pendingSel = React.useRef(null);
+
+  const [caret, setCaret] = React.useState(0);
+  const [selEnd, setSelEnd] = React.useState(0);
+
+  // completion / search / popover state
+  const completions = React.useMemo(() => buildCompletions(window.SCHEMA), []);
+  const [ac, setAc] = React.useState(null);        // {items, active, ctx}
+  const [searchOpen, setSearchOpen] = React.useState(false);
+  const [query, setQuery] = React.useState('');
+  const [replace, setReplace] = React.useState('');
+  const [sopts, setSopts] = React.useState({ caseSensitive: false, wholeWord: false, regex: false });
+  const [showReplace, setShowReplace] = React.useState(false);
+  const [activeMatch, setActiveMatch] = React.useState(0);
+  const [hover, setHover] = React.useState(null);
+  const searchInputRef = React.useRef(null);
+  const hoverTimer = React.useRef(null);
+
+  const lineHeight = density === 'compact' ? 1.5 : 1.7;
+  const padY = density === 'compact' ? 8 : 12;
+  const padX = 14;
+  const lhPx = fontSize * lineHeight;
+  const lines = value.split('\n');
+
+  React.useLayoutEffect(() => {
+    if (pendingSel.current != null && taRef.current) {
+      const [s, e] = pendingSel.current;
+      taRef.current.selectionStart = s;
+      taRef.current.selectionEnd = e;
+      pendingSel.current = null;
+      setCaret(s); setSelEnd(e);
+    }
+  });
+
+  const apply = (newVal, s, e = s) => { pendingSel.current = [s, e]; onChange(newVal); };
+
+  const syncCaret = () => {
+    const ta = taRef.current; if (!ta) return;
+    setCaret(ta.selectionStart); setSelEnd(ta.selectionEnd);
+  };
+
+  const onScroll = () => {
+    const ta = taRef.current;
+    if (preRef.current) { preRef.current.scrollTop = ta.scrollTop; preRef.current.scrollLeft = ta.scrollLeft; }
+    if (overlayRef.current) { overlayRef.current.scrollTop = ta.scrollTop; overlayRef.current.scrollLeft = ta.scrollLeft; }
+    if (lineRef.current) lineRef.current.scrollTop = ta.scrollTop;
+    setAc(null);
+  };
+
+  // ── autocomplete trigger ───────────────────────────────────────────────────
+  const refreshComplete = (val, pos) => {
+    const ctx = completionContext(val, pos);
+    if (!ctx.qualified && ctx.word.length < 1) { setAc(null); return; }
+    const items = rankCompletions(completions, ctx);
+    if (!items.length) { setAc(null); return; }
+    setAc({ items, active: 0, ctx });
+  };
+
+  const acceptCompletion = (it) => {
+    if (!ac) return;
+    const { from, to } = ac.ctx;
+    const ins = it.insert;
+    const newVal = value.slice(0, from) + ins + value.slice(to);
+    const caretPos = from + ins.length;
+    apply(newVal, caretPos);
+    setAc(null);
+  };
+
+  // ── key handling: tab, brackets, autoclose, autocomplete nav, cmd+f ──────────
+  const onKeyDown = (e) => {
+    const ta = e.target;
+    const s = ta.selectionStart, en = ta.selectionEnd;
+
+    // Cmd/Ctrl+F — registered on the textarea so the browser's native find
+    // doesn't intercept first (resolved design decision).
+    if ((e.metaKey || e.ctrlKey) && (e.key === 'f' || e.key === 'F')) {
+      e.preventDefault();
+      setSearchOpen(true);
+      requestAnimationFrame(() => searchInputRef.current?.focus());
+      return;
+    }
+
+    // autocomplete navigation
+    if (ac) {
+      if (e.key === 'ArrowDown') { e.preventDefault(); setAc({ ...ac, active: (ac.active + 1) % ac.items.length }); return; }
+      if (e.key === 'ArrowUp') { e.preventDefault(); setAc({ ...ac, active: (ac.active - 1 + ac.items.length) % ac.items.length }); return; }
+      if (e.key === 'Enter' || e.key === 'Tab') { e.preventDefault(); acceptCompletion(ac.items[ac.active]); return; }
+      if (e.key === 'Escape') { e.preventDefault(); setAc(null); return; }
+    }
+
+    if (e.key === 'Tab') {
+      e.preventDefault();
+      apply(value.slice(0, s) + '  ' + value.slice(en), s + 2);
+      return;
+    }
+
+    // auto-close pairs + wrap selection (#24)
+    if (OPEN[e.key]) {
+      e.preventDefault();
+      const close = OPEN[e.key];
+      if (s !== en) { // wrap
+        apply(value.slice(0, s) + e.key + value.slice(s, en) + close + value.slice(en), s + 1, en + 1);
+      } else {
+        apply(value.slice(0, s) + e.key + close + value.slice(en), s + 1);
+      }
+      return;
+    }
+    if ((e.key === "'" || e.key === '"' || e.key === '`')) {
+      const q = e.key;
+      if (s !== en) { e.preventDefault(); apply(value.slice(0, s) + q + value.slice(s, en) + q + value.slice(en), s + 1, en + 1); return; }
+      if (value[s] === q) { e.preventDefault(); apply(value, s + 1); return; } // type over
+      e.preventDefault(); apply(value.slice(0, s) + q + q + value.slice(en), s + 1); return;
+    }
+    if (CLOSE[e.key] && value[s] === e.key && s === en) { // type over closer
+      e.preventDefault(); apply(value, s + 1); return;
+    }
+    if (e.key === 'Backspace' && s === en && s > 0) {
+      const prev = value[s - 1], next = value[s];
+      if ((OPEN[prev] && next === OPEN[prev]) || ((prev === "'" || prev === '"' || prev === '`') && next === prev)) {
+        e.preventDefault(); apply(value.slice(0, s - 1) + value.slice(s + 1), s - 1); return;
+      }
+    }
+  };
+
+  const onChangeRaw = (e) => {
+    const val = e.target.value;
+    const pos = e.target.selectionStart;
+    onChange(val);
+    setCaret(pos); setSelEnd(pos);
+    refreshComplete(val, pos);
+  };
+
+  // ── search ───────────────────────────────────────────────────────────────
+  const matches = React.useMemo(
+    () => (searchOpen && query ? findMatches(value, query, sopts) : []),
+    [searchOpen, query, value, sopts]);
+  React.useEffect(() => { setActiveMatch((a) => matches.length ? Math.min(a, matches.length - 1) : 0); }, [matches.length]);
+
+  const scrollToMatch = (m) => {
+    const ta = taRef.current; if (!ta || !m) return;
+    const line = value.slice(0, m.start).split('\n').length - 1;
+    const top = line * lhPx;
+    if (top < ta.scrollTop + padY || top > ta.scrollTop + ta.clientHeight - lhPx - padY) {
+      ta.scrollTop = Math.max(0, top - ta.clientHeight / 2);
+      onScroll();
+    }
+  };
+  const gotoMatch = (idx) => { const i = (idx + matches.length) % matches.length; setActiveMatch(i); scrollToMatch(matches[i]); };
+  const doReplace = () => {
+    const m = matches[activeMatch]; if (!m) return;
+    apply(value.slice(0, m.start) + replace + value.slice(m.end), m.start + replace.length);
+    requestAnimationFrame(() => searchInputRef.current?.focus());
+  };
+  const doReplaceAll = () => {
+    if (!matches.length) return;
+    let out = '', last = 0;
+    for (const m of matches) { out += value.slice(last, m.start) + replace; last = m.end; }
+    out += value.slice(last);
+    apply(out, Math.min(caret, out.length));
+  };
+  const closeSearch = () => { setSearchOpen(false); requestAnimationFrame(() => taRef.current?.focus()); };
+
+  // ── marks (search + bracket pair) ──────────────────────────────────────────
+  const marks = React.useMemo(() => {
+    const ms = [];
+    if (searchOpen) matches.forEach((m, i) => ms.push({ start: m.start, end: m.end, cls: i === activeMatch ? 'active' : 'match' }));
+    if (!searchOpen && caret === selEnd) {
+      const bp = matchBracketAt(value, caret);
+      if (bp) { ms.push({ start: bp[0], end: bp[0] + 1, cls: 'bracket' }); ms.push({ start: bp[1], end: bp[1] + 1, cls: 'bracket' }); }
+    }
+    return ms;
+  }, [searchOpen, matches, activeMatch, value, caret, selEnd]);
+
+  // ── signature help (#27) ────────────────────────────────────────────────────
+  const sig = React.useMemo(() => {
+    if (ac || caret !== selEnd) return null;
+    const sc = signatureContext(value, caret);
+    if (!sc) return null;
+    const meta = REF_FUNCTIONS[sc.name];
+    if (!meta) return null;
+    return { ...sc, sig: meta.sig, ret: meta.ret };
+  }, [value, caret, selEnd, ac]);
+
+  // ── hover docs (#27) ────────────────────────────────────────────────────────
+  const onMouseMove = (e) => {
+    clearTimeout(hoverTimer.current);
+    const ta = taRef.current; if (!ta) { return; }
+    const cx = e.clientX, cy = e.clientY;
+    hoverTimer.current = setTimeout(() => {
+      const rect = ta.getBoundingClientRect();
+      const pos = posFromXY(value, cx, cy, rect, ta, fontSize, lhPx, padX, padY);
+      const w = wordAt(value, pos);
+      if (!w) { setHover(null); return; }
+      const fn = REF_FUNCTIONS[w.word];
+      const kw = REF_KEYWORD_DOCS[w.word.toUpperCase()];
+      if (fn) setHover({ x: cx, y: cy, sig: fn.sig, ret: fn.ret, doc: fn.desc });
+      else if (kw) setHover({ x: cx, y: cy, title: w.word.toUpperCase(), doc: kw });
+      else setHover(null);
+    }, 350);
+  };
+  const onMouseLeave = () => { clearTimeout(hoverTimer.current); setHover(null); };
+
+  const sharedText = {
+    margin: 0, padding: `${padY}px ${padX}px`, fontFamily: 'inherit', fontSize: 'inherit',
+    lineHeight: 'inherit', whiteSpace: 'pre', border: 'none', position: 'absolute', inset: 0,
+  };
+  const caretCoords = caretXY(value, caret, taRef.current, fontSize, lhPx, padX, padY);
+  // Screen-space caret position for body-portaled popovers (so the editor's
+  // overflow:hidden can't clip them). Falls back to 0,0 before first mount.
+  const taRect = taRef.current ? taRef.current.getBoundingClientRect() : null;
+  const popCoords = {
+    cx: (taRect ? taRect.left : 0) + caretCoords.x,
+    cy: (taRect ? taRect.top : 0) + caretCoords.y,
+    lhPx,
+    vw: typeof window !== 'undefined' ? window.innerWidth : 1280,
+    vh: typeof window !== 'undefined' ? window.innerHeight : 800,
+    accent,
+  };
+
+  return (
+    <div className="sql-editor" style={{
+      position: 'relative', display: 'flex', width: '100%', height: '100%',
+      fontFamily: '"JetBrains Mono","SF Mono",ui-monospace,monospace',
+      fontSize, lineHeight, background: 'var(--bg-editor)', color: 'var(--fg)', overflow: 'hidden',
+      '--accent': accent,
+    }}>
+      <div ref={lineRef} className="sql-gutter" style={{
+        flexShrink: 0, width: 44, padding: `${padY}px 8px ${padY}px 0`, textAlign: 'right',
+        color: 'var(--fg-faint)', userSelect: 'none', background: 'var(--bg-gutter)',
+        borderRight: '1px solid var(--border)', overflow: 'hidden', fontVariantNumeric: 'tabular-nums',
+      }}>
+        {lines.map((_, i) => <div key={i} style={{ height: `${lineHeight}em` }}>{i + 1}</div>)}
+      </div>
+
+      <div ref={wrapRef} style={{ position: 'relative', flex: 1, overflow: 'hidden' }}
+        onMouseMove={onMouseMove} onMouseLeave={onMouseLeave}>
+        {/* mark overlay (below tokens; transparent text, only backgrounds show) */}
+        <pre ref={overlayRef} aria-hidden="true" style={{ ...sharedText, color: 'transparent', overflow: 'hidden', pointerEvents: 'none' }}>
+          <MarkOverlay value={value} marks={marks} accent={accent} />
+        </pre>
+        {/* token highlight */}
+        <pre ref={preRef} aria-hidden="true" style={{ ...sharedText, color: 'inherit', overflow: 'hidden', pointerEvents: 'none' }}>
+          <SqlHighlighter sql={value} />
+        </pre>
+        <textarea
+          ref={taRef}
+          value={value}
+          onChange={onChangeRaw}
+          onScroll={onScroll}
+          onKeyDown={onKeyDown}
+          onSelect={syncCaret}
+          onKeyUp={syncCaret}
+          onClick={() => { syncCaret(); setAc(null); }}
+          onBlur={() => setTimeout(() => setAc(null), 120)}
+          spellCheck={false}
+          style={{
+            ...sharedText, background: 'transparent', color: 'transparent', caretColor: accent,
+            outline: 'none', resize: 'none', overflow: 'auto', tabSize: 2, zIndex: 2,
+          }}
+        />
+
+        {searchOpen && (
+          <SearchPanel
+            accent={accent} query={query} setQuery={setQuery} replace={replace} setReplace={setReplace}
+            opts={sopts} setOpts={setSopts} matchCount={matches.length} activeIndex={activeMatch}
+            showReplace={showReplace} setShowReplace={setShowReplace}
+            onNext={() => gotoMatch(activeMatch + 1)} onPrev={() => gotoMatch(activeMatch - 1)}
+            onReplace={doReplace} onReplaceAll={doReplaceAll} onClose={closeSearch} inputRef={searchInputRef}
+          />
+        )}
+
+        {ac && (
+          <AutocompleteDropdown
+            items={ac.items} active={ac.active} query={ac.ctx.word} accent={accent}
+            coords={popCoords}
+            onPick={acceptCompletion}
+          />
+        )}
+
+        {sig && (
+          <SignatureHelp sig={sig.sig} name={sig.name} argIdx={sig.argIdx} ret={sig.ret}
+            coords={popCoords} />
+        )}
+      </div>
+
+      {hover && <HoverCard {...hover} />}
+    </div>
+  );
+}
+
+// ── FORMATTER (unchanged) ─────────────────────────────────────────────────────
+const FMT_NEWLINE_KW = new Set([
+  'SELECT','FROM','WHERE','PREWHERE','GROUP','ORDER','HAVING','LIMIT','UNION',
+  'SETTINGS','FORMAT','WITH','JOIN','LEFT','RIGHT','INNER','OUTER','FULL',
+  'CROSS','ON','INSERT','VALUES','UPDATE','SET','DELETE','ARRAY',
+]);
+const FMT_JOIN_PREFIX = new Set(['LEFT','RIGHT','INNER','OUTER','FULL','CROSS','ANY','ALL','ASOF','SEMI','ANTI','GLOBAL']);
+function fmtNeedSpace(prev, cur) {
+  if (!prev) return false;
+  const pv = prev.v, cv = cur.v;
+  if (cv === ',' || cv === ')' || cv === ';') return false;
+  if (pv === '(') return false;
+  if (pv === '.' || cv === '.') return false;
+  if (cv === '(') return prev.t === 'keyword';
+  return true;
+}
+function formatSql(sql) {
+  if (!sql || !sql.trim()) return sql;
+  const toks = tokenize(sql).filter((t) => t.t !== 'ws' && t.v !== '');
+  let out = '', depth = 0, prev = null;
+  for (const tk of toks) {
+    let v = tk.v;
+    const uv = v.toUpperCase();
+    if (tk.t === 'keyword') v = uv;
+    if (v === '(') depth++;
+    let newline = false;
+    if (tk.t === 'keyword' && depth === 0 && FMT_NEWLINE_KW.has(uv)) {
+      const prevUv = prev && prev.t === 'keyword' ? prev.v.toUpperCase() : null;
+      if (uv === 'BY') newline = false;
+      else if (uv === 'JOIN' && prevUv && FMT_JOIN_PREFIX.has(prevUv)) newline = false;
+      else if (uv === 'SET' && prevUv === 'OFFSET') newline = false;
+      else newline = true;
+    }
+    if (out === '') out = v;
+    else if (newline) out += '\n' + v;
+    else out += (fmtNeedSpace(prev, tk) ? ' ' : '') + v;
+    if (v === ')') depth = Math.max(0, depth - 1);
+    prev = tk;
+  }
+  return out;
+}
+
+Object.assign(window, { SqlEditor, highlightSql, tokenize, formatSql });
diff --git a/design/tweaks-panel.jsx b/design/tweaks-panel.jsx
new file mode 100644
index 0000000..184b014
--- /dev/null
+++ b/design/tweaks-panel.jsx
@@ -0,0 +1,425 @@
+
+// tweaks-panel.jsx
+// Reusable Tweaks shell + form-control helpers.
+//
+// Owns the host protocol (listens for __activate_edit_mode / __deactivate_edit_mode,
+// posts __edit_mode_available / __edit_mode_set_keys / __edit_mode_dismissed) so
+// individual prototypes don't re-roll it. Ships a consistent set of controls so you
+// don't hand-draw <input type="range">, segmented radios, steppers, etc.
+//
+// Usage (in an HTML file that loads React + Babel):
+//
+//   const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
+//     "primaryColor": "#D97757",
+//     "fontSize": 16,
+//     "density": "regular",
+//     "dark": false
+//   }/*EDITMODE-END*/;
+//
+//   function App() {
+//     const [t, setTweak] = useTweaks(TWEAK_DEFAULTS);
+//     return (
+//       <div style={{ fontSize: t.fontSize, color: t.primaryColor }}>
+//         Hello
+//         <TweaksPanel>
+//           <TweakSection label="Typography" />
+//           <TweakSlider label="Font size" value={t.fontSize} min={10} max={32} unit="px"
+//                        onChange={(v) => setTweak('fontSize', v)} />
+//           <TweakRadio  label="Density" value={t.density}
+//                        options={['compact', 'regular', 'comfy']}
+//                        onChange={(v) => setTweak('density', v)} />
+//           <TweakSection label="Theme" />
+//           <TweakColor  label="Primary" value={t.primaryColor}
+//                        onChange={(v) => setTweak('primaryColor', v)} />
+//           <TweakToggle label="Dark mode" value={t.dark}
+//                        onChange={(v) => setTweak('dark', v)} />
+//         </TweaksPanel>
+//       </div>
+//     );
+//   }
+//
+// ─────────────────────────────────────────────────────────────────────────────
+
+const __TWEAKS_STYLE = `
+  .twk-panel{position:fixed;right:16px;bottom:16px;z-index:2147483646;width:280px;
+    max-height:calc(100vh - 32px);display:flex;flex-direction:column;
+    background:rgba(250,249,247,.78);color:#29261b;
+    -webkit-backdrop-filter:blur(24px) saturate(160%);backdrop-filter:blur(24px) saturate(160%);
+    border:.5px solid rgba(255,255,255,.6);border-radius:14px;
+    box-shadow:0 1px 0 rgba(255,255,255,.5) inset,0 12px 40px rgba(0,0,0,.18);
+    font:11.5px/1.4 ui-sans-serif,system-ui,-apple-system,sans-serif;overflow:hidden}
+  .twk-hd{display:flex;align-items:center;justify-content:space-between;
+    padding:10px 8px 10px 14px;cursor:move;user-select:none}
+  .twk-hd b{font-size:12px;font-weight:600;letter-spacing:.01em}
+  .twk-x{appearance:none;border:0;background:transparent;color:rgba(41,38,27,.55);
+    width:22px;height:22px;border-radius:6px;cursor:default;font-size:13px;line-height:1}
+  .twk-x:hover{background:rgba(0,0,0,.06);color:#29261b}
+  .twk-body{padding:2px 14px 14px;display:flex;flex-direction:column;gap:10px;
+    overflow-y:auto;overflow-x:hidden;min-height:0;
+    scrollbar-width:thin;scrollbar-color:rgba(0,0,0,.15) transparent}
+  .twk-body::-webkit-scrollbar{width:8px}
+  .twk-body::-webkit-scrollbar-track{background:transparent;margin:2px}
+  .twk-body::-webkit-scrollbar-thumb{background:rgba(0,0,0,.15);border-radius:4px;
+    border:2px solid transparent;background-clip:content-box}
+  .twk-body::-webkit-scrollbar-thumb:hover{background:rgba(0,0,0,.25);
+    border:2px solid transparent;background-clip:content-box}
+  .twk-row{display:flex;flex-direction:column;gap:5px}
+  .twk-row-h{flex-direction:row;align-items:center;justify-content:space-between;gap:10px}
+  .twk-lbl{display:flex;justify-content:space-between;align-items:baseline;
+    color:rgba(41,38,27,.72)}
+  .twk-lbl>span:first-child{font-weight:500}
+  .twk-val{color:rgba(41,38,27,.5);font-variant-numeric:tabular-nums}
+
+  .twk-sect{font-size:10px;font-weight:600;letter-spacing:.06em;text-transform:uppercase;
+    color:rgba(41,38,27,.45);padding:10px 0 0}
+  .twk-sect:first-child{padding-top:0}
+
+  .twk-field{appearance:none;width:100%;height:26px;padding:0 8px;
+    border:.5px solid rgba(0,0,0,.1);border-radius:7px;
+    background:rgba(255,255,255,.6);color:inherit;font:inherit;outline:none}
+  .twk-field:focus{border-color:rgba(0,0,0,.25);background:rgba(255,255,255,.85)}
+  select.twk-field{padding-right:22px;
+    background-image:url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='10' height='6' viewBox='0 0 10 6'><path fill='rgba(0,0,0,.5)' d='M0 0h10L5 6z'/></svg>");
+    background-repeat:no-repeat;background-position:right 8px center}
+
+  .twk-slider{appearance:none;-webkit-appearance:none;width:100%;height:4px;margin:6px 0;
+    border-radius:999px;background:rgba(0,0,0,.12);outline:none}
+  .twk-slider::-webkit-slider-thumb{-webkit-appearance:none;appearance:none;
+    width:14px;height:14px;border-radius:50%;background:#fff;
+    border:.5px solid rgba(0,0,0,.12);box-shadow:0 1px 3px rgba(0,0,0,.2);cursor:default}
+  .twk-slider::-moz-range-thumb{width:14px;height:14px;border-radius:50%;
+    background:#fff;border:.5px solid rgba(0,0,0,.12);box-shadow:0 1px 3px rgba(0,0,0,.2);cursor:default}
+
+  .twk-seg{position:relative;display:flex;padding:2px;border-radius:8px;
+    background:rgba(0,0,0,.06);user-select:none}
+  .twk-seg-thumb{position:absolute;top:2px;bottom:2px;border-radius:6px;
+    background:rgba(255,255,255,.9);box-shadow:0 1px 2px rgba(0,0,0,.12);
+    transition:left .15s cubic-bezier(.3,.7,.4,1),width .15s}
+  .twk-seg.dragging .twk-seg-thumb{transition:none}
+  .twk-seg button{appearance:none;position:relative;z-index:1;flex:1;border:0;
+    background:transparent;color:inherit;font:inherit;font-weight:500;min-height:22px;
+    border-radius:6px;cursor:default;padding:4px 6px;line-height:1.2;
+    overflow-wrap:anywhere}
+
+  .twk-toggle{position:relative;width:32px;height:18px;border:0;border-radius:999px;
+    background:rgba(0,0,0,.15);transition:background .15s;cursor:default;padding:0}
+  .twk-toggle[data-on="1"]{background:#34c759}
+  .twk-toggle i{position:absolute;top:2px;left:2px;width:14px;height:14px;border-radius:50%;
+    background:#fff;box-shadow:0 1px 2px rgba(0,0,0,.25);transition:transform .15s}
+  .twk-toggle[data-on="1"] i{transform:translateX(14px)}
+
+  .twk-num{display:flex;align-items:center;height:26px;padding:0 0 0 8px;
+    border:.5px solid rgba(0,0,0,.1);border-radius:7px;background:rgba(255,255,255,.6)}
+  .twk-num-lbl{font-weight:500;color:rgba(41,38,27,.6);cursor:ew-resize;
+    user-select:none;padding-right:8px}
+  .twk-num input{flex:1;min-width:0;height:100%;border:0;background:transparent;
+    font:inherit;font-variant-numeric:tabular-nums;text-align:right;padding:0 8px 0 0;
+    outline:none;color:inherit;-moz-appearance:textfield}
+  .twk-num input::-webkit-inner-spin-button,.twk-num input::-webkit-outer-spin-button{
+    -webkit-appearance:none;margin:0}
+  .twk-num-unit{padding-right:8px;color:rgba(41,38,27,.45)}
+
+  .twk-btn{appearance:none;height:26px;padding:0 12px;border:0;border-radius:7px;
+    background:rgba(0,0,0,.78);color:#fff;font:inherit;font-weight:500;cursor:default}
+  .twk-btn:hover{background:rgba(0,0,0,.88)}
+  .twk-btn.secondary{background:rgba(0,0,0,.06);color:inherit}
+  .twk-btn.secondary:hover{background:rgba(0,0,0,.1)}
+
+  .twk-swatch{appearance:none;-webkit-appearance:none;width:56px;height:22px;
+    border:.5px solid rgba(0,0,0,.1);border-radius:6px;padding:0;cursor:default;
+    background:transparent;flex-shrink:0}
+  .twk-swatch::-webkit-color-swatch-wrapper{padding:0}
+  .twk-swatch::-webkit-color-swatch{border:0;border-radius:5.5px}
+  .twk-swatch::-moz-color-swatch{border:0;border-radius:5.5px}
+`;
+
+// ── useTweaks ───────────────────────────────────────────────────────────────
+// Single source of truth for tweak values. setTweak persists via the host
+// (__edit_mode_set_keys → host rewrites the EDITMODE block on disk).
+function useTweaks(defaults) {
+  const [values, setValues] = React.useState(defaults);
+  // Accepts either setTweak('key', value) or setTweak({ key: value, ... }) so a
+  // useState-style call doesn't write a "[object Object]" key into the persisted
+  // JSON block.
+  const setTweak = React.useCallback((keyOrEdits, val) => {
+    const edits = typeof keyOrEdits === 'object' && keyOrEdits !== null
+      ? keyOrEdits : { [keyOrEdits]: val };
+    setValues((prev) => ({ ...prev, ...edits }));
+    window.parent.postMessage({ type: '__edit_mode_set_keys', edits }, '*');
+  }, []);
+  return [values, setTweak];
+}
+
+// ── TweaksPanel ─────────────────────────────────────────────────────────────
+// Floating shell. Registers the protocol listener BEFORE announcing
+// availability — if the announce ran first, the host's activate could land
+// before our handler exists and the toolbar toggle would silently no-op.
+// The close button posts __edit_mode_dismissed so the host's toolbar toggle
+// flips off in lockstep; the host echoes __deactivate_edit_mode back which
+// is what actually hides the panel.
+function TweaksPanel({ title = 'Tweaks', children }) {
+  const [open, setOpen] = React.useState(false);
+  const dragRef = React.useRef(null);
+  const offsetRef = React.useRef({ x: 16, y: 16 });
+  const PAD = 16;
+
+  const clampToViewport = React.useCallback(() => {
+    const panel = dragRef.current;
+    if (!panel) return;
+    const w = panel.offsetWidth, h = panel.offsetHeight;
+    const maxRight = Math.max(PAD, window.innerWidth - w - PAD);
+    const maxBottom = Math.max(PAD, window.innerHeight - h - PAD);
+    offsetRef.current = {
+      x: Math.min(maxRight, Math.max(PAD, offsetRef.current.x)),
+      y: Math.min(maxBottom, Math.max(PAD, offsetRef.current.y)),
+    };
+    panel.style.right = offsetRef.current.x + 'px';
+    panel.style.bottom = offsetRef.current.y + 'px';
+  }, []);
+
+  React.useEffect(() => {
+    if (!open) return;
+    clampToViewport();
+    if (typeof ResizeObserver === 'undefined') {
+      window.addEventListener('resize', clampToViewport);
+      return () => window.removeEventListener('resize', clampToViewport);
+    }
+    const ro = new ResizeObserver(clampToViewport);
+    ro.observe(document.documentElement);
+    return () => ro.disconnect();
+  }, [open, clampToViewport]);
+
+  React.useEffect(() => {
+    const onMsg = (e) => {
+      const t = e?.data?.type;
+      if (t === '__activate_edit_mode') setOpen(true);
+      else if (t === '__deactivate_edit_mode') setOpen(false);
+    };
+    window.addEventListener('message', onMsg);
+    window.parent.postMessage({ type: '__edit_mode_available' }, '*');
+    return () => window.removeEventListener('message', onMsg);
+  }, []);
+
+  const dismiss = () => {
+    setOpen(false);
+    window.parent.postMessage({ type: '__edit_mode_dismissed' }, '*');
+  };
+
+  const onDragStart = (e) => {
+    const panel = dragRef.current;
+    if (!panel) return;
+    const r = panel.getBoundingClientRect();
+    const sx = e.clientX, sy = e.clientY;
+    const startRight = window.innerWidth - r.right;
+    const startBottom = window.innerHeight - r.bottom;
+    const move = (ev) => {
+      offsetRef.current = {
+        x: startRight - (ev.clientX - sx),
+        y: startBottom - (ev.clientY - sy),
+      };
+      clampToViewport();
+    };
+    const up = () => {
+      window.removeEventListener('mousemove', move);
+      window.removeEventListener('mouseup', up);
+    };
+    window.addEventListener('mousemove', move);
+    window.addEventListener('mouseup', up);
+  };
+
+  if (!open) return null;
+  return (
+    <>
+      <style>{__TWEAKS_STYLE}</style>
+      <div ref={dragRef} className="twk-panel"
+           style={{ right: offsetRef.current.x, bottom: offsetRef.current.y }}>
+        <div className="twk-hd" onMouseDown={onDragStart}>
+          <b>{title}</b>
+          <button className="twk-x" aria-label="Close tweaks"
+                  onMouseDown={(e) => e.stopPropagation()}
+                  onClick={dismiss}>✕</button>
+        </div>
+        <div className="twk-body">{children}</div>
+      </div>
+    </>
+  );
+}
+
+// ── Layout helpers ──────────────────────────────────────────────────────────
+
+function TweakSection({ label, children }) {
+  return (
+    <>
+      <div className="twk-sect">{label}</div>
+      {children}
+    </>
+  );
+}
+
+function TweakRow({ label, value, children, inline = false }) {
+  return (
+    <div className={inline ? 'twk-row twk-row-h' : 'twk-row'}>
+      <div className="twk-lbl">
+        <span>{label}</span>
+        {value != null && <span className="twk-val">{value}</span>}
+      </div>
+      {children}
+    </div>
+  );
+}
+
+// ── Controls ────────────────────────────────────────────────────────────────
+
+function TweakSlider({ label, value, min = 0, max = 100, step = 1, unit = '', onChange }) {
+  return (
+    <TweakRow label={label} value={`${value}${unit}`}>
+      <input type="range" className="twk-slider" min={min} max={max} step={step}
+             value={value} onChange={(e) => onChange(Number(e.target.value))} />
+    </TweakRow>
+  );
+}
+
+function TweakToggle({ label, value, onChange }) {
+  return (
+    <div className="twk-row twk-row-h">
+      <div className="twk-lbl"><span>{label}</span></div>
+      <button type="button" className="twk-toggle" data-on={value ? '1' : '0'}
+              role="switch" aria-checked={!!value}
+              onClick={() => onChange(!value)}><i /></button>
+    </div>
+  );
+}
+
+function TweakRadio({ label, value, options, onChange }) {
+  const trackRef = React.useRef(null);
+  const [dragging, setDragging] = React.useState(false);
+  const opts = options.map((o) => (typeof o === 'object' ? o : { value: o, label: o }));
+  const idx = Math.max(0, opts.findIndex((o) => o.value === value));
+  const n = opts.length;
+
+  // The active value is read by pointer-move handlers attached for the lifetime
+  // of a drag — ref it so a stale closure doesn't fire onChange for every move.
+  const valueRef = React.useRef(value);
+  valueRef.current = value;
+
+  const segAt = (clientX) => {
+    const r = trackRef.current.getBoundingClientRect();
+    const inner = r.width - 4;
+    const i = Math.floor(((clientX - r.left - 2) / inner) * n);
+    return opts[Math.max(0, Math.min(n - 1, i))].value;
+  };
+
+  const onPointerDown = (e) => {
+    setDragging(true);
+    const v0 = segAt(e.clientX);
+    if (v0 !== valueRef.current) onChange(v0);
+    const move = (ev) => {
+      if (!trackRef.current) return;
+      const v = segAt(ev.clientX);
+      if (v !== valueRef.current) onChange(v);
+    };
+    const up = () => {
+      setDragging(false);
+      window.removeEventListener('pointermove', move);
+      window.removeEventListener('pointerup', up);
+    };
+    window.addEventListener('pointermove', move);
+    window.addEventListener('pointerup', up);
+  };
+
+  return (
+    <TweakRow label={label}>
+      <div ref={trackRef} role="radiogroup" onPointerDown={onPointerDown}
+           className={dragging ? 'twk-seg dragging' : 'twk-seg'}>
+        <div className="twk-seg-thumb"
+             style={{ left: `calc(2px + ${idx} * (100% - 4px) / ${n})`,
+                      width: `calc((100% - 4px) / ${n})` }} />
+        {opts.map((o) => (
+          <button key={o.value} type="button" role="radio" aria-checked={o.value === value}>
+            {o.label}
+          </button>
+        ))}
+      </div>
+    </TweakRow>
+  );
+}
+
+function TweakSelect({ label, value, options, onChange }) {
+  return (
+    <TweakRow label={label}>
+      <select className="twk-field" value={value} onChange={(e) => onChange(e.target.value)}>
+        {options.map((o) => {
+          const v = typeof o === 'object' ? o.value : o;
+          const l = typeof o === 'object' ? o.label : o;
+          return <option key={v} value={v}>{l}</option>;
+        })}
+      </select>
+    </TweakRow>
+  );
+}
+
+function TweakText({ label, value, placeholder, onChange }) {
+  return (
+    <TweakRow label={label}>
+      <input className="twk-field" type="text" value={value} placeholder={placeholder}
+             onChange={(e) => onChange(e.target.value)} />
+    </TweakRow>
+  );
+}
+
+function TweakNumber({ label, value, min, max, step = 1, unit = '', onChange }) {
+  const clamp = (n) => {
+    if (min != null && n < min) return min;
+    if (max != null && n > max) return max;
+    return n;
+  };
+  const startRef = React.useRef({ x: 0, val: 0 });
+  const onScrubStart = (e) => {
+    e.preventDefault();
+    startRef.current = { x: e.clientX, val: value };
+    const decimals = (String(step).split('.')[1] || '').length;
+    const move = (ev) => {
+      const dx = ev.clientX - startRef.current.x;
+      const raw = startRef.current.val + dx * step;
+      const snapped = Math.round(raw / step) * step;
+      onChange(clamp(Number(snapped.toFixed(decimals))));
+    };
+    const up = () => {
+      window.removeEventListener('pointermove', move);
+      window.removeEventListener('pointerup', up);
+    };
+    window.addEventListener('pointermove', move);
+    window.addEventListener('pointerup', up);
+  };
+  return (
+    <div className="twk-num">
+      <span className="twk-num-lbl" onPointerDown={onScrubStart}>{label}</span>
+      <input type="number" value={value} min={min} max={max} step={step}
+             onChange={(e) => onChange(clamp(Number(e.target.value)))} />
+      {unit && <span className="twk-num-unit">{unit}</span>}
+    </div>
+  );
+}
+
+function TweakColor({ label, value, onChange }) {
+  return (
+    <div className="twk-row twk-row-h">
+      <div className="twk-lbl"><span>{label}</span></div>
+      <input type="color" className="twk-swatch" value={value}
+             onChange={(e) => onChange(e.target.value)} />
+    </div>
+  );
+}
+
+function TweakButton({ label, onClick, secondary = false }) {
+  return (
+    <button type="button" className={secondary ? 'twk-btn secondary' : 'twk-btn'}
+            onClick={onClick}>{label}</button>
+  );
+}
+
+Object.assign(window, {
+  useTweaks, TweaksPanel, TweakSection, TweakRow,
+  TweakSlider, TweakToggle, TweakRadio, TweakSelect,
+  TweakText, TweakNumber, TweakColor, TweakButton,
+});
diff --git a/src/core/completions.js b/src/core/completions.js
new file mode 100644
index 0000000..ef0dbf6
--- /dev/null
+++ b/src/core/completions.js
@@ -0,0 +1,174 @@
+// Pure completion logic for the SQL editor (#25/#26). No DOM, no globals.
+//
+// Reference data (keywords + function metadata) is loaded once per connection
+// from ClickHouse system tables (see net/ch-client.js loadReferenceData) and
+// assembled here into the in-memory shape the editor reads on the keystroke
+// path — never a query per keystroke. `assembleReferenceData` falls back to the
+// built-in tokenizer sets when the server didn't supply them.
+
+import { SQL_KEYWORDS, SQL_FUNCS } from './sql-highlight.js';
+
+const BUILTIN_KEYWORDS = [...SQL_KEYWORDS];
+const BUILTIN_FUNCS = [...SQL_FUNCS];
+
+// Built-in hover docs for a few ClickHouse-specific keywords (#27). There's no
+// server table for keyword docs, so this static set covers the high-value ones;
+// function docs come from system.functions (loaded per connection).
+const KEYWORD_DOCS = {
+  PREWHERE: 'ClickHouse filter applied before reading other columns — an optimization over WHERE for selective predicates.',
+  FINAL: 'Merges rows with the same key at read time (ReplacingMergeTree etc.). Expensive; avoid on hot paths.',
+  SAMPLE: 'Reads a deterministic fraction of data for approximate results. Requires a SAMPLE BY key on the table.',
+  LIMIT: 'Caps the number of returned rows. LIMIT n BY expr limits per group.',
+  SETTINGS: 'Per-query settings override, e.g. SETTINGS max_threads = 4.',
+  FORMAT: 'Sets the output format of the query, e.g. FORMAT JSONEachRow.',
+};
+
+/**
+ * Turn a loaded reference payload (or null) into the editor's in-memory shape:
+ *   { keywords: string[],            // completion candidates
+ *     functions: { name: {kind,sig,ret,desc} },
+ *     keywordSet: Set<UPPER>,        // tokenizer highlight lookup
+ *     funcSet: Set<name> }           // tokenizer highlight lookup
+ * Missing pieces fall back to the built-in sets so highlighting + keyword/
+ * function completion still work offline / on older ClickHouse.
+ */
+export function assembleReferenceData(loaded) {
+  const keywords = loaded && loaded.keywords && loaded.keywords.length
+    ? loaded.keywords
+    : BUILTIN_KEYWORDS;
+  const functions = loaded && loaded.functions && Object.keys(loaded.functions).length
+    ? loaded.functions
+    : Object.fromEntries(BUILTIN_FUNCS.map((name) => [name, { kind: 'fn', sig: name + '()', ret: '', desc: '' }]));
+  return {
+    keywords,
+    functions,
+    keywordDocs: KEYWORD_DOCS, // for hover docs (#27); static built-in set
+    keywordSet: new Set(keywords.map((k) => k.toUpperCase())),
+    funcSet: new Set(Object.keys(functions)),
+  };
+}
+
+/**
+ * Build the flat completion candidate list from reference data + the in-memory
+ * schema. Schema is the repo shape ([{db, tables:[{name, columns}]}]); only
+ * already-loaded columns are included (`tb.columns` is an array, not null /
+ * 'loading') — no on-demand column fetch from the completion path (#25/#26).
+ */
+export function buildCompletions(ref, schema) {
+  const items = [];
+  for (const k of ref.keywords) {
+    items.push({ label: k, kind: 'keyword', insert: k, detail: 'keyword' });
+  }
+  for (const [name, m] of Object.entries(ref.functions)) {
+    const kind = m.kind === 'agg' ? 'agg' : m.kind === 'cast' ? 'cast' : 'fn';
+    // The label already shows the function name, so the detail column shows only
+    // the parenthesised params — `(s, offset[, …])`, not `substring(s, …)` (#26).
+    const sig = m.sig || name + '()';
+    const paren = sig.indexOf('(');
+    items.push({ label: name, kind, insert: name + '(', detail: paren >= 0 ? sig.slice(paren) : sig, doc: m.desc || '', ret: m.ret || '' });
+  }
+  for (const db of schema || []) {
+    items.push({ label: db.db, kind: 'db', insert: db.db, detail: 'database' });
+    for (const tb of db.tables || []) {
+      items.push({ label: tb.name, kind: 'table', insert: tb.name, detail: 'table', parent: db.db });
+      if (Array.isArray(tb.columns)) {
+        for (const c of tb.columns) {
+          items.push({ label: c.name, kind: 'column', insert: c.name, detail: c.type, parent: tb.name });
+        }
+      }
+    }
+  }
+  return items;
+}
+
+/**
+ * The word being typed at the caret, and whether it is qualified (after a dot —
+ * `table.` → that table's columns). Returns {word, from, to, qualified, parent}.
+ */
+export function completionContext(value, pos) {
+  let s = pos;
+  while (s > 0 && /[A-Za-z0-9_]/.test(value[s - 1])) s--;
+  const word = value.slice(s, pos);
+  let qualified = false;
+  let parent = null;
+  if (value[s - 1] === '.') {
+    let p = s - 1;
+    while (p > 0 && /[A-Za-z0-9_]/.test(value[p - 1])) p--;
+    const name = value.slice(p, s - 1);
+    // Only qualified when a real identifier precedes the dot. A bare '.' after a
+    // non-identifier (`.col`, `).c`, `count().c`) would otherwise yield parent=''
+    // and an empty dropdown — fall back to normal completion instead (#4 review).
+    if (name) { qualified = true; parent = name; }
+  }
+  return { word, from: s, to: pos, qualified, parent };
+}
+
+/**
+ * Rank candidates for `ctx`. Qualified → only that table's columns. Otherwise
+ * prefix matches before substring; columns/tables boosted over keywords once
+ * ≥1 char is typed. Empty word (and not qualified) → keywords + tables only.
+ * Capped for a tight dropdown.
+ */
+export function rankCompletions(items, ctx) {
+  const w = ctx.word.toLowerCase();
+  if (ctx.qualified) {
+    const cols = items.filter((it) => it.kind === 'column' && it.parent === ctx.parent);
+    return (w ? cols.filter((c) => c.label.toLowerCase().includes(w)) : cols).slice(0, 50);
+  }
+  if (!w) {
+    return items.filter((it) => it.kind === 'keyword' || it.kind === 'table').slice(0, 40);
+  }
+  const scored = [];
+  for (const it of items) {
+    const l = it.label.toLowerCase();
+    const idx = l.indexOf(w);
+    if (idx === -1) continue;
+    let score = idx === 0 ? 0 : 100 + idx;              // prefix beats substring
+    if (it.kind === 'column' || it.kind === 'table') score -= 10; // boost schema
+    if (it.kind === 'keyword') score += 5;
+    score += (l.length - w.length) * 0.1;               // prefer closer length
+    scored.push({ it, score });
+  }
+  scored.sort((a, b) => a.score - b.score || a.it.label.localeCompare(b.it.label));
+  return scored.slice(0, 50).map((s) => s.it);
+}
+
+/**
+ * The identifier word containing `pos` (expands in both directions). Used by
+ * hover docs (#27) to find the token under the mouse. Returns {word, from, to}
+ * or null when `pos` isn't inside a word.
+ */
+export function wordAt(value, pos) {
+  let s = pos;
+  let e = pos;
+  while (s > 0 && /[A-Za-z0-9_]/.test(value[s - 1])) s--;
+  while (e < value.length && /[A-Za-z0-9_]/.test(value[e])) e++;
+  if (s === e) return null;
+  return { word: value.slice(s, e), from: s, to: e };
+}
+
+/**
+ * If `pos` is inside a function call `name(… )`, return {name, argIdx} — the
+ * enclosing function and which argument the caret is on (commas counted at
+ * depth 0). Used by signature help (#27). Returns null outside a call; a `;` or
+ * newline at depth 0 ends the search (don't cross statements/lines).
+ */
+export function signatureContext(value, pos) {
+  let depth = 0;
+  let argIdx = 0;
+  for (let i = pos - 1; i >= 0; i--) {
+    const c = value[i];
+    if (c === ')') depth++;
+    else if (c === '(') {
+      if (depth === 0) {
+        let e = i;
+        while (e > 0 && /[A-Za-z0-9_]/.test(value[e - 1])) e--;
+        const name = value.slice(e, i);
+        return name ? { name, argIdx } : null;
+      }
+      depth--;
+    } else if (c === ',' && depth === 0) argIdx++;
+    else if ((c === ';' || c === '\n') && depth === 0) return null;
+  }
+  return null;
+}
diff --git a/src/core/editor-brackets.js b/src/core/editor-brackets.js
new file mode 100644
index 0000000..a565d24
--- /dev/null
+++ b/src/core/editor-brackets.js
@@ -0,0 +1,86 @@
+// Pure bracket logic for the editor (#24): caret-adjacent pair matching and the
+// auto-close / wrap / type-over / pair-delete decision. No DOM.
+
+// Auto-close pairs. `{`/`}` is deliberately excluded (niche ClickHouse JSON
+// context) per the resolved Phase-1b decision; bracket *matching* still spans
+// it (MATCH_* below) since highlighting a `{}` pair is harmless and useful.
+const OPEN = { '(': ')', '[': ']' };
+const QUOTES = new Set(["'", '"', '`']);
+const CLOSERS = new Set([')', ']', '}']);
+const MATCH_OPEN = { '(': ')', '[': ']', '{': '}' };
+const MATCH_CLOSE = { ')': '(', ']': '[', '}': '{' };
+
+// Walk from `idx` in `dir` (+1 from an opener, -1 from a closer) tracking nesting
+// depth; return [openIdx, closeIdx] for the matched pair, or null if unbalanced
+// or `idx` is not the expected bracket.
+function scan(value, idx, dir) {
+  const ch = value[idx];
+  if (dir === 1 && MATCH_OPEN[ch]) {
+    let depth = 0;
+    for (let k = idx; k < value.length; k++) {
+      if (value[k] === ch) depth++;
+      else if (value[k] === MATCH_OPEN[ch]) { depth--; if (depth === 0) return [idx, k]; }
+    }
+  } else if (dir === -1 && MATCH_CLOSE[ch]) {
+    let depth = 0;
+    for (let k = idx; k >= 0; k--) {
+      if (value[k] === ch) depth++;
+      else if (value[k] === MATCH_CLOSE[ch]) { depth--; if (depth === 0) return [k, idx]; }
+    }
+  }
+  return null;
+}
+
+/**
+ * The bracket pair adjacent to `caret`: an opener at value[caret] (scan forward)
+ * or a closer at value[caret-1] (scan backward). Returns [openIdx, closeIdx] or
+ * null.
+ */
+export function matchBracketAt(value, caret) {
+  return scan(value, caret, 1) || (caret > 0 ? scan(value, caret - 1, -1) : null);
+}
+
+/**
+ * Decide the edit for a key pressed at selection [s, e]. Returns
+ * { value, selStart, selEnd } to apply, or null when the key isn't a bracket
+ * action (the caller falls through to its normal handling).
+ *   • opener: wrap a selection, else insert the pair with the caret inside
+ *   • quote: wrap a selection, type over an existing quote, else auto-close
+ *   • closer: type over an existing matching closer
+ *   • Backspace inside an empty ()/[]/'' pair: delete both halves
+ * When `inLiteral` (the caret sits inside a string/comment), auto-pairing is
+ * suppressed — typing `(` in 'O(' must not insert a stray `)` — but type-over of
+ * an existing quote/closer still works so the literal can be closed normally.
+ */
+export function bracketEdit(value, s, e, key, inLiteral = false) {
+  if (OPEN[key] && !inLiteral) {
+    const close = OPEN[key];
+    if (s !== e) {
+      return { value: value.slice(0, s) + key + value.slice(s, e) + close + value.slice(e), selStart: s + 1, selEnd: e + 1 };
+    }
+    return { value: value.slice(0, s) + key + close + value.slice(e), selStart: s + 1, selEnd: s + 1 };
+  }
+  if (QUOTES.has(key)) {
+    if (s === e && value[s] === key) {
+      return { value, selStart: s + 1, selEnd: s + 1 }; // type over an existing quote (closes the literal)
+    }
+    if (!inLiteral) {
+      if (s !== e) {
+        return { value: value.slice(0, s) + key + value.slice(s, e) + key + value.slice(e), selStart: s + 1, selEnd: e + 1 };
+      }
+      return { value: value.slice(0, s) + key + key + value.slice(e), selStart: s + 1, selEnd: s + 1 };
+    }
+    // inside a literal and not a type-over → let the quote type normally
+  }
+  if (CLOSERS.has(key) && s === e && value[s] === key) {
+    return { value, selStart: s + 1, selEnd: s + 1 }; // type over the auto-inserted closer
+  }
+  if (key === 'Backspace' && s === e && s > 0) {
+    const prev = value[s - 1];
+    const next = value[s];
+    if ((OPEN[prev] && next === OPEN[prev]) || (QUOTES.has(prev) && next === prev)) {
+      return { value: value.slice(0, s - 1) + value.slice(s + 1), selStart: s - 1, selEnd: s - 1 };
+    }
+  }
+  return null;
+}
diff --git a/src/core/editor-geometry.js b/src/core/editor-geometry.js
new file mode 100644
index 0000000..2224102
--- /dev/null
+++ b/src/core/editor-geometry.js
@@ -0,0 +1,46 @@
+// Pure caret geometry for positioning the autocomplete popover (#26). No DOM.
+//
+// The editor is `white-space: pre` in a fixed-size monospace font, so a caret's
+// pixel offset is plain line/column arithmetic — char width is passed in by the
+// caller (a constant tuned to the font; see CHAR_WIDTH_PX in editor.js) rather
+// than measured, keeping this fully testable. If a proportional font or soft
+// wrapping is ever introduced, switch to a mirror-div measurement.
+
+/** Zero-based {line, col} of caret position `pos` within `value`. */
+export function caretLineCol(value, pos) {
+  const before = value.slice(0, pos);
+  return { line: before.split('\n').length - 1, col: pos - (before.lastIndexOf('\n') + 1) };
+}
+
+/**
+ * Pixel offset of the caret within the editor's text area, accounting for
+ * padding and the current scroll.
+ * @param m { charWidth, lhPx, padX, padY, scrollTop, scrollLeft }
+ */
+export function caretXY(value, pos, m) {
+  const { line, col } = caretLineCol(value, pos);
+  return {
+    x: m.padX + col * m.charWidth - (m.scrollLeft || 0),
+    y: m.padY + line * m.lhPx - (m.scrollTop || 0),
+  };
+}
+
+/**
+ * Inverse of caretXY for hover (#27): the text offset at a point, where relX/relY
+ * are already in CSS px relative to the text origin (after padding + scroll).
+ * Returns null when the point is outside the text's lines, OR past the end of a
+ * short line's glyphs — otherwise a dwell in the blank space right of e.g.
+ * `SELECT count` would map to the end of `count` and pop a phantom hover card
+ * nowhere near a token (#27). A half-column tolerance keeps the last glyph live.
+ */
+export function offsetFromXY(value, relX, relY, m) {
+  const lines = value.split('\n');
+  const line = Math.floor(relY / m.lhPx);
+  if (line < 0 || line >= lines.length) return null;
+  const rawCol = relX / m.charWidth;
+  if (rawCol > lines[line].length + 0.5) return null; // beyond the line's glyphs
+  const col = Math.max(0, Math.min(Math.round(rawCol), lines[line].length));
+  let pos = 0;
+  for (let k = 0; k < line; k++) pos += lines[k].length + 1;
+  return pos + col;
+}
diff --git a/src/core/editor-marks.js b/src/core/editor-marks.js
new file mode 100644
index 0000000..458b5e6
--- /dev/null
+++ b/src/core/editor-marks.js
@@ -0,0 +1,30 @@
+// Pure segmentation for the editor's transparent mark overlay (#23 search
+// highlights, #24 bracket pair). No DOM.
+//
+// The overlay is a second `color: transparent` <pre> layered below the token
+// <pre>; only the marked spans carry a background, so the token render path is
+// never touched. This splits `value` into ordered {text, cls} segments — the
+// DOM painter renders cls != null with a `mark-<cls>` background span and the
+// rest as plain (transparent) text, keeping the overlay's layout identical to
+// the editor's for pixel-aligned highlights.
+
+/**
+ * @param value the full editor text
+ * @param marks [{start, end, cls}] — half-open ranges, **sorted by start and
+ *   non-overlapping**. They always are here: search matches come back in order
+ *   and disjoint, and the bracket pair (the only other source, never mixed with
+ *   search marks) is two sorted width-1 ranges. The single linear pass keeps the
+ *   keystroke path off a quadratic per-segment scan.
+ * @returns [{text, cls|null}] covering the whole string in order.
+ */
+export function buildMarkSegments(value, marks) {
+  const out = [];
+  let pos = 0;
+  for (const m of marks) {
+    if (m.start > pos) out.push({ text: value.slice(pos, m.start), cls: null });
+    out.push({ text: value.slice(m.start, m.end), cls: m.cls });
+    pos = m.end;
+  }
+  if (pos < value.length || !out.length) out.push({ text: value.slice(pos), cls: null });
+  return out;
+}
diff --git a/src/core/editor-search.js b/src/core/editor-search.js
new file mode 100644
index 0000000..db58e01
--- /dev/null
+++ b/src/core/editor-search.js
@@ -0,0 +1,39 @@
+// Pure find/replace matching for the in-editor search panel (#23). No DOM.
+
+/**
+ * All matches of `query` in `value`, in order, as [{start, end}]. Plain mode
+ * escapes the query; regex mode compiles it directly. Whole-word fences the
+ * pattern with `\b…\b` in BOTH modes (regex is wrapped in a non-capturing group
+ * so the boundaries apply to the whole pattern). Case-insensitive unless
+ * `caseSensitive`. An empty query or an invalid regex yields [] (the panel
+ * surfaces the error separately). Zero-width matches (e.g. `a*`, `^`, `$`) are
+ * skipped — they have no text to highlight or replace — while still advancing
+ * the scan; the total is capped so a pathological pattern can't hang typing.
+ */
+export function findMatches(value, query, opts = {}) {
+  if (!query) return [];
+  const { caseSensitive = false, regex = false, wholeWord = false } = opts;
+  let re;
+  try {
+    let pat = regex ? query : query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (wholeWord) pat = '\\b' + (regex ? '(?:' + pat + ')' : pat) + '\\b';
+    re = new RegExp(pat, caseSensitive ? 'g' : 'gi');
+  } catch {
+    return [];
+  }
+  const matches = [];
+  let m;
+  let guard = 0;
+  while ((m = re.exec(value)) !== null) {
+    if (++guard > 10000) break;
+    if (m.index === re.lastIndex) { re.lastIndex++; continue; } // skip zero-width, keep advancing
+    matches.push({ start: m.index, end: m.index + m[0].length });
+  }
+  return matches;
+}
+
+/** Whether `query` is usable (only meaningful in regex mode). */
+export function validRegex(query, regex) {
+  if (!regex || !query) return true;
+  try { new RegExp(query); return true; } catch { return false; }
+}
diff --git a/src/core/sql-highlight.js b/src/core/sql-highlight.js
index 0651af8..2729cc3 100644
--- a/src/core/sql-highlight.js
+++ b/src/core/sql-highlight.js
@@ -26,8 +26,14 @@ export const SQL_FUNCS = new Set([
  * Tokenize SQL into [type, text] pairs. Types: comment, string, ident,
  * number, keyword, func, op, ws, other. The `ident` type covers backtick /
  * double-quoted identifiers and bare words that are neither keyword nor func.
+ *
+ * The optional second arg lets a caller override the keyword/function sets
+ * (#25) — e.g. the server's `system.keywords` / `system.functions` — so
+ * highlighting is version-correct. It is backward-compatible: existing callers
+ * pass nothing and get the built-in sets. `keywords` is matched
+ * case-insensitively (uppercased lookup); `funcs` is matched as-is.
  */
-export function tokenize(sql) {
+export function tokenize(sql, { keywords = SQL_KEYWORDS, funcs = SQL_FUNCS } = {}) {
   const out = [];
   let i = 0;
   const n = sql.length;
@@ -75,8 +81,8 @@ export function tokenize(sql) {
       const word = sql.slice(i, j);
       const upper = word.toUpperCase();
       let type = 'ident';
-      if (SQL_KEYWORDS.has(upper)) type = 'keyword';
-      else if (SQL_FUNCS.has(word)) type = 'func';
+      if (keywords.has(upper)) type = 'keyword';
+      else if (funcs.has(word)) type = 'func';
       out.push([type, word]);
       i = j;
       continue;
@@ -98,3 +104,27 @@ export function tokenize(sql) {
   }
   return out;
 }
+
+// A same-length copy of `sql` with every string-literal, comment, and
+// backtick-quoted-identifier character replaced by NUL ('\0'). Bracket matching
+// (#24), signature help (#27), and auto-close decisions run on this so that
+// brackets/quotes/commas inside literals don't pair, count as arguments, or
+// trigger auto-close. NUL is none of `(),;\n`, so the raw-char scanners skip it.
+// Offsets are preserved (same length), so indices map back to the real text.
+export function maskFromTokens(tokens) {
+  let out = '';
+  for (const [t, v] of tokens) {
+    const literal = t === 'string' || t === 'comment' || (t === 'ident' && v[0] === '`');
+    out += literal ? '\0'.repeat(v.length) : v;
+  }
+  return out;
+}
+
+// Convenience wrapper that tokenizes then masks. Callers on the keystroke path
+// that already tokenized for highlighting should reuse maskFromTokens with that
+// token list instead, to avoid a second pass (#5 review). String/comment
+// classification is independent of the keyword/func sets, so a token list built
+// with server keyword overrides yields the same mask.
+export function maskLiterals(sql) {
+  return maskFromTokens(tokenize(sql));
+}
diff --git a/src/net/ch-client.js b/src/net/ch-client.js
index 81a4ec0..9353afb 100644
--- a/src/net/ch-client.js
+++ b/src/net/ch-client.js
@@ -138,6 +138,86 @@ export async function loadColumns(ctx, db, table, sqlString) {
   return (json.data || []).map((r) => ({ name: r.name, type: r.type, comment: r.comment || '' }));
 }
 
+// Run a query for its `data` rows, returning null on ANY error. Editor
+// reference data is best-effort: a missing system table on older ClickHouse (or
+// a denied SELECT) must degrade gracefully, never surface as a query error.
+async function tryQueryData(ctx, sql) {
+  try {
+    const json = await queryJson(ctx, sql);
+    return json.data || [];
+  } catch {
+    return null;
+  }
+}
+
+// First non-empty line of a (possibly multi-line / Markdown) cell, trimmed.
+// ClickHouse doc cells (system.functions.syntax/description) frequently begin
+// with a blank line, so skip leading empties and return the first line that
+// actually has content — taking the literal first line yields '' for them.
+function firstLine(s) {
+  if (!s) return '';
+  for (const line of String(s).split('\n')) {
+    const t = line.trim();
+    if (t) return t;
+  }
+  return '';
+}
+
+/**
+ * Load editor reference data once per connection: the server's keyword list and
+ * function metadata (name, kind, and — where the server exposes it — the
+ * `syntax` signature for signature help, #27), so highlighting + autocomplete +
+ * signature help are version-correct. This is the only *bulk* reference fetch;
+ * everything then runs off this in-memory data, never a query per keystroke (the
+ * keystroke rule, #25). Hover descriptions are NOT loaded here — they are large
+ * and most are never read — they're fetched on demand per entity and cached
+ * (loadEntityDoc, #27). Each source is best-effort; a missing/denied system
+ * table yields null for that piece and the caller (assembleReferenceData) falls
+ * back to the built-in set.
+ * Returns { keywords: string[]|null, functions: {name:{kind,sig,ret,desc}}|null }.
+ */
+export async function loadReferenceData(ctx) {
+  const kw = await tryQueryData(ctx, 'SELECT keyword FROM system.keywords FORMAT JSON');
+  const keywords = kw ? kw.map((r) => r.keyword) : null;
+  // Prefer the `syntax` column (modern ClickHouse) for signature help; fall back
+  // to the minimal shape when it doesn't exist (older servers) so we still get
+  // names for highlighting + completion.
+  const fn = await tryQueryData(ctx, 'SELECT name, is_aggregate, syntax FROM system.functions FORMAT JSON')
+    || await tryQueryData(ctx, 'SELECT name, is_aggregate FROM system.functions FORMAT JSON');
+  let functions = null;
+  if (fn) {
+    functions = {};
+    for (const r of fn) {
+      functions[r.name] = {
+        kind: r.is_aggregate ? 'agg' : 'fn',
+        sig: firstLine(r.syntax) || r.name + '()',
+        ret: '',
+        desc: '', // hover docs are fetched lazily per entity + cached (loadEntityDoc, #27)
+      };
+    }
+  }
+  return { keywords, functions };
+}
+
+/**
+ * Fetch one function's documentation on demand for hover docs (#27). Kept OUT of
+ * the bulk reference load: descriptions are large and most are never hovered, so
+ * loading every one would bloat connect time. The caller (app.entityDoc) caches
+ * the result so each entity is queried at most once per connection. Returns the
+ * first non-empty line (CH descriptions begin with a blank line), `''` when the
+ * query SUCCEEDS but there's no description (unknown name / older server / blank),
+ * or `null` when the query itself FAILED — so the caller can cache the former but
+ * retry the latter rather than sticking a transient error (#8 review).
+ */
+export async function loadEntityDoc(ctx, name, sqlString) {
+  const rows = await tryQueryData(
+    ctx,
+    'SELECT description FROM system.functions WHERE name = ' + sqlString(name) + ' LIMIT 1 FORMAT JSON',
+  );
+  if (rows === null) return null;                  // query failed → retryable, don't cache
+  return rows[0] ? firstLine(rows[0].description) : ''; // succeeded → '' means genuinely no doc
+}
+
 /**
  * Run a query in streaming mode (JSONStringsEachRowWithProgress) or raw mode
  * (TSV/JSON). `onLine(parsedObj)` is called per stream object in streaming
diff --git a/src/styles.css b/src/styles.css
index 45723d4..e05cbaf 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -763,6 +763,7 @@ body {
   font-family: inherit; font-size: inherit; line-height: inherit;
   color: inherit;
   white-space: pre;
+  tab-size: 2; /* match .sql-textarea so tabs in pasted SQL align with the glyphs */
   overflow: hidden;
   pointer-events: none;
 }
@@ -800,6 +801,125 @@ body {
 .sql-ident { color: var(--fg); }
 .sql-op { color: var(--fg-mute); }
 
+/* Mark overlay (#23 search highlights, #24 bracket pair): transparent <pre>
+   below the token <pre>; only the marked spans paint a background. */
+.sql-mark-overlay {
+  position: absolute; inset: 0; margin: 0;
+  padding: 12px 14px;
+  font-family: inherit; font-size: inherit; line-height: inherit;
+  color: transparent;
+  white-space: pre;
+  tab-size: 2; /* match .sql-textarea so highlights line up on tabbed lines */
+  overflow: hidden;
+  pointer-events: none;
+}
+.mark-match { background: color-mix(in oklab, var(--accent) 24%, transparent); border-radius: 2px; }
+.mark-active { background: color-mix(in oklab, var(--accent) 55%, transparent); border-radius: 2px; }
+.mark-bracket { background: color-mix(in oklab, var(--accent) 34%, transparent); border-radius: 2px; }
+
+/* Find/replace panel (#23) — floats over the top-right of the editor. */
+.sql-search {
+  position: absolute; top: 8px; right: 14px; z-index: 5;
+  display: flex; gap: 6px; align-items: flex-start;
+  background: var(--bg-modal); border: 1px solid var(--border);
+  border-radius: 8px; box-shadow: 0 10px 30px rgba(0, 0, 0, .32); padding: 7px;
+}
+.srch-disc {
+  width: 18px; align-self: stretch; border: none; background: transparent;
+  color: var(--fg-faint); cursor: pointer; border-radius: 4px;
+  display: flex; align-items: center; justify-content: center;
+  transform: rotate(-90deg); transition: transform .15s;
+}
+.srch-disc.open { transform: none; }
+.srch-rows { display: flex; flex-direction: column; gap: 6px; }
+.srch-row { display: flex; align-items: center; gap: 4px; }
+.srch-field {
+  width: 180px; height: 26px; padding: 0 8px;
+  background: var(--bg-input); border: 1px solid var(--border); border-radius: 6px;
+  color: var(--fg); font-size: 12px; font-family: var(--mono); outline: none;
+}
+.srch-field.bad { border-color: #ef4444; }
+.srch-count {
+  min-width: 50px; text-align: center; font-size: 11px;
+  font-family: var(--mono); color: var(--fg-faint);
+}
+.srch-count.bad { color: #ef4444; }
+.srch-nav {
+  width: 24px; height: 22px; border: none; border-radius: 4px;
+  background: transparent; color: var(--fg-mute); cursor: pointer;
+  display: flex; align-items: center; justify-content: center; font-size: 12px;
+}
+.srch-nav:hover { background: var(--bg-hover); color: var(--fg); }
+.srch-togs { display: flex; gap: 2px; margin-left: 2px; }
+.srch-tog {
+  width: 24px; height: 22px; border: none; border-radius: 4px;
+  background: var(--bg-chip); color: var(--fg-mute); cursor: pointer;
+  font-family: var(--mono); font-size: 11px; font-weight: 600;
+}
+.srch-tog.on { background: var(--accent); color: #fff; }
+.srch-btn {
+  height: 22px; padding: 0 8px; border: none; border-radius: 4px;
+  background: var(--bg-chip); color: var(--fg); cursor: pointer; font-size: 11px;
+}
+.srch-btn.primary { background: var(--accent); color: #fff; }
+
+/* Autocomplete dropdown (#26) — fixed-positioned at the caret. */
+.ac-dropdown {
+  position: fixed; z-index: 50; width: 320px; max-height: 248px;
+  display: flex; flex-direction: column; overflow: hidden;
+  background: var(--bg-modal); border: 1px solid var(--border);
+  border-radius: 8px; box-shadow: 0 12px 34px rgba(0, 0, 0, .4);
+  font-family: var(--ui);
+}
+.ac-list { flex: 1; min-height: 0; overflow-y: auto; padding: 4px; }
+.ac-row {
+  display: flex; align-items: center; gap: 9px;
+  padding: 5px 8px; border-radius: 5px; cursor: pointer;
+}
+.ac-row.on { background: color-mix(in oklab, var(--accent) 20%, transparent); }
+.ac-chip {
+  width: 17px; height: 17px; flex-shrink: 0; border-radius: 4px;
+  display: flex; align-items: center; justify-content: center;
+  background: var(--bg-chip); font-family: var(--mono); font-size: 11px; font-weight: 700;
+}
+.ac-label { font-family: var(--mono); font-size: 12.5px; color: var(--fg); flex-shrink: 0; }
+.ac-detail {
+  margin-left: auto; max-width: 150px; text-align: right;
+  font-family: var(--mono); font-size: 10.5px; color: var(--fg-faint);
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.ac-footer {
+  flex-shrink: 0; padding: 7px 10px; background: var(--bg-chip);
+  border-top: 1px solid var(--border-faint);
+  font-size: 11px; color: var(--fg-mute); line-height: 1.45;
+  display: flex; flex-direction: column; gap: 3px;
+}
+/* The footer shows the active entry's description (#27). Clamp it so a long
+   description can't balloon the footer and squeeze the scrolling list. */
+.ac-doc { display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }
+
+/* Signature help + hover docs (#27) — fixed-positioned near the caret/mouse. */
+.sig-help {
+  position: fixed; z-index: 55; max-width: 360px;
+  padding: 6px 10px; border-radius: 7px;
+  background: var(--bg-modal); border: 1px solid var(--border);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, .35);
+  font-family: var(--mono); font-size: 12px; color: var(--fg-mute); white-space: nowrap;
+}
+.sig-name { color: var(--fg); }
+.sig-arg.on { color: var(--accent); font-weight: 700; }
+.sig-ret { color: var(--fg-faint); }
+.hover-card {
+  position: fixed; z-index: 55; width: 280px;
+  padding: 9px 11px; border-radius: 8px;
+  background: var(--bg-modal); border: 1px solid var(--border);
+  box-shadow: 0 12px 34px rgba(0, 0, 0, .4);
+  font-family: var(--ui); pointer-events: none;
+}
+.hover-sig { font-family: var(--mono); font-size: 12px; color: var(--fg); margin-bottom: 5px; }
+.hover-ret { color: var(--fg-faint); }
+.hover-doc { font-size: 11.5px; color: var(--fg-mute); line-height: 1.5; }
+
 /* ------------ results ------------ */
 .results { display: flex; flex-direction: column; height: 100%; min-height: 0; }
 .res-toolbar {
diff --git a/src/ui/app.js b/src/ui/app.js
index 2c64868..2804958 100644
--- a/src/ui/app.js
+++ b/src/ui/app.js
@@ -17,6 +17,7 @@ import { buildExportDoc, parseImportDoc } from '../core/saved-io.js';
 import { toTSV, toCSV } from '../core/export.js';
 import { newResult, applyStreamLine } from '../core/stream.js';
 import { encodeShare } from '../core/share.js';
+import { assembleReferenceData, buildCompletions } from '../core/completions.js';
 import { generatePKCE, randomState } from '../core/pkce.js';
 import * as oauthCfg from '../net/oauth-config.js';
 import * as oauth from '../net/oauth.js';
@@ -279,9 +280,43 @@ export function createApp(env = {}) {
     } catch (e) {
       app.state.schemaError = String((e && e.message) || e);
     }
+    app.rebuildCompletions();
     renderSchema(app);
     updateBanner();
   };
+  // Editor reference data + autocomplete candidates. Loaded once per connection
+  // (the keystroke rule, #25): keywords/functions drive both version-correct
+  // highlighting and the autocomplete list; completion then runs client-side.
+  app.refData = assembleReferenceData(null); // built-in fallback until loaded
+  app.rebuildCompletions = () => {
+    app.completions = buildCompletions(app.refData, app.state.schema);
+  };
+  app.rebuildCompletions();
+  // Hover docs (#27) are fetched on demand per entity and cached for reuse —
+  // descriptions are large, so they stay out of the bulk reference load. The
+  // cache holds the resolved string (incl. '' for no-doc / error) so each entity
+  // is queried at most once per connection; an in-flight promise is cached too
+  // to dedupe concurrent hovers of the same word.
+  app.docCache = new Map();
+  app.entityDoc = (name) => {
+    if (app.docCache.has(name)) return Promise.resolve(app.docCache.get(name));
+    const p = ensureConfig().then(() => ch.loadEntityDoc(chCtx, name, sqlString));
+    app.docCache.set(name, p); // dedupe concurrent hovers of the same name
+    p.then((doc) => {
+      // Cache a resolved doc ('' included = genuinely no doc), but DROP a failed
+      // fetch (null) so a transient error doesn't suppress it for the session (#8).
+      if (doc === null) app.docCache.delete(name);
+      else app.docCache.set(name, doc);
+    });
+    return p;
+  };
+  app.loadReference = async () => {
+    await ensureConfig();
+    app.refData = assembleReferenceData(await ch.loadReferenceData(chCtx));
+    app.docCache.clear(); // re-fetch hover docs against the (possibly new) connection
+    app.rebuildCompletions();
+    if (app.dom.editorSync) app.dom.editorSync(); // re-highlight with server keywords
+  };
   // A prominent, dismissible banner for schema/auth failures — the schema-panel
   // text alone is easy to miss on first deploy. Driven by app.state.schemaError.
   function updateBanner() {
@@ -313,6 +348,7 @@ export function createApp(env = {}) {
     } catch {
       tableObj.columns = [];
     }
+    app.rebuildCompletions(); // newly-loaded columns become completion candidates (#26)
     renderSchema(app);
   }
 
@@ -742,4 +778,5 @@ export function renderApp(app, helpers) {
   app.updateSaveBtn();
   app.loadVersion();
   app.loadSchema();
+  app.loadReference();
 }
diff --git a/src/ui/dom.js b/src/ui/dom.js
index 5d53d66..a02e0e3 100644
--- a/src/ui/dom.js
+++ b/src/ui/dom.js
@@ -36,3 +36,12 @@ export function h(tag, props, ...children) {
 export function s(tag, props, ...children) {
   return apply(document.createElementNS(SVG_NS, tag), props, children);
 }
+
+// The page's CSS `zoom` factor as seen by `el`: getBoundingClientRect() is in
+// post-zoom px while layout (offsetWidth) is pre-zoom CSS px, so their ratio is
+// the zoom. The single source of truth for bridging `html{zoom}` when mapping
+// between client coords and CSS px (editor popovers, results column-resize).
+// Falls back to 1 when the element isn't laid out (offsetWidth 0 → NaN).
+export function zoomScale(el) {
+  return (el.getBoundingClientRect().width / el.offsetWidth) || 1;
+}
diff --git a/src/ui/editor-complete.js b/src/ui/editor-complete.js
new file mode 100644
index 0000000..598e82b
--- /dev/null
+++ b/src/ui/editor-complete.js
@@ -0,0 +1,163 @@
+// Autocomplete dropdown (#26). Reads the in-memory completion candidates built
+// once per connection (#25) and ranks them client-side — never a query on the
+// keystroke path. The editor wires this in: it calls refresh() on every text
+// change, delegates nav keys via handleKeydown(), and supplies the caret anchor
+// + an undoable replaceRange for accepting a candidate.
+//
+// host = {
+//   textarea,
+//   getCompletions(),                 // () => candidate list (or [])
+//   replaceRange(from, to, text),     // undoable edit that fires 'input'
+//   caretAnchor(),                    // () => {x, y, lineHeight} in screen px
+//   appendPopover(el),                // mount the dropdown
+//   suppressed(),                     // () => true to stay hidden (e.g. find open)
+//   fetchDoc(name),                   // () => Promise<string> — lazy, cached function doc
+//   getKeywordDocs(),                 // () => { KEYWORD: doc } for the footer
+// }
+
+import { h } from './dom.js';
+import { completionContext, rankCompletions } from '../core/completions.js';
+
+// Debounce the footer's function-description fetch so holding ↓ through a long
+// list doesn't fire a query per row — only the row you settle on is fetched
+// (then cached). Keyword docs are static and render with no delay.
+const FOOTER_DOC_DELAY = 150;
+
+// Kind → glyph + color for the row chip (presentation; the data is in core).
+const KIND_META = {
+  keyword: { glyph: 'K', color: '#C586C0' },
+  fn: { glyph: 'ƒ', color: '#DCDCAA' },
+  agg: { glyph: 'Σ', color: '#E0B341' },
+  cast: { glyph: '⇄', color: '#4FC1FF' },
+  table: { glyph: '▦', color: 'var(--accent)' },
+  column: { glyph: '▪', color: '#92E1D8' },
+  db: { glyph: '◈', color: '#A0A0A8' },
+};
+
+export function createComplete(host) {
+  const ta = host.textarea;
+  const state = { open: false, items: [], active: 0, ctx: null };
+  let pop = null;          // { el, list, footer } — built lazily
+  let accepting = false;   // guards the input fired by our own accept edit
+  let footerTimer = null;  // debounce for the lazy function-doc fetch
+  let footerSeq = 0;       // ignore a doc fetch that resolves after the active row moved
+
+  const hide = () => {
+    if (!state.open) return;
+    state.open = false;
+    clearTimeout(footerTimer);
+    if (pop) { pop.el.remove(); pop = null; }
+  };
+
+  // Render the footer's description line (or hide the footer when there's none).
+  const setFooter = (doc) => {
+    pop.footer.replaceChildren();
+    if (doc) {
+      pop.footer.appendChild(h('div', { class: 'ac-doc' }, doc));
+      pop.footer.style.display = '';
+    } else {
+      pop.footer.style.display = 'none';
+    }
+  };
+
+  // Re-evaluate completion at the caret and show/hide the dropdown.
+  const refresh = () => {
+    if (accepting || host.suppressed() || ta.selectionStart !== ta.selectionEnd) { hide(); return; }
+    const ctx = completionContext(ta.value, ta.selectionStart);
+    if (!ctx.qualified && ctx.word.length < 1) { hide(); return; } // need ≥1 char or a dot
+    const items = rankCompletions(host.getCompletions(), ctx);
+    if (!items.length) { hide(); return; }
+    state.open = true;
+    state.items = items;
+    state.active = 0;
+    state.ctx = ctx;
+    render();
+  };
+
+  const accept = (item) => {
+    accepting = true; // the resulting 'input' must not re-trigger the dropdown
+    host.replaceRange(state.ctx.from, state.ctx.to, item.insert);
+    accepting = false;
+    hide();
+  };
+
+  const move = (delta) => {
+    state.active = (state.active + delta + state.items.length) % state.items.length;
+    render();
+  };
+
+  const CARET_MOVERS = new Set(['ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown']);
+  const handleKeydown = (e) => {
+    if (!state.open) return false;
+    if (e.key === 'ArrowDown') { e.preventDefault(); move(1); return true; }
+    if (e.key === 'ArrowUp') { e.preventDefault(); move(-1); return true; }
+    if (e.key === 'Enter' || e.key === 'Tab') {
+      // A modified Enter/Tab is a run/format/blur chord, not "accept" — dismiss
+      // and let it bubble (otherwise ⌘↵ would splice a token *and* run).
+      if (e.metaKey || e.ctrlKey || e.altKey) { hide(); return false; }
+      e.preventDefault(); accept(state.items[state.active]); return true;
+    }
+    if (e.key === 'Escape') { e.preventDefault(); hide(); return true; }
+    // A caret-moving key makes the tracked word range stale (refresh only runs
+    // on input) — dismiss and let the caret move, so a later accept can't
+    // overwrite text at the old position.
+    if (CARET_MOVERS.has(e.key)) { hide(); return false; }
+    return false;
+  };
+
+  function render() {
+    if (!pop) {
+      const list = h('div', { class: 'ac-list' });
+      const footer = h('div', { class: 'ac-footer' });
+      pop = { el: h('div', { class: 'ac-dropdown' }, list, footer), list, footer };
+      host.appendPopover(pop.el);
+    }
+    const anchor = host.caretAnchor();
+    pop.el.style.left = Math.round(anchor.x) + 'px';
+    pop.el.style.top = Math.round(anchor.y + anchor.lineHeight) + 'px';
+
+    // replaceChildren resets scrollTop to 0; track the active row so we can pull
+    // it back into view below (otherwise it stays hidden below the fold).
+    pop.list.replaceChildren();
+    let activeRow = null;
+    state.items.forEach((it, i) => {
+      const meta = KIND_META[it.kind] || KIND_META.fn;
+      const row = h('div', {
+        class: 'ac-row' + (i === state.active ? ' on' : ''),
+        // mousedown (not click) so we beat the textarea's blur-driven hide.
+        onmousedown: (ev) => { ev.preventDefault(); accept(it); },
+      },
+        h('span', { class: 'ac-chip', style: { color: meta.color } }, meta.glyph),
+        h('span', { class: 'ac-label' }, it.label),
+        h('span', { class: 'ac-detail' }, it.detail || ''));
+      if (i === state.active) activeRow = row;
+      pop.list.appendChild(row);
+    });
+    if (activeRow) activeRow.scrollIntoView({ block: 'nearest' });
+
+    // Footer = the active entry's DESCRIPTION (the params already show in the row's
+    // detail column, so we don't repeat them). Keyword docs are static; function
+    // docs are fetched lazily + cached, debounced so navigating doesn't spam queries.
+    const cur = state.items[state.active];
+    clearTimeout(footerTimer);
+    if (cur.kind === 'keyword') {
+      setFooter(host.getKeywordDocs()[cur.label.toUpperCase()] || '');
+    } else if (cur.kind === 'fn' || cur.kind === 'agg' || cur.kind === 'cast') {
+      setFooter(''); // hide until the lazily-fetched description arrives
+      const seq = ++footerSeq;
+      footerTimer = setTimeout(() => {
+        Promise.resolve(host.fetchDoc(cur.label)).then((doc) => {
+          if (doc && seq === footerSeq && pop) setFooter(doc);
+        });
+      }, FOOTER_DOC_DELAY);
+    } else {
+      setFooter(''); // tables/columns/db: the detail column already shows what we know
+    }
+  }
+
+  // Dismiss when focus leaves (deferred so a row mousedown can land) or on scroll.
+  ta.addEventListener('blur', () => setTimeout(hide, 120));
+  ta.addEventListener('scroll', hide);
+
+  return { isOpen: () => state.open, refresh, hide, handleKeydown };
+}
diff --git a/src/ui/editor-intel.js b/src/ui/editor-intel.js
new file mode 100644
index 0000000..3c7ed12
--- /dev/null
+++ b/src/ui/editor-intel.js
@@ -0,0 +1,133 @@
+// Editor intelligence (#27): signature help + hover docs, both driven off the
+// in-memory reference data loaded once per connection (#25) — never a query on
+// the keystroke path. Signature help follows the caret inside a function call;
+// hover docs come from the textarea's mousemove (the only layer with pointer
+// events — .sql-pre / the overlay are pointer-events:none).
+//
+// host = {
+//   textarea,
+//   maskedValue(),          // () => the text with string/comment chars masked (#2)
+//   getFunctions(),         // () => { name: {sig, ret, kind} }
+//   getKeywordDocs(),       // () => { KEYWORD: doc }
+//   fetchDoc(name),         // () => Promise<string> — lazy, cached hover doc for a function
+//   caretAnchor(),          // () => {x, y, lineHeight} in screen px (shared with #26)
+//   offsetAt(cx, cy),       // map mouse client coords → text offset (or null)
+//   clientToLocal(cx, cy),  // map mouse client coords → the popover's local CSS px (zoom)
+//   appendPopover(el),
+//   suppressed(),           // () => true to stay hidden (find / autocomplete open)
+// }
+
+const HOVER_DWELL_MS = 350;
+
+import { h } from './dom.js';
+import { signatureContext, wordAt } from '../core/completions.js';
+
+export function createIntel(host) {
+  const ta = host.textarea;
+  let sigEl = null;          // signature popover
+  let hoverEl = null;        // hover card
+  let hoverTimer = null;
+
+  const hideSig = () => { if (sigEl) { sigEl.remove(); sigEl = null; } };
+  const hideHover = () => { if (hoverEl) { hoverEl.remove(); hoverEl = null; } };
+  const hide = () => { hideSig(); hideHover(); };
+
+  // Functions are keyed by the server's canonical name (usually lowercase: count,
+  // substring; a few uppercase: CAST). SQL is case-insensitive for function calls,
+  // so resolve the typed word against exact/lower/upper — matching autocomplete,
+  // which lower-cases both sides (#27). Returns { name: canonical, meta } or null.
+  const lookupFn = (word) => {
+    const fns = host.getFunctions();
+    if (fns[word]) return { name: word, meta: fns[word] };
+    const lo = word.toLowerCase();
+    if (fns[lo]) return { name: lo, meta: fns[lo] };
+    const up = word.toUpperCase();
+    if (fns[up]) return { name: up, meta: fns[up] };
+    return null;
+  };
+
+  // ── signature help (caret-driven) ──────────────────────────────────────────
+  const refreshSignature = () => {
+    if (host.suppressed() || ta.selectionStart !== ta.selectionEnd) { hideSig(); return; }
+    // Scan the string/comment-masked text so a comma inside a literal isn't
+    // counted as an argument separator (#2 review). Function names are code, so
+    // ctx.name is intact in the mask.
+    const ctx = signatureContext(host.maskedValue(), ta.selectionStart);
+    const found = ctx && lookupFn(ctx.name);
+    if (!found) { hideSig(); return; }
+    const meta = found.meta;
+    const sig = meta.sig; // always "name(…)" — the loader guarantees a () fallback
+    // Strip the optional-param brackets ClickHouse syntax uses (`name(a, b[, c])`)
+    // before splitting on commas, so the parts align with signatureContext's
+    // depth-0 comma count and the active-arg highlight lands right (#2 review).
+    const inner = sig.slice(sig.indexOf('(') + 1, sig.lastIndexOf(')')).replace(/[[\]]/g, '');
+    const args = inner.split(',');
+    const parts = [h('span', { class: 'sig-name' }, ctx.name), '('];
+    args.forEach((a, i) => {
+      parts.push(h('span', { class: i === ctx.argIdx ? 'sig-arg on' : 'sig-arg' }, a.trim()));
+      if (i < args.length - 1) parts.push(', ');
+    });
+    parts.push(')');
+    if (meta.ret) parts.push(h('span', { class: 'sig-ret' }, ' → ' + meta.ret));
+    if (!sigEl) { sigEl = h('div', { class: 'sig-help' }); host.appendPopover(sigEl); }
+    sigEl.replaceChildren(...parts);
+    const anchor = host.caretAnchor();
+    sigEl.style.left = Math.round(anchor.x) + 'px';
+    sigEl.style.top = Math.round(Math.max(4, anchor.y - anchor.lineHeight - 6)) + 'px'; // above the caret
+  };
+
+  // ── hover docs (mouse-driven, dwell; doc text fetched lazily + cached) ──────
+  let hoverToken = 0; // bumped each dwell so a late doc fetch for a stale word is ignored
+  const onMouseMove = (e) => {
+    clearTimeout(hoverTimer);
+    if (host.suppressed()) { hideHover(); return; }
+    const cx = e.clientX;
+    const cy = e.clientY;
+    hoverTimer = setTimeout(() => {
+      const pos = host.offsetAt(cx, cy);
+      // Resolve the hovered word from the string/comment-masked text (literal
+      // chars are NUL), so hovering a word inside a string or comment shows no
+      // phantom doc card — consistent with signature help (#1 review).
+      const w = pos == null ? null : wordAt(host.maskedValue(), pos);
+      if (!w) { hideHover(); return; }
+      const token = ++hoverToken;
+      const found = lookupFn(w.word);
+      const kw = host.getKeywordDocs()[w.word.toUpperCase()];
+      if (found) {
+        // Show the signature immediately; the description is fetched on demand by
+        // the canonical name (a separate query, cached per entity) and filled in
+        // when it arrives — unless the pointer has since moved to another token.
+        const meta = found.meta;
+        renderHover({ sig: meta.sig, ret: meta.ret, doc: '', x: cx, y: cy });
+        Promise.resolve(host.fetchDoc(found.name)).then((doc) => {
+          if (doc && token === hoverToken && hoverEl) renderHover({ sig: meta.sig, ret: meta.ret, doc, x: cx, y: cy });
+        });
+      } else if (kw) {
+        renderHover({ sig: w.word.toUpperCase(), doc: kw, x: cx, y: cy });
+      } else {
+        hideHover();
+      }
+    }, HOVER_DWELL_MS);
+  };
+  const onMouseLeave = () => { clearTimeout(hoverTimer); hideHover(); };
+
+  function renderHover({ sig, ret, doc, x, y }) {
+    if (!hoverEl) { hoverEl = h('div', { class: 'hover-card' }); host.appendPopover(hoverEl); }
+    hoverEl.replaceChildren(...[
+      h('div', { class: 'hover-sig' }, sig, ret ? h('span', { class: 'hover-ret' }, ' → ' + ret) : null),
+      doc ? h('div', { class: 'hover-doc' }, doc) : null,
+    ].filter(Boolean));
+    const loc = host.clientToLocal(x, y);
+    hoverEl.style.left = Math.round(loc.x) + 'px';
+    hoverEl.style.top = Math.round(loc.y + 16) + 'px';
+  }
+
+  // Esc dismisses the signature popover (only when it's showing, so a running
+  // query's Esc-to-cancel still works otherwise).
+  const handleKeydown = (e) => {
+    if (e.key === 'Escape' && sigEl) { e.preventDefault(); hideSig(); return true; }
+    return false;
+  };
+
+  return { refreshSignature, onMouseMove, onMouseLeave, handleKeydown, hide };
+}
diff --git a/src/ui/editor-search.js b/src/ui/editor-search.js
new file mode 100644
index 0000000..33de944
--- /dev/null
+++ b/src/ui/editor-search.js
@@ -0,0 +1,181 @@
+// In-editor find/replace panel (#23). A floating panel over the editor, driven
+// by the pure matcher in core/editor-search.js. Match highlights are drawn by
+// the editor's transparent mark overlay — this module only owns the panel UI,
+// the search state, and the Cmd/Ctrl+F trigger; it hands its marks to the
+// editor via `host.repaintMarks()` and edits text via `host.replaceRange`.
+//
+// host = {
+//   area,                         // .sql-area element to mount the panel into
+//   textarea,                     // the editor <textarea>
+//   padY, lineHeightPx,           // editor metrics for centering a match
+//   replaceRange(start, end, txt),// undoable edit that fires 'input'
+//   syncScroll(),                 // re-sync overlay/pre/gutter after we scroll
+//   repaintMarks(),               // ask the editor to repaint the mark overlay
+// }
+
+import { h } from './dom.js';
+import { Icon } from './icons.js';
+import { findMatches, validRegex } from '../core/editor-search.js';
+import { caretLineCol } from '../core/editor-geometry.js';
+
+export function createSearch(host) {
+  const ta = host.textarea;
+  const state = {
+    open: false, query: '', replace: '', showReplace: false,
+    opts: { caseSensitive: false, wholeWord: false, regex: false },
+    matches: [], active: 0,
+  };
+  let panel = null; // built lazily on first open; cleared on close
+
+  // Re-run the matcher against the current text and clamp the active index, then
+  // refresh the panel (so editing the editor updates the count). The editor
+  // calls this on every text change; the overlay repaint is the caller's job.
+  const recompute = () => {
+    state.matches = state.open && state.query
+      ? findMatches(ta.value, state.query, state.opts)
+      : [];
+    if (state.active >= state.matches.length) {
+      state.active = state.matches.length ? state.matches.length - 1 : 0;
+    }
+    updatePanel();
+  };
+
+  // The marks the editor overlays: every match 'match', the active one 'active'.
+  const marks = () => (state.open
+    ? state.matches.map((m, i) => ({ start: m.start, end: m.end, cls: i === state.active ? 'active' : 'match' }))
+    : []);
+
+  const refresh = () => { recompute(); host.repaintMarks(); };
+  // A new query / option set invalidates the current position — start at the
+  // first match so the active highlight + count don't point at a stale index.
+  const refreshFromStart = () => { state.active = 0; refresh(); };
+
+  const scrollToActive = () => {
+    const m = state.matches[state.active]; // goto/doReplace guarantee a match first
+    const { line } = caretLineCol(ta.value, m.start);
+    const top = host.padY + line * host.lineHeightPx; // pixel top within the scrolled content
+    if (top < ta.scrollTop || top + host.lineHeightPx > ta.scrollTop + ta.clientHeight) {
+      ta.scrollTop = Math.max(0, top - ta.clientHeight / 2);
+      host.syncScroll();
+    }
+  };
+
+  const goto = (idx) => {
+    if (!state.matches.length) return;
+    state.active = (idx + state.matches.length) % state.matches.length;
+    scrollToActive();
+    host.repaintMarks();
+    updatePanel();
+  };
+
+  const doReplace = () => {
+    const m = state.matches[state.active];
+    if (!m) return;
+    host.replaceRange(m.start, m.end, state.replace); // fires input → editor recomputes
+    if (state.matches.length) scrollToActive(); // bring the now-active match into view
+    panel.input.focus();
+  };
+  const doReplaceAll = () => {
+    if (!state.matches.length) return;
+    let out = '';
+    let last = 0;
+    for (const m of state.matches) { out += ta.value.slice(last, m.start) + state.replace; last = m.end; }
+    out += ta.value.slice(last);
+    host.replaceRange(0, ta.value.length, out);
+    panel.input.focus();
+  };
+
+  function updatePanel() {
+    if (!panel) return;
+    const bad = !validRegex(state.query, state.opts.regex);
+    panel.input.classList.toggle('bad', bad);
+    panel.counter.classList.toggle('bad', bad);
+    panel.counter.textContent = bad ? 'bad re'
+      : state.matches.length ? (state.active + 1) + '/' + state.matches.length : '0/0';
+    for (const k of Object.keys(panel.toggles)) panel.toggles[k].classList.toggle('on', state.opts[k]);
+    panel.disc.classList.toggle('open', state.showReplace);
+    const shown = panel.rows.contains(panel.replaceRow);
+    if (state.showReplace && !shown) panel.rows.appendChild(panel.replaceRow);
+    else if (!state.showReplace && shown) panel.replaceRow.remove();
+  }
+
+  function buildPanel() {
+    const input = h('input', {
+      class: 'srch-field', placeholder: 'Find', spellcheck: 'false',
+      oninput: (e) => { state.query = e.target.value; refreshFromStart(); },
+      onkeydown: (e) => {
+        if (e.key === 'Enter') { e.preventDefault(); goto(state.active + (e.shiftKey ? -1 : 1)); }
+        else if (e.key === 'Escape') { e.preventDefault(); close(); }
+      },
+    });
+    const counter = h('span', { class: 'srch-count' });
+    const navBtn = (label, title, onclick) => h('button', { class: 'srch-nav', title, onclick }, label);
+    const togBtn = (key, label, title) => h('button', {
+      class: 'srch-tog', title,
+      onclick: () => { state.opts[key] = !state.opts[key]; refreshFromStart(); },
+    }, label);
+    const toggles = {
+      caseSensitive: togBtn('caseSensitive', 'Aa', 'Match case'),
+      wholeWord: togBtn('wholeWord', 'W', 'Whole word'),
+      regex: togBtn('regex', '.*', 'Regular expression'),
+    };
+    const findRow = h('div', { class: 'srch-row' },
+      input, counter,
+      navBtn('↑', 'Previous (⇧⏎)', () => goto(state.active - 1)),
+      navBtn('↓', 'Next (⏎)', () => goto(state.active + 1)),
+      h('div', { class: 'srch-togs' }, toggles.caseSensitive, toggles.wholeWord, toggles.regex),
+      h('button', { class: 'srch-nav', title: 'Close (Esc)', onclick: close }, Icon.close()));
+
+    const replaceInput = h('input', {
+      class: 'srch-field', placeholder: 'Replace', spellcheck: 'false',
+      oninput: (e) => { state.replace = e.target.value; },
+      onkeydown: (e) => {
+        if (e.key === 'Enter') { e.preventDefault(); doReplace(); }
+        else if (e.key === 'Escape') { e.preventDefault(); close(); }
+      },
+    });
+    const replaceRow = h('div', { class: 'srch-row' },
+      replaceInput,
+      h('button', { class: 'srch-btn', title: 'Replace (⏎)', onclick: doReplace }, 'Replace'),
+      h('button', { class: 'srch-btn primary', title: 'Replace all', onclick: doReplaceAll }, 'All'));
+
+    const disc = h('button', {
+      class: 'srch-disc', title: 'Toggle replace',
+      onclick: () => { state.showReplace = !state.showReplace; updatePanel(); },
+    }, Icon.chev());
+    const rows = h('div', { class: 'srch-rows' }, findRow);
+    const el = h('div', { class: 'sql-search' }, disc, rows);
+    panel = { el, input, counter, toggles, disc, rows, replaceRow };
+    host.area.appendChild(el);
+  }
+
+  const open = () => {
+    if (!state.open) {
+      state.open = true;
+      if (!panel) buildPanel();
+      else host.area.appendChild(panel.el);
+      refresh();
+    }
+    panel.input.focus();
+    panel.input.select();
+  };
+
+  function close() {
+    if (!state.open) return;
+    state.open = false;
+    if (panel) panel.el.remove();
+    host.repaintMarks(); // clear the highlights
+    ta.focus();
+  }
+
+  // Cmd/Ctrl+F on the textarea — registered here so the browser's native find
+  // can't intercept it before a global handler (resolved design decision).
+  ta.addEventListener('keydown', (e) => {
+    if ((e.metaKey || e.ctrlKey) && (e.key === 'f' || e.key === 'F')) {
+      e.preventDefault();
+      open();
+    }
+  });
+
+  return { isOpen: () => state.open, marks, recompute, open, close };
+}
diff --git a/src/ui/editor.js b/src/ui/editor.js
index 5f5aa38..47f49ce 100644
--- a/src/ui/editor.js
+++ b/src/ui/editor.js
@@ -1,19 +1,46 @@
 // The SQL editor: a textarea overlaid on a syntax-highlighted <pre>, with a
 // line-number gutter. Highlighting reuses the pure tokenizer in core.
 
-import { h } from './dom.js';
-import { tokenize } from '../core/sql-highlight.js';
+import { h, zoomScale } from './dom.js';
+import { tokenize, maskFromTokens } from '../core/sql-highlight.js';
+import { buildMarkSegments } from '../core/editor-marks.js';
+import { matchBracketAt, bracketEdit } from '../core/editor-brackets.js';
+import { caretXY, offsetFromXY } from '../core/editor-geometry.js';
+import { createSearch } from './editor-search.js';
+import { createComplete } from './editor-complete.js';
+import { createIntel } from './editor-intel.js';
 import { activeTab } from '../state.js';
 
+// Editor layout metrics (kept in lockstep with .sql-editor in styles.css):
+// integer line-height so the textarea and overlay <pre>s lay out identically.
+const LINE_HEIGHT_PX = 22;
+const PAD_Y = 12;
+const PAD_X = 14;
+// Width of one monospace glyph at the editor's 13px font — a constant (the font
+// is fixed) used only to anchor the autocomplete popover near the caret (#26).
+const CHAR_WIDTH_PX = 7.8;
+
 // dataTransfer MIME used when dragging a schema identifier onto the editor.
 // A dedicated type (not text/plain) scopes the drop handler to schema-tree
 // drags, leaving native text drag-within-the-textarea untouched.
 export const IDENT_MIME = 'application/x-asb-identifier';
 
-/** Paint tokenized SQL into `preEl` (whitespace as text, tokens as spans). */
-export function renderHighlightInto(preEl, sql) {
+/**
+ * Paint tokenized SQL into `preEl` (whitespace as text, tokens as spans).
+ * `opts` (optional) forwards dynamic keyword/function sets to the tokenizer so
+ * highlighting tracks the connected server's `system.keywords`/`functions`
+ * (#25); omitted → the tokenizer's built-in sets.
+ */
+export function renderHighlightInto(preEl, sql, opts) {
+  renderTokensInto(preEl, tokenize(sql, opts));
+}
+
+// Paint an already-tokenized stream into `preEl`. Split out so the editor's
+// keystroke path can tokenize ONCE and feed both the highlighter and the
+// literal mask, instead of tokenizing the buffer twice per keystroke (#5 review).
+export function renderTokensInto(preEl, tokens) {
   preEl.replaceChildren();
-  for (const [t, v] of tokenize(sql)) {
+  for (const [t, v] of tokens) {
     if (t === 'ws') {
       preEl.appendChild(document.createTextNode(v));
     } else {
@@ -37,42 +64,245 @@ function gutterLines(sql) {
  */
 export function mountEditor(app, container) {
   const gutter = h('div', { class: 'sql-gutter' });
+  // Mark overlay: a transparent <pre> below the token <pre>, carrying only the
+  // search/bracket highlight backgrounds (#23/#24) — the token render path is
+  // never touched. DOM order = paint order: overlay, then tokens, then textarea.
+  const markPre = document.createElement('pre');
+  markPre.className = 'sql-mark-overlay';
+  markPre.setAttribute('aria-hidden', 'true');
   const pre = document.createElement('pre');
   pre.className = 'sql-pre';
   const ta = document.createElement('textarea');
   ta.className = 'sql-textarea';
   ta.spellcheck = false;
-  const area = h('div', { class: 'sql-area' }, pre, ta);
+  const area = h('div', { class: 'sql-area' }, markPre, pre, ta);
   container.replaceChildren(h('div', { class: 'sql-editor' }, gutter, area));
 
-  const paint = (sql) => {
-    renderHighlightInto(pre, sql);
+  // Tokenize the buffer ONCE per (text, reference-data) change and reuse the
+  // token list for BOTH the syntax highlighter and the literal mask, instead of
+  // tokenizing twice per keystroke (#5 review). Re-tokenize when app.refData
+  // changes too (server keyword/func sets arrive after connect), else the
+  // re-highlight would use stale tokens. String/comment classification is
+  // opt-independent, so the highlighter's token list is valid for the mask.
+  let tokVal = null;
+  let tokRef = null;
+  let tokList = [];
+  let maskOut = '';
+  const recompute = () => {
+    const ref = app.refData;
+    if (ta.value === tokVal && ref === tokRef) return;
+    tokVal = ta.value;
+    tokRef = ref;
+    tokList = tokenize(ta.value, ref ? { keywords: ref.keywordSet, funcs: ref.funcSet } : undefined);
+    maskOut = maskFromTokens(tokList);
+  };
+  const paintTokens = (sql) => {
+    recompute(); // sql === ta.value at every call site (sync sets ta.value first)
+    renderTokensInto(pre, tokList);
     gutter.replaceChildren(...gutterLines(sql));
   };
+  // The text with string/comment/backtick-ident chars masked to NUL. Bracket
+  // matching, signature help, and the auto-close decision run on this so
+  // literals' brackets/quotes/commas don't pair or count (#2 review).
+  const masked = () => { recompute(); return maskOut; };
+  // All highlight sources, aggregated for the overlay: search matches (#23) or,
+  // when search is closed and the caret is collapsed, the bracket pair adjacent
+  // to the caret (#24).
+  const computeMarks = () => {
+    const marks = search.marks();
+    if (!search.isOpen() && ta.selectionStart === ta.selectionEnd) {
+      const bp = matchBracketAt(masked(), ta.selectionStart);
+      if (bp) {
+        marks.push({ start: bp[0], end: bp[0] + 1, cls: 'bracket' });
+        marks.push({ start: bp[1], end: bp[1] + 1, cls: 'bracket' });
+      }
+    }
+    return marks;
+  };
+  const paintMarks = () => {
+    const marks = computeMarks();
+    // Common case (no search, caret not on a bracket): keep the keystroke path
+    // cheap — clear the overlay once and skip rebuilding a full-document node.
+    if (!marks.length) {
+      if (markPre.firstChild) markPre.replaceChildren();
+      return;
+    }
+    markPre.replaceChildren();
+    for (const seg of buildMarkSegments(ta.value, marks)) {
+      if (seg.cls) {
+        const sp = document.createElement('span');
+        sp.className = 'mark-' + seg.cls;
+        sp.textContent = seg.text;
+        markPre.appendChild(sp);
+      } else {
+        markPre.appendChild(document.createTextNode(seg.text));
+      }
+    }
+    markPre.appendChild(document.createTextNode('\n'));
+  };
+  const syncScroll = () => {
+    pre.scrollTop = ta.scrollTop;
+    pre.scrollLeft = ta.scrollLeft;
+    markPre.scrollTop = ta.scrollTop;
+    markPre.scrollLeft = ta.scrollLeft;
+    gutter.scrollTop = ta.scrollTop;
+  };
+  // Set the textarea selection to a range and replace it (undoable, fires input).
+  const replaceRange = (start, end, text) => {
+    ta.focus();
+    ta.selectionStart = start;
+    ta.selectionEnd = end;
+    applyEdit(ta, text);
+  };
+  // Apply a structural bracket edit (#24) while PRESERVING the native undo stack.
+  // A direct `ta.value = …` assignment wipes ⌘Z, so instead express the edit as a
+  // single execCommand over the changed range (insertText, or delete for an
+  // empty-pair Backspace) — the same undo-friendly path applyEdit uses — derived
+  // by diffing the old/new value. Type-over (no value change) is a pure caret
+  // move. Then place the structural caret and re-sync the caret-driven UI
+  // (execCommand fired 'input' at the post-edit caret; a type-over fires none).
+  const applyBracketEdit = (edit) => {
+    const before = ta.value;
+    if (before !== edit.value) {
+      const { from, to, ins } = bracketDiff(before, edit.value);
+      ta.focus();
+      ta.selectionStart = from;
+      ta.selectionEnd = to;
+      let ok = false;
+      try {
+        ok = ins ? ta.ownerDocument.execCommand('insertText', false, ins)
+          : ta.ownerDocument.execCommand('delete', false);
+      } catch { ok = false; }
+      if (!ok) { ta.value = edit.value; ta.dispatchEvent(new Event('input')); }
+    }
+    ta.selectionStart = edit.selStart;
+    ta.selectionEnd = edit.selEnd;
+    paintMarks();
+    intel.refreshSignature();
+  };
+
+  const search = createSearch({
+    area, textarea: ta, padY: PAD_Y, lineHeightPx: LINE_HEIGHT_PX,
+    replaceRange, syncScroll, repaintMarks: paintMarks,
+  });
+
+  // Screen-space caret position for the autocomplete popover.
+  const caretAnchor = () => {
+    const { x, y } = caretXY(ta.value, ta.selectionStart, {
+      charWidth: CHAR_WIDTH_PX, lhPx: LINE_HEIGHT_PX, padX: PAD_X, padY: PAD_Y,
+      scrollTop: ta.scrollTop, scrollLeft: ta.scrollLeft,
+    });
+    const rect = ta.getBoundingClientRect();
+    // getBoundingClientRect is in post-zoom px while x/y are CSS px; bridge the
+    // html{zoom} gap via the shared zoomScale helper (also used by results.js).
+    const scale = zoomScale(ta);
+    return { x: rect.left / scale + x, y: rect.top / scale + y, lineHeight: LINE_HEIGHT_PX };
+  };
+  const complete = createComplete({
+    textarea: ta,
+    getCompletions: () => app.completions || [],
+    replaceRange,
+    caretAnchor,
+    appendPopover: (el) => area.appendChild(el),
+    suppressed: () => search.isOpen(),
+    fetchDoc: (name) => app.entityDoc(name), // lazy + cached function description (#27)
+    getKeywordDocs: () => (app.refData ? app.refData.keywordDocs : {}),
+  });
+
+  // Map a mouse position to a text offset for hover docs (#27). Mirrors
+  // caretAnchor's html{zoom} handling, inverted.
+  const offsetAt = (clientX, clientY) => {
+    const rect = ta.getBoundingClientRect();
+    const scale = zoomScale(ta);
+    const relX = (clientX - rect.left) / scale - PAD_X + ta.scrollLeft;
+    const relY = (clientY - rect.top) / scale - PAD_Y + ta.scrollTop;
+    return offsetFromXY(ta.value, relX, relY, { charWidth: CHAR_WIDTH_PX, lhPx: LINE_HEIGHT_PX });
+  };
+  // Client (post-zoom) coords → the popover's local CSS px. The popovers are
+  // fixed children of the html{zoom} tree, so their left/top are scaled on
+  // paint; divide by the same scale offsetAt/caretAnchor use so the hover card
+  // lands on the cursor (#27).
+  const clientToLocal = (clientX, clientY) => {
+    const scale = zoomScale(ta);
+    return { x: clientX / scale, y: clientY / scale };
+  };
+  const intel = createIntel({
+    textarea: ta,
+    maskedValue: masked, // string/comment-masked text for signatureContext (#2 review)
+    getFunctions: () => (app.refData ? app.refData.functions : {}),
+    getKeywordDocs: () => (app.refData ? app.refData.keywordDocs : {}),
+    fetchDoc: (name) => app.entityDoc(name),
+    caretAnchor,
+    offsetAt,
+    clientToLocal,
+    appendPopover: (el) => area.appendChild(el),
+    suppressed: () => search.isOpen() || complete.isOpen(),
+  });
+
   const sync = () => {
+    // A tab switch reassigns ta.value; dismiss the autocomplete dropdown and the
+    // signature popover so their tracked offsets can't act on the new tab's text.
+    complete.hide();
+    intel.hide();
     const tab = activeTab(app.state);
     ta.value = tab.sql;
-    paint(tab.sql);
+    paintTokens(tab.sql);
+    search.recompute();
+    paintMarks();
   };
 
   ta.addEventListener('input', () => {
     const tab = activeTab(app.state);
     tab.sql = ta.value;
     tab.dirty = true;
-    paint(ta.value);
+    paintTokens(ta.value);
+    search.recompute(); // text changed → refresh match positions, then overlay
+    paintMarks();
+    complete.refresh(); // re-evaluate autocomplete at the new caret (#26)
+    intel.refreshSignature(); // and signature help (#27)
     app.actions.rerenderTabs();
     app.actions.updateSaveBtn();
   });
-  ta.addEventListener('scroll', () => {
-    pre.scrollTop = ta.scrollTop;
-    pre.scrollLeft = ta.scrollLeft;
-    gutter.scrollTop = ta.scrollTop;
-  });
+  ta.addEventListener('scroll', () => { syncScroll(); intel.hide(); });
+  ta.addEventListener('mousemove', (e) => intel.onMouseMove(e));
+  ta.addEventListener('mouseleave', () => intel.onMouseLeave());
   ta.addEventListener('keydown', (e) => {
-    if (e.key !== 'Tab') return;
-    e.preventDefault();
-    applyEdit(ta, '  ');
+    // Autocomplete nav (↑/↓/Enter/Tab/Esc while the dropdown is open) wins first.
+    if (complete.handleKeydown(e)) return;
+    if (intel.handleKeydown(e)) return; // Esc dismisses signature help
+    // (handled below: command-chord / IME guard, then brackets, then Tab)
+    // A command chord (⌘/Ctrl) or an IME composition isn't bracket/Tab input —
+    // leave it for the global shortcuts (run/format) or the IME. AltGr (Ctrl+Alt
+    // on some EU layouts) *does* type real brackets, so don't treat it as a chord.
+    const altGraph = typeof e.getModifierState === 'function' && e.getModifierState('AltGraph');
+    if (e.isComposing || e.metaKey || (e.ctrlKey && !altGraph)) return;
+    // Bracket auto-close / wrap / type-over / pair-delete (#24) takes priority;
+    // a non-bracket key returns null and falls through to the Tab handler.
+    // Suppress auto-pairing inside a string/comment (the char before the caret is
+    // masked to NUL) so e.g. typing `(` in 'O(' doesn't insert a stray `)`.
+    const s = ta.selectionStart;
+    const inLiteral = s > 0 && masked()[s - 1] === '\0';
+    const edit = bracketEdit(ta.value, s, ta.selectionEnd, e.key, inLiteral);
+    if (edit) {
+      e.preventDefault();
+      applyBracketEdit(edit);
+      return;
+    }
+    if (e.key === 'Tab') {
+      e.preventDefault();
+      applyEdit(ta, '  ');
+    }
   });
+  // Caret moves don't fire 'input' — repaint the overlay so the bracket-pair
+  // highlight (#24) tracks the caret. A mouse click also moves the caret, which
+  // makes any open completion's tracked word range stale, so dismiss it there.
+  const onCaretMove = () => { paintMarks(); intel.refreshSignature(); };
+  // keyup only handles caret-only moves; a printable key already repainted via
+  // 'input', and selection changes fire 'select' — so don't repaint twice here.
+  const CARET_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown']);
+  ta.addEventListener('keyup', (e) => { if (CARET_KEYS.has(e.key)) onCaretMove(); });
+  ta.addEventListener('click', () => { complete.hide(); paintMarks(); intel.refreshSignature(); });
+  ta.addEventListener('select', onCaretMove);
   // Accept schema identifiers dragged from the tree; insert at the cursor.
   ta.addEventListener('dragover', (e) => e.preventDefault());
   ta.addEventListener('drop', (e) => {
@@ -84,7 +314,11 @@ export function mountEditor(app, container) {
 
   app.dom.editorTextarea = ta;
   app.dom.editorPre = pre;
+  app.dom.editorMarkPre = markPre;
   app.dom.editorGutter = gutter;
+  app.dom.editorSearch = search;
+  app.dom.editorComplete = complete;
+  app.dom.editorIntel = intel;
   app.dom.editorSync = sync;
   sync();
 }
@@ -107,6 +341,17 @@ function applyEdit(ta, text) {
   ta.dispatchEvent(new Event('input'));
 }
 
+// Minimal prefix/suffix diff: the replaced range in `a` and the inserted text
+// that turns it into `b`. Lets applyBracketEdit apply a bracket edit as one
+// execCommand over a range (undo-preserving) instead of a `.value =` assignment.
+function bracketDiff(a, b) {
+  let p = 0;
+  while (p < a.length && p < b.length && a[p] === b[p]) p++;
+  let s = 0;
+  while (s < a.length - p && s < b.length - p && a[a.length - 1 - s] === b[b.length - 1 - s]) s++;
+  return { from: p, to: a.length - s, ins: b.slice(p, b.length - s) };
+}
+
 /** Insert `text` at the textarea cursor (undoable). */
 export function insertAtCursor(app, text) {
   const ta = app.dom.editorTextarea;
diff --git a/src/ui/results.js b/src/ui/results.js
index 32b1e12..ddc12b9 100644
--- a/src/ui/results.js
+++ b/src/ui/results.js
@@ -2,7 +2,7 @@
 // view for TSV/JSON output) plus the renderers. Heavy logic (sorting, axis
 // selection) lives in core/ and is reused here.
 
-import { h } from './dom.js';
+import { h, zoomScale } from './dom.js';
 import { Icon } from './icons.js';
 import { formatRows, formatBytes, isNumericType } from '../core/format.js';
 import { looksLikeHtml, prettyValue } from '../core/cell.js';
@@ -54,7 +54,7 @@ function startColumnResize(r, th, ev) {
   }
   applyFixedWidths(table, r);
   const win = th.ownerDocument.defaultView;
-  const scale = th.getBoundingClientRect().width / th.offsetWidth;
+  const scale = zoomScale(th);
   const startX = ev.clientX;
   const startW = r.colWidths[colIndex];
   const onMove = (m) => {
diff --git a/tests/helpers/fake-app.js b/tests/helpers/fake-app.js
index d2b02d3..1b02789 100644
--- a/tests/helpers/fake-app.js
+++ b/tests/helpers/fake-app.js
@@ -38,6 +38,7 @@ export function makeApp(over = {}) {
     signOut: vi.fn(),
     loadVersion: vi.fn(),
     loadSchema: vi.fn(),
+    entityDoc: vi.fn(async () => ''), // lazy hover-doc loader (#27); overridden per test
     loadIdps: async () => ({ idps: [], basicLogin: true }),
     dom: {
       qtabsInner: document.createElement('div'),
diff --git a/tests/unit/app.test.js b/tests/unit/app.test.js
index bc100dd..b17b99c 100644
--- a/tests/unit/app.test.js
+++ b/tests/unit/app.test.js
@@ -189,6 +189,74 @@ describe('loadVersion / loadSchema', () => {
   });
 });
 
+describe('loadReference / rebuildCompletions (#25)', () => {
+  it('loads server keywords + functions into refData and the completion list', async () => {
+    const e = env({ fetch: makeFetch([
+      [(u, sql) => /system\.keywords/.test(sql), resp({ json: { data: [{ keyword: 'PREWHERE' }] } })],
+      [(u, sql) => /system\.functions/.test(sql), resp({ json: { data: [{ name: 'toDate', is_aggregate: 0 }] } })],
+    ]) });
+    const app = createApp(e);
+    app.renderApp();
+    await app.loadReference();
+    expect(app.refData.keywordSet.has('PREWHERE')).toBe(true); // drives the tokenizer too
+    expect(app.refData.funcSet.has('toDate')).toBe(true);
+    expect(app.completions.some((c) => c.label === 'PREWHERE')).toBe(true);
+  });
+  it('starts with the built-in fallback before any load', () => {
+    const app = createApp(env());
+    expect(app.refData.keywordSet.has('SELECT')).toBe(true);
+    expect(app.completions.length).toBeGreaterThan(0);
+  });
+  it('rebuildCompletions folds in already-loaded schema columns', () => {
+    const app = createApp(env());
+    app.state.schema = [{ db: 'd', tables: [{ name: 't', columns: [{ name: 'c', type: 'UInt8' }] }] }];
+    app.rebuildCompletions();
+    expect(app.completions.some((c) => c.kind === 'column' && c.label === 'c' && c.parent === 't')).toBe(true);
+  });
+  it('loadReference tolerates being called before the editor mounts', async () => {
+    const app = createApp(env()); // no renderApp → no app.dom.editorSync
+    await expect(app.loadReference()).resolves.toBeUndefined();
+    expect(app.refData).toBeTruthy();
+  });
+  it('loadColumns folds the newly-loaded columns into the completion list (#26)', async () => {
+    const e = env({ fetch: makeFetch([
+      [(u, sql) => /system\.columns/.test(sql), resp({ json: { data: [{ name: 'id', type: 'UInt64', comment: '' }] } })],
+    ]) });
+    const app = createApp(e); // no renderApp → loadSchema can't clobber our schema mid-test
+    app.state.schema = [{ db: 'd', expanded: true, tables: [{ name: 't', columns: null }] }];
+    await app.actions.loadColumns('d', 't', app.state.schema[0].tables[0]);
+    expect(app.completions.some((c) => c.kind === 'column' && c.label === 'id' && c.parent === 't')).toBe(true);
+  });
+  it('entityDoc fetches a hover description on demand and caches it (#27)', async () => {
+    const fetch = makeFetch([
+      [(u, sql) => /system\.functions/.test(sql) && /description/.test(sql),
+        resp({ json: { data: [{ description: '\nCounts rows.' }] } })],
+    ]);
+    const app = createApp(env({ fetch }));
+    const first = await app.entityDoc('count');
+    const second = await app.entityDoc('count'); // served from cache, no second query
+    expect(first).toBe('Counts rows.'); // first non-empty line (CH leading blank stripped)
+    expect(second).toBe('Counts rows.');
+    const docQueries = fetch.mock.calls.filter(([, init]) => init && /system\.functions/.test(init.body) && /description/.test(init.body));
+    expect(docQueries.length).toBe(1);
+  });
+  it('does not cache a FAILED doc fetch — it retries on the next hover (#8 review)', async () => {
+    let calls = 0;
+    const fetch = makeFetch([
+      [(u, sql) => /system\.functions/.test(sql) && /description/.test(sql), () => {
+        calls += 1;
+        return calls === 1
+          ? resp({ ok: false, status: 500, text: 'boom' })            // transient failure
+          : resp({ json: { data: [{ description: 'Now works.' }] } }); // later succeeds
+      }],
+    ]);
+    const app = createApp(env({ fetch }));
+    expect(await app.entityDoc('count')).toBeNull(); // failed → null, not cached
+    expect(await app.entityDoc('count')).toBe('Now works.'); // retried, not served from a cached error
+    expect(calls).toBe(2);
+  });
+});
+
 describe('query run', () => {
   function appForRun(routes, over) {
     const e = env({ fetch: makeFetch(routes), ...over });
diff --git a/tests/unit/ch-client.test.js b/tests/unit/ch-client.test.js
index f6e2738..d5eabea 100644
--- a/tests/unit/ch-client.test.js
+++ b/tests/unit/ch-client.test.js
@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
 import {
-  chUrl, authedFetch, queryJson, loadServerVersion, loadSchema, loadColumns, runQuery, killQuery,
+  chUrl, authedFetch, queryJson, loadServerVersion, loadSchema, loadColumns, loadReferenceData, loadEntityDoc, runQuery, killQuery,
 } from '../../src/net/ch-client.js';
 import { sqlString } from '../../src/core/format.js';
 
@@ -186,6 +186,67 @@ describe('loadColumns', () => {
   });
 });
 
+describe('loadReferenceData', () => {
+  it('loads keywords + function metadata from system tables', async () => {
+    const ctx = ctxWith(async (url, o) => (
+      o.body.includes('system.keywords')
+        ? jsonResp({ data: [{ keyword: 'SELECT' }, { keyword: 'PREWHERE' }] })
+        : jsonResp({ data: [{ name: 'count', is_aggregate: 1 }, { name: 'toDate', is_aggregate: 0 }] })
+    ));
+    const ref = await loadReferenceData(ctx);
+    expect(ref.keywords).toEqual(['SELECT', 'PREWHERE']);
+    expect(ref.functions.count).toEqual({ kind: 'agg', sig: 'count()', ret: '', desc: '' });
+    expect(ref.functions.toDate.kind).toBe('fn'); // is_aggregate 0 → plain function
+  });
+  it('returns null pieces when a system table is missing/denied (best-effort)', async () => {
+    const ctx = ctxWith(async () => textResp('Code: 60. DB::Exception: Unknown table', false, 500));
+    expect(await loadReferenceData(ctx)).toEqual({ keywords: null, functions: null });
+  });
+  it('tolerates an empty data shape', async () => {
+    const ctx = ctxWith(async () => jsonResp({}));
+    expect(await loadReferenceData(ctx)).toEqual({ keywords: [], functions: {} });
+  });
+  it('uses the syntax column for signatures; descriptions are NOT bulk-loaded (lazy, #27)', async () => {
+    const ctx = ctxWith(async (url, o) => (
+      o.body.includes('system.keywords')
+        ? jsonResp({ data: [{ keyword: 'SELECT' }] })
+        : jsonResp({ data: [{ name: 'toDate', is_aggregate: 0, syntax: 'toDate(x)' }] })
+    ));
+    const ref = await loadReferenceData(ctx);
+    // desc stays '' here — hover docs are fetched on demand via loadEntityDoc.
+    expect(ref.functions.toDate).toEqual({ kind: 'fn', sig: 'toDate(x)', ret: '', desc: '' });
+  });
+  it('falls back to the minimal function query when the syntax column is absent (older CH)', async () => {
+    const ctx = ctxWith(async (url, o) => {
+      if (o.body.includes('system.keywords')) return jsonResp({ data: [{ keyword: 'SELECT' }] });
+      if (o.body.includes('syntax')) return textResp('Code: 47. DB::Exception: Unknown identifier syntax', false, 500);
+      return jsonResp({ data: [{ name: 'now', is_aggregate: 0 }] }); // minimal columns only
+    });
+    const ref = await loadReferenceData(ctx);
+    expect(ref.functions.now).toEqual({ kind: 'fn', sig: 'now()', ret: '', desc: '' });
+  });
+});
+
+describe('loadEntityDoc (#27 — lazy hover docs)', () => {
+  it('returns the first NON-empty line (CH descriptions begin with a blank line)', async () => {
+    const ctx = ctxWith(async () => jsonResp({ data: [{ description: '\nCalculates a hash.\nMore detail here.' }] }));
+    expect(await loadEntityDoc(ctx, 'BLAKE3', sqlString)).toBe('Calculates a hash.');
+  });
+  it('escapes the name through sqlString and queries system.functions', async () => {
+    const fetchImpl = vi.fn(async () => jsonResp({ data: [{ description: 'doc' }] }));
+    const ctx = ctxWith(fetchImpl);
+    await loadEntityDoc(ctx, "o'brien", sqlString);
+    expect(fetchImpl.mock.calls[0][1].body).toContain("WHERE name = 'o''brien'");
+  });
+  it('returns "" when the query succeeds but there is no description (unknown name / blank)', async () => {
+    expect(await loadEntityDoc(ctxWith(async () => jsonResp({ data: [] })), 'nope', sqlString)).toBe('');
+    expect(await loadEntityDoc(ctxWith(async () => jsonResp({ data: [{ description: '\n   \n' }] })), 'blank', sqlString)).toBe('');
+  });
+  it('returns null when the query FAILS, so the caller can retry rather than cache it (#8 review)', async () => {
+    expect(await loadEntityDoc(ctxWith(async () => textResp('boom', false, 500)), 'x', sqlString)).toBeNull();
+  });
+});
+
 describe('runQuery', () => {
   it('streams lines and reports an error result on !ok', async () => {
     const ctx = ctxWith(async () => textResp('{"exception":"boom"}', false, 500));
diff --git a/tests/unit/completions.test.js b/tests/unit/completions.test.js
new file mode 100644
index 0000000..97d83a5
--- /dev/null
+++ b/tests/unit/completions.test.js
@@ -0,0 +1,153 @@
+import { describe, it, expect } from 'vitest';
+import {
+  assembleReferenceData, buildCompletions, completionContext, rankCompletions,
+  wordAt, signatureContext,
+} from '../../src/core/completions.js';
+import { SQL_KEYWORDS, SQL_FUNCS } from '../../src/core/sql-highlight.js';
+
+describe('assembleReferenceData', () => {
+  it('falls back to the built-in sets when given null', () => {
+    const ref = assembleReferenceData(null);
+    expect(ref.keywords).toEqual([...SQL_KEYWORDS]);
+    expect(ref.keywordSet.has('SELECT')).toBe(true);
+    expect(ref.funcSet.has('count')).toBe(true);
+    // built-in functions get a synthesized meta entry
+    expect(ref.functions.count).toEqual({ kind: 'fn', sig: 'count()', ret: '', desc: '' });
+  });
+  it('uses loaded keywords + functions when present', () => {
+    const ref = assembleReferenceData({
+      keywords: ['select', 'prewhere'],
+      functions: { toDate: { kind: 'cast', sig: 'toDate(x)', ret: 'Date', desc: 'd' } },
+    });
+    expect(ref.keywords).toEqual(['select', 'prewhere']);
+    expect(ref.keywordSet.has('PREWHERE')).toBe(true);   // uppercased for the tokenizer
+    expect(ref.funcSet.has('toDate')).toBe(true);
+    expect(ref.funcSet.has('count')).toBe(false);        // not built-in fallback
+  });
+  it('falls back per-field when keywords or functions are empty', () => {
+    const ref = assembleReferenceData({ keywords: [], functions: {} });
+    expect(ref.keywords).toEqual([...SQL_KEYWORDS]);
+    expect(Object.keys(ref.functions).length).toBe(SQL_FUNCS.size);
+  });
+  it('exposes a built-in keyword-docs map for hover (#27)', () => {
+    expect(assembleReferenceData(null).keywordDocs.PREWHERE).toContain('before reading');
+  });
+});
+
+describe('wordAt', () => {
+  it('returns the identifier surrounding a position', () => {
+    expect(wordAt('select count(x)', 9)).toEqual({ word: 'count', from: 7, to: 12 });
+  });
+  it('returns null when the position is not inside a word', () => {
+    expect(wordAt('a (b)', 2)).toBeNull(); // on the space
+  });
+});
+
+describe('signatureContext', () => {
+  it('finds the enclosing function and the active argument index', () => {
+    expect(signatureContext('sum(a', 5)).toEqual({ name: 'sum', argIdx: 0 });
+    expect(signatureContext('sum(a, b', 8)).toEqual({ name: 'sum', argIdx: 1 });
+  });
+  it('counts only commas at the call depth (skips nested calls)', () => {
+    expect(signatureContext('if(x, foo(a,b), ', 16)).toEqual({ name: 'if', argIdx: 2 });
+  });
+  it('returns null outside a call, for an anonymous (, and across ; or newline', () => {
+    expect(signatureContext('select 1', 8)).toBeNull();
+    expect(signatureContext('(a', 2)).toBeNull();         // no name before '('
+    expect(signatureContext('sum(a); x', 9)).toBeNull();  // ';' at depth 0 stops the scan
+    expect(signatureContext('a\nb', 3)).toBeNull();        // newline at depth 0 stops the scan
+  });
+});
+
+describe('buildCompletions', () => {
+  const ref = {
+    keywords: ['SELECT'],
+    functions: {
+      count: { kind: 'agg', sig: 'count([x])', ret: 'UInt64', desc: 'counts' },
+      toDate: { kind: 'cast', sig: 'toDate(x)', ret: 'Date', desc: 'casts' },
+      lower: { kind: 'fn', sig: '', ret: '', desc: '' }, // missing sig → fallback name()
+      plus: { kind: 'fn', sig: 'a + b', ret: '', desc: '' }, // operator syntax, no '(' → kept as-is
+    },
+  };
+  const schema = [
+    { db: 'airline', tables: [
+      { name: 'ontime', columns: [{ name: 'Year', type: 'UInt16' }] },
+      { name: 'pending', columns: null },   // not loaded → no column items, table still listed
+    ] },
+    { db: 'empty' },                          // db.tables undefined → just the db item
+  ];
+
+  it('maps keywords, function kinds, and schema (loaded columns only)', () => {
+    const items = buildCompletions(ref, schema);
+    expect(items.find((i) => i.label === 'SELECT')).toMatchObject({ kind: 'keyword', insert: 'SELECT' });
+    // detail shows only the params (the label already shows the name) — #26
+    expect(items.find((i) => i.label === 'count')).toMatchObject({ kind: 'agg', insert: 'count(', detail: '([x])', ret: 'UInt64' });
+    expect(items.find((i) => i.label === 'toDate')).toMatchObject({ kind: 'cast', detail: '(x)' });
+    expect(items.find((i) => i.label === 'lower')).toMatchObject({ kind: 'fn', detail: '()' }); // sig fallback → just ()
+    expect(items.find((i) => i.label === 'plus')).toMatchObject({ kind: 'fn', detail: 'a + b' }); // no '(' → sig kept as-is
+    expect(items.find((i) => i.label === 'airline')).toMatchObject({ kind: 'db' });
+    expect(items.find((i) => i.label === 'ontime')).toMatchObject({ kind: 'table', parent: 'airline' });
+    expect(items.find((i) => i.label === 'Year')).toMatchObject({ kind: 'column', parent: 'ontime', detail: 'UInt16' });
+    expect(items.some((i) => i.label === 'pending')).toBe(true);          // table listed
+    expect(items.some((i) => i.kind === 'column' && i.parent === 'pending')).toBe(false); // no columns
+    expect(items.find((i) => i.label === 'empty')).toMatchObject({ kind: 'db' });
+  });
+  it('handles a null schema', () => {
+    const items = buildCompletions(ref, null);
+    expect(items.every((i) => i.kind === 'keyword' || ['agg', 'cast', 'fn'].includes(i.kind))).toBe(true);
+  });
+});
+
+describe('completionContext', () => {
+  it('reads the word at the caret', () => {
+    expect(completionContext('SELECT cou', 10)).toEqual({ word: 'cou', from: 7, to: 10, qualified: false, parent: null });
+  });
+  it('detects a qualified word after a dot and its parent', () => {
+    expect(completionContext('ontime.Ye', 9)).toEqual({ word: 'Ye', from: 7, to: 9, qualified: true, parent: 'ontime' });
+  });
+  it('qualified with empty word right after the dot', () => {
+    expect(completionContext('ontime.', 7)).toEqual({ word: '', from: 7, to: 7, qualified: true, parent: 'ontime' });
+  });
+  it('word at the very start', () => {
+    expect(completionContext('SEL', 3)).toMatchObject({ word: 'SEL', from: 0, qualified: false });
+  });
+  it('a dot NOT preceded by an identifier is not qualified — falls back to normal completion (#4 review)', () => {
+    expect(completionContext('.col', 4)).toMatchObject({ word: 'col', qualified: false, parent: null });
+    expect(completionContext('count().c', 9)).toMatchObject({ word: 'c', qualified: false, parent: null });
+  });
+});
+
+describe('rankCompletions', () => {
+  const items = [
+    { label: 'SELECT', kind: 'keyword' },
+    { label: 'sum', kind: 'agg' },
+    { label: 'substring', kind: 'fn' },
+    { label: 'ontime', kind: 'table', parent: 'airline' },
+    { label: 'Year', kind: 'column', parent: 'ontime' },
+    { label: 'Month', kind: 'column', parent: 'ontime' },
+    { label: 'Origin', kind: 'column', parent: 'other' },
+  ];
+
+  it('qualified → only the parent table columns, optionally filtered', () => {
+    const all = rankCompletions(items, { word: '', qualified: true, parent: 'ontime' });
+    expect(all.map((i) => i.label)).toEqual(['Year', 'Month']);
+    const filtered = rankCompletions(items, { word: 'mon', qualified: true, parent: 'ontime' });
+    expect(filtered.map((i) => i.label)).toEqual(['Month']);
+  });
+  it('empty word (unqualified) → keywords + tables only', () => {
+    const r = rankCompletions(items, { word: '', qualified: false, parent: null });
+    expect(r.map((i) => i.label).sort()).toEqual(['SELECT', 'ontime']);
+  });
+  it('scores prefix above substring and boosts schema over keywords', () => {
+    const r = rankCompletions(items, { word: 's', qualified: false, parent: null });
+    // 'SELECT','sum','substring' all start with s; none of the schema rows match 's'
+    expect(r[0].label).toBe('sum'); // shorter prefix match ranks first by length tiebreak
+    expect(r.map((i) => i.label)).toContain('substring');
+  });
+  it('skips non-matches and ranks a substring hit below prefixes', () => {
+    const r = rankCompletions(items, { word: 'o', qualified: false, parent: null });
+    // 'ontime','Origin','Month'(substring 'o'),'substring'? no. prefix: ontime/Origin
+    expect(r.map((i) => i.label)).toContain('ontime');
+    expect(r).not.toContainEqual(expect.objectContaining({ label: 'SELECT' }));
+  });
+});
diff --git a/tests/unit/editor-brackets.test.js b/tests/unit/editor-brackets.test.js
new file mode 100644
index 0000000..0f178a3
--- /dev/null
+++ b/tests/unit/editor-brackets.test.js
@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import { matchBracketAt, bracketEdit } from '../../src/core/editor-brackets.js';
+
+describe('matchBracketAt', () => {
+  it('matches forward from an opener at the caret', () => {
+    expect(matchBracketAt('(a)', 0)).toEqual([0, 2]);
+  });
+  it('matches backward from a closer just before the caret', () => {
+    expect(matchBracketAt('(a)', 3)).toEqual([0, 2]);
+  });
+  it('handles nesting', () => {
+    expect(matchBracketAt('(())', 0)).toEqual([0, 3]);
+  });
+  it('matches braces too (matching spans {} even though auto-close does not)', () => {
+    expect(matchBracketAt('{x}', 0)).toEqual([0, 2]);
+  });
+  it('returns null for an unbalanced opener (and caret 0 has nothing behind it)', () => {
+    expect(matchBracketAt('((', 0)).toBeNull();
+  });
+  it('returns null for an unbalanced closer behind the caret', () => {
+    expect(matchBracketAt('a)', 2)).toBeNull();
+  });
+  it('returns null when the caret is not adjacent to a bracket', () => {
+    expect(matchBracketAt('abc', 1)).toBeNull();
+  });
+});
+
+describe('bracketEdit', () => {
+  it('auto-closes an opener with the caret inside', () => {
+    expect(bracketEdit('', 0, 0, '(')).toEqual({ value: '()', selStart: 1, selEnd: 1 });
+  });
+  it('wraps a selection with an opener', () => {
+    expect(bracketEdit('abc', 0, 3, '[')).toEqual({ value: '[abc]', selStart: 1, selEnd: 4 });
+  });
+  it('auto-closes a quote', () => {
+    expect(bracketEdit('', 0, 0, "'")).toEqual({ value: "''", selStart: 1, selEnd: 1 });
+  });
+  it('wraps a selection with a quote', () => {
+    expect(bracketEdit('abc', 0, 3, '"')).toEqual({ value: '"abc"', selStart: 1, selEnd: 4 });
+  });
+  it('types over an existing quote instead of inserting', () => {
+    expect(bracketEdit("''", 1, 1, "'")).toEqual({ value: "''", selStart: 2, selEnd: 2 });
+  });
+  it('types over an existing closer', () => {
+    expect(bracketEdit('()', 1, 1, ')')).toEqual({ value: '()', selStart: 2, selEnd: 2 });
+  });
+  it('returns null for a closer with no matching char ahead', () => {
+    expect(bracketEdit('ab', 1, 1, ')')).toBeNull();
+  });
+  it('Backspace removes both halves of an empty bracket pair', () => {
+    expect(bracketEdit('()', 1, 1, 'Backspace')).toEqual({ value: '', selStart: 0, selEnd: 0 });
+  });
+  it('Backspace removes both halves of an empty quote pair', () => {
+    expect(bracketEdit("x''y", 2, 2, 'Backspace')).toEqual({ value: 'xy', selStart: 1, selEnd: 1 });
+  });
+  it('Backspace not inside a pair → null', () => {
+    expect(bracketEdit('ab', 1, 1, 'Backspace')).toBeNull();
+    expect(bracketEdit('()', 0, 0, 'Backspace')).toBeNull(); // s = 0 guard
+    expect(bracketEdit('()', 0, 2, 'Backspace')).toBeNull(); // selection, not collapsed
+  });
+  it('{ is excluded from auto-close (Phase 1b), and ordinary keys are no-ops', () => {
+    expect(bracketEdit('', 0, 0, '{')).toBeNull();
+    expect(bracketEdit('ab', 1, 1, 'x')).toBeNull();
+    expect(bracketEdit('ab', 1, 1, 'Tab')).toBeNull();
+  });
+  describe('inLiteral suppresses auto-pairing but not type-over (#2 review)', () => {
+    it('does not auto-close an opener inside a string/comment', () => {
+      expect(bracketEdit("'O'", 2, 2, '(', true)).toBeNull(); // type '(' literally, no stray ')'
+    });
+    it('does not wrap a selection with an opener inside a literal', () => {
+      expect(bracketEdit("'abc'", 1, 4, '(', true)).toBeNull();
+    });
+    it('does not auto-pair a quote inside a literal', () => {
+      expect(bracketEdit("'ab", 3, 3, "'", true)).toBeNull();
+    });
+    it('still types over an existing quote inside a literal (closes it)', () => {
+      expect(bracketEdit("'ab'", 3, 3, "'", true)).toEqual({ value: "'ab'", selStart: 4, selEnd: 4 });
+    });
+    it('still types over a closer, and still pair-deletes, inside a literal', () => {
+      expect(bracketEdit('()', 1, 1, ')', true)).toEqual({ value: '()', selStart: 2, selEnd: 2 });
+      expect(bracketEdit('()', 1, 1, 'Backspace', true)).toEqual({ value: '', selStart: 0, selEnd: 0 });
+    });
+  });
+});
diff --git a/tests/unit/editor-geometry.test.js b/tests/unit/editor-geometry.test.js
new file mode 100644
index 0000000..752bdb2
--- /dev/null
+++ b/tests/unit/editor-geometry.test.js
@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+import { caretLineCol, caretXY, offsetFromXY } from '../../src/core/editor-geometry.js';
+
+describe('caretLineCol', () => {
+  it('computes line/col on the first line', () => {
+    expect(caretLineCol('select a', 3)).toEqual({ line: 0, col: 3 });
+  });
+  it('computes line/col after newlines', () => {
+    expect(caretLineCol('ab\ncd\nef', 7)).toEqual({ line: 2, col: 1 });
+  });
+});
+
+describe('caretXY', () => {
+  const m = { charWidth: 8, lhPx: 22, padX: 14, padY: 12, scrollTop: 0, scrollLeft: 0 };
+  it('offsets by padding + column/line', () => {
+    expect(caretXY('abcd', 2, m)).toEqual({ x: 14 + 2 * 8, y: 12 });
+  });
+  it('subtracts scroll when present', () => {
+    expect(caretXY('a\nb', 3, { ...m, scrollTop: 5, scrollLeft: 3 }))
+      .toEqual({ x: 14 + 8 - 3, y: 12 + 22 - 5 });
+  });
+  it('treats missing scroll as 0', () => {
+    expect(caretXY('ab', 1, { charWidth: 8, lhPx: 22, padX: 14, padY: 12 }))
+      .toEqual({ x: 22, y: 12 });
+  });
+});
+
+describe('offsetFromXY', () => {
+  const m = { charWidth: 8, lhPx: 22 };
+  it('maps a point to a text offset', () => {
+    expect(offsetFromXY('abc\ndef', 16, 0, m)).toBe(2);  // line 0, col 2
+    expect(offsetFromXY('abc\ndef', 8, 22, m)).toBe(5);  // line 1, col 1 → 'abc\n' (4) + 1
+  });
+  it('returns null well past a short line (no phantom hover), clamps a small overshoot (#10)', () => {
+    expect(offsetFromXY('ab\ncdef', 800, 0, m)).toBeNull();   // far past 'ab' → no token here
+    expect(offsetFromXY('ab\ncdef', 8 * 2 + 2, 0, m)).toBe(2); // within ½ char of the end → clamps to end
+    expect(offsetFromXY('ab\ncdef', -50, 0, m)).toBe(0);       // negative → col 0
+  });
+  it('returns null above or below the text', () => {
+    expect(offsetFromXY('abc', 0, -5, m)).toBeNull();
+    expect(offsetFromXY('abc', 0, 999, m)).toBeNull();
+  });
+});
diff --git a/tests/unit/editor-marks.test.js b/tests/unit/editor-marks.test.js
new file mode 100644
index 0000000..c4ebf7e
--- /dev/null
+++ b/tests/unit/editor-marks.test.js
@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { buildMarkSegments } from '../../src/core/editor-marks.js';
+
+// Contract: marks are sorted by start and non-overlapping (search matches come
+// back ordered + disjoint; the bracket pair is two sorted width-1 ranges and is
+// never mixed with search marks).
+describe('buildMarkSegments', () => {
+  it('returns a single plain segment when there are no marks', () => {
+    expect(buildMarkSegments('hello', [])).toEqual([{ text: 'hello', cls: null }]);
+  });
+  it('handles empty text with no marks', () => {
+    expect(buildMarkSegments('', [])).toEqual([{ text: '', cls: null }]);
+  });
+  it('splits text around a single mark, with a trailing plain segment', () => {
+    expect(buildMarkSegments('hello', [{ start: 1, end: 3, cls: 'match' }])).toEqual([
+      { text: 'h', cls: null }, { text: 'el', cls: 'match' }, { text: 'lo', cls: null },
+    ]);
+  });
+  it('emits no empty trailing segment for a mark that reaches the end', () => {
+    expect(buildMarkSegments('ab', [{ start: 0, end: 2, cls: 'match' }])).toEqual([{ text: 'ab', cls: 'match' }]);
+  });
+  it('keeps the gap between separated marks unmarked', () => {
+    expect(buildMarkSegments('a b c', [
+      { start: 0, end: 1, cls: 'match' }, { start: 4, end: 5, cls: 'match' },
+    ])).toEqual([
+      { text: 'a', cls: 'match' }, { text: ' b ', cls: null }, { text: 'c', cls: 'match' },
+    ]);
+  });
+  it('renders an adjacent (touching) pair with no gap segment, e.g. ()', () => {
+    expect(buildMarkSegments('()', [
+      { start: 0, end: 1, cls: 'bracket' }, { start: 1, end: 2, cls: 'bracket' },
+    ])).toEqual([{ text: '(', cls: 'bracket' }, { text: ')', cls: 'bracket' }]);
+  });
+});
diff --git a/tests/unit/editor-search.test.js b/tests/unit/editor-search.test.js
new file mode 100644
index 0000000..608b1d9
--- /dev/null
+++ b/tests/unit/editor-search.test.js
@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { findMatches, validRegex } from '../../src/core/editor-search.js';
+
+describe('findMatches', () => {
+  it('returns [] for an empty query', () => {
+    expect(findMatches('abc', '')).toEqual([]);
+  });
+  it('finds plain matches, case-insensitive by default', () => {
+    expect(findMatches('aAbA', 'a')).toEqual([
+      { start: 0, end: 1 }, { start: 1, end: 2 }, { start: 3, end: 4 },
+    ]);
+  });
+  it('honors caseSensitive', () => {
+    expect(findMatches('aA', 'a', { caseSensitive: true })).toEqual([{ start: 0, end: 1 }]);
+  });
+  it('escapes regex metacharacters in plain mode', () => {
+    expect(findMatches('a.b a.b', 'a.b')).toHaveLength(2);
+    expect(findMatches('axb', 'a.b')).toEqual([]); // '.' is a literal dot
+  });
+  it('wholeWord fences with boundaries', () => {
+    expect(findMatches('cat category', 'cat', { wholeWord: true })).toEqual([{ start: 0, end: 3 }]);
+  });
+  it('wholeWord fences in regex mode too (#4)', () => {
+    // \d+ as a whole word: matches the standalone 12 and 34, not the 12 inside a12
+    expect(findMatches('12 a12 34', '\\d+', { regex: true, wholeWord: true }))
+      .toEqual([{ start: 0, end: 2 }, { start: 7, end: 9 }]);
+  });
+  it('regex mode compiles the pattern', () => {
+    expect(findMatches('a1b2', '\\d', { regex: true })).toEqual([{ start: 1, end: 2 }, { start: 3, end: 4 }]);
+  });
+  it('regex mode honors caseSensitive', () => {
+    expect(findMatches('aA', 'a', { regex: true, caseSensitive: true })).toEqual([{ start: 0, end: 1 }]);
+  });
+  it('an invalid regex yields []', () => {
+    expect(findMatches('abc', '(', { regex: true })).toEqual([]);
+  });
+  it('drops zero-width matches (nothing to highlight or replace) without looping (#6)', () => {
+    expect(findMatches('ab', 'x*', { regex: true })).toEqual([]); // every match is zero-width
+    expect(findMatches('a\nb', '$', { regex: true })).toEqual([]);
+    // real matches around a zero-width-capable pattern are still kept
+    expect(findMatches('xax', 'a*', { regex: true })).toEqual([{ start: 1, end: 2 }]);
+  });
+  it('caps the match count to guard the keystroke path', () => {
+    expect(findMatches('a'.repeat(20000), 'a').length).toBe(10000);
+  });
+});
+
+describe('validRegex', () => {
+  it('is true when not in regex mode (even for a bad pattern)', () => {
+    expect(validRegex('(', false)).toBe(true);
+  });
+  it('is true for an empty query', () => {
+    expect(validRegex('', true)).toBe(true);
+  });
+  it('is true for a valid pattern, false for an invalid one', () => {
+    expect(validRegex('a+', true)).toBe(true);
+    expect(validRegex('(', true)).toBe(false);
+  });
+});
diff --git a/tests/unit/editor.test.js b/tests/unit/editor.test.js
index 12854a4..a693d34 100644
--- a/tests/unit/editor.test.js
+++ b/tests/unit/editor.test.js
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { renderHighlightInto, mountEditor, insertAtCursor, replaceEditor, IDENT_MIME } from '../../src/ui/editor.js';
 import { makeApp } from '../helpers/fake-app.js';
 
@@ -10,6 +10,12 @@ describe('renderHighlightInto', () => {
     expect(pre.querySelector('.sql-number').textContent).toBe('1');
     expect(pre.textContent.endsWith('\n')).toBe(true);
   });
+  it('forwards dynamic keyword/func sets to the tokenizer (#25)', () => {
+    const pre = document.createElement('pre');
+    renderHighlightInto(pre, 'FOO bar', { keywords: new Set(['FOO']), funcs: new Set(['bar']) });
+    expect(pre.querySelector('.sql-keyword').textContent).toBe('FOO');
+    expect(pre.querySelector('.sql-func').textContent).toBe('bar');
+  });
 });
 
 describe('mountEditor', () => {
@@ -27,6 +33,23 @@ describe('mountEditor', () => {
     expect(app.dom.editorTextarea.value).toBe('SELECT 1');
     expect(app.dom.editorGutter.children.length).toBe(1);
   });
+  it('highlights with the connection reference sets when app.refData is present (#25)', () => {
+    const app = makeApp();
+    app.refData = { keywordSet: new Set(['FOO']), funcSet: new Set() };
+    app.activeTab().sql = 'FOO';
+    mountEditor(app, document.createElement('div'));
+    expect(app.dom.editorPre.querySelector('.sql-keyword').textContent).toBe('FOO');
+  });
+  it('re-highlights when reference data arrives after connect — same text, new sets (#5 review)', () => {
+    const app = makeApp();
+    app.activeTab().sql = 'FOO';
+    mountEditor(app, document.createElement('div'));
+    expect(app.dom.editorPre.querySelector('.sql-keyword')).toBeNull(); // FOO is a plain ident pre-connect
+    app.refData = { keywordSet: new Set(['FOO']), funcSet: new Set() };
+    app.dom.editorSync(); // what loadReference calls when server sets arrive
+    // the shared token cache must invalidate on the refData change (not just on text change)
+    expect(app.dom.editorPre.querySelector('.sql-keyword').textContent).toBe('FOO');
+  });
   it('typing updates the tab, marks dirty, repaints, and rerenders', () => {
     const { app, ta } = mount();
     ta.value = 'SELECT 2\nFROM t';
@@ -154,3 +177,696 @@ describe('replaceEditor', () => {
     expect(() => replaceEditor(app, 'x')).not.toThrow();
   });
 });
+
+describe('in-editor find/replace (#23)', () => {
+  function mounted(sql = 'select a from t') {
+    const app = makeApp();
+    app.activeTab().sql = sql;
+    const container = document.createElement('div');
+    mountEditor(app, container);
+    return { app, container, ta: app.dom.editorTextarea };
+  }
+  const panel = (c) => c.querySelector('.sql-search');
+  const findInput = (c) => c.querySelector('.sql-search .srch-field');
+  const count = (c) => c.querySelector('.srch-count').textContent;
+  const type = (input, v) => { input.value = v; input.dispatchEvent(new Event('input')); };
+  const key = (el, k, opts = {}) => el.dispatchEvent(new KeyboardEvent('keydown', { key: k, cancelable: true, ...opts }));
+
+  it('Cmd+F (and Ctrl+F / uppercase F) opens the panel', () => {
+    const { container, ta } = mounted();
+    expect(panel(container)).toBeNull();
+    key(ta, 'f', { metaKey: true });
+    expect(panel(container)).not.toBeNull();
+    const b = mounted();
+    key(b.ta, 'F', { ctrlKey: true });
+    expect(panel(b.container)).not.toBeNull();
+  });
+
+  it('typing a query highlights matches in the overlay and shows the count', () => {
+    const { app, container, ta } = mounted('a a a');
+    key(ta, 'f', { metaKey: true });
+    type(findInput(container), 'a');
+    expect(count(container)).toBe('1/3');
+    expect(app.dom.editorMarkPre.querySelector('.mark-active')).not.toBeNull();
+    expect(app.dom.editorMarkPre.querySelectorAll('.mark-match').length).toBe(2);
+  });
+
+  it('next/prev cycle the active match (Enter, Shift+Enter, and the buttons)', () => {
+    const { container, ta } = mounted('a a a');
+    key(ta, 'f', { metaKey: true });
+    const input = findInput(container);
+    type(input, 'a');
+    key(input, 'Enter');                       // → 2/3
+    expect(count(container)).toBe('2/3');
+    key(input, 'Enter', { shiftKey: true });   // → 1/3
+    expect(count(container)).toBe('1/3');
+    container.querySelector('.srch-nav[title^="Previous"]').dispatchEvent(new Event('click')); // wrap → 3/3
+    expect(count(container)).toBe('3/3');
+    container.querySelector('.srch-nav[title^="Next"]').dispatchEvent(new Event('click'));      // wrap → 1/3
+    expect(count(container)).toBe('1/3');
+  });
+
+  it('next with no matches is a no-op', () => {
+    const { container, ta } = mounted('abc');
+    key(ta, 'f', { metaKey: true });
+    expect(() => container.querySelector('.srch-nav[title^="Next"]').dispatchEvent(new Event('click'))).not.toThrow();
+    expect(count(container)).toBe('0/0');
+  });
+
+  it('case / whole-word / regex toggles re-filter and reflect state', () => {
+    const { container, ta } = mounted('a A a');
+    key(ta, 'f', { metaKey: true });
+    type(findInput(container), 'a');
+    expect(count(container)).toBe('1/3');
+    const aa = container.querySelector('.srch-tog[title="Match case"]');
+    aa.dispatchEvent(new Event('click'));
+    expect(aa.classList.contains('on')).toBe(true);
+    expect(count(container)).toBe('1/2'); // only the two lowercase a's
+
+    const ww = mounted('cat category');
+    key(ww.ta, 'f', { metaKey: true });
+    type(findInput(ww.container), 'cat');
+    expect(count(ww.container)).toBe('1/2');
+    ww.container.querySelector('.srch-tog[title="Whole word"]').dispatchEvent(new Event('click'));
+    expect(count(ww.container)).toBe('1/1');
+  });
+
+  it('regex toggle + invalid pattern shows the bad-re state', () => {
+    const { container, ta } = mounted('a1 b2');
+    key(ta, 'f', { metaKey: true });
+    container.querySelector('.srch-tog[title="Regular expression"]').dispatchEvent(new Event('click'));
+    const input = findInput(container);
+    type(input, '\\d');
+    expect(count(container)).toBe('1/2');
+    type(input, '(');                          // invalid regex
+    expect(count(container)).toBe('bad re');
+    expect(input.classList.contains('bad')).toBe(true);
+  });
+
+  it('replace swaps the active match; replace-all swaps the rest', () => {
+    const { container, ta } = mounted('a a a');
+    key(ta, 'f', { metaKey: true });
+    type(findInput(container), 'a');
+    container.querySelector('.srch-disc').dispatchEvent(new Event('click')); // reveal replace row
+    const replaceInput = container.querySelectorAll('.sql-search .srch-field')[1];
+    type(replaceInput, 'X');
+    container.querySelector('.srch-btn').dispatchEvent(new Event('click'));  // Replace active
+    expect(ta.value).toBe('X a a');
+    container.querySelector('.srch-btn.primary').dispatchEvent(new Event('click')); // Replace all
+    expect(ta.value).toBe('X X X');
+  });
+
+  it('replace via Enter in the replace field, and replace/all no-op without matches', () => {
+    const { container, ta } = mounted('a a');
+    key(ta, 'f', { metaKey: true });
+    type(findInput(container), 'a');
+    container.querySelector('.srch-disc').dispatchEvent(new Event('click'));
+    const replaceInput = container.querySelectorAll('.sql-search .srch-field')[1];
+    type(replaceInput, 'Z');
+    key(replaceInput, 'Enter');
+    expect(ta.value).toBe('Z a');
+
+    const none = mounted('abc');
+    key(none.ta, 'f', { metaKey: true });
+    none.container.querySelector('.srch-disc').dispatchEvent(new Event('click'));
+    const before = none.ta.value;
+    none.container.querySelector('.srch-btn').dispatchEvent(new Event('click'));
+    none.container.querySelector('.srch-btn.primary').dispatchEvent(new Event('click'));
+    expect(none.ta.value).toBe(before);
+  });
+
+  it('Escape and the close button close the panel and clear highlights', () => {
+    const { app, container, ta } = mounted('a a');
+    expect(app.dom.editorSearch.isOpen()).toBe(false);
+    key(ta, 'f', { metaKey: true });
+    expect(app.dom.editorSearch.isOpen()).toBe(true);
+    type(findInput(container), 'a');
+    expect(app.dom.editorMarkPre.querySelector('.mark-active')).not.toBeNull();
+    key(findInput(container), 'Escape');
+    expect(app.dom.editorSearch.isOpen()).toBe(false);
+    expect(panel(container)).toBeNull();
+    expect(app.dom.editorMarkPre.querySelector('.mark-active')).toBeNull();
+    // reopen (reuses the panel element) and close via the × button
+    key(ta, 'f', { metaKey: true });
+    expect(panel(container)).not.toBeNull();
+    key(ta, 'f', { metaKey: true }); // already open → just refocus
+    container.querySelector('.srch-nav[title^="Close"]').dispatchEvent(new Event('click'));
+    expect(panel(container)).toBeNull();
+  });
+
+  it('Escape in the replace field closes the panel', () => {
+    const { container, ta } = mounted('a');
+    key(ta, 'f', { metaKey: true });
+    container.querySelector('.srch-disc').dispatchEvent(new Event('click'));
+    key(container.querySelectorAll('.sql-search .srch-field')[1], 'Escape');
+    expect(panel(container)).toBeNull();
+  });
+
+  it('toggling the replace disclosure shows then hides the replace row', () => {
+    const { container, ta } = mounted('a');
+    key(ta, 'f', { metaKey: true });
+    const disc = container.querySelector('.srch-disc');
+    expect(container.querySelectorAll('.sql-search .srch-field').length).toBe(1);
+    disc.dispatchEvent(new Event('click'));
+    expect(container.querySelectorAll('.sql-search .srch-field').length).toBe(2);
+    expect(disc.classList.contains('open')).toBe(true);
+    disc.dispatchEvent(new Event('click'));
+    expect(container.querySelectorAll('.sql-search .srch-field').length).toBe(1);
+  });
+
+  it('editing the text recomputes matches and the overlay mirrors the value', () => {
+    const { app, container, ta } = mounted('a a');
+    key(ta, 'f', { metaKey: true });
+    type(findInput(container), 'a');
+    expect(count(container)).toBe('1/2');
+    ta.value = 'a a a a'; // user types in the editor
+    ta.dispatchEvent(new Event('input'));
+    expect(count(container)).toBe('1/4');
+    expect(app.dom.editorMarkPre.textContent).toContain('a a a a');
+  });
+
+  it('editing the query resets the active match to the first', () => {
+    const { container, ta } = mounted('a a a');
+    key(ta, 'f', { metaKey: true });
+    const input = findInput(container);
+    type(input, 'a');
+    key(input, 'Enter'); key(input, 'Enter'); // → 3/3
+    expect(count(container)).toBe('3/3');
+    type(input, 'a'); // re-typing the query re-searches from the top
+    expect(count(container)).toBe('1/3');
+  });
+});
+
+describe('bracket matching + auto-close (#24)', () => {
+  function mounted(sql = '') {
+    const app = makeApp();
+    app.activeTab().sql = sql;
+    const container = document.createElement('div');
+    mountEditor(app, container);
+    const ta = app.dom.editorTextarea;
+    ta.value = sql;
+    return { app, container, ta };
+  }
+  const press = (ta, k, opts = {}) => {
+    const e = new KeyboardEvent('keydown', { key: k, cancelable: true, ...opts });
+    ta.dispatchEvent(e);
+    return e;
+  };
+
+  it('auto-closes an opener and places the caret inside', () => {
+    const { ta } = mounted('');
+    ta.selectionStart = ta.selectionEnd = 0;
+    const e = press(ta, '(');
+    expect(e.defaultPrevented).toBe(true);
+    expect(ta.value).toBe('()');
+    expect(ta.selectionStart).toBe(1);
+  });
+  it('wraps a selection with the opener', () => {
+    const { ta } = mounted('abc');
+    ta.selectionStart = 0; ta.selectionEnd = 3;
+    press(ta, '[');
+    expect(ta.value).toBe('[abc]');
+    expect(ta.selectionStart).toBe(1);
+    expect(ta.selectionEnd).toBe(4);
+  });
+  it('auto-closes a quote, then types over the closer', () => {
+    const { ta } = mounted('');
+    ta.selectionStart = ta.selectionEnd = 0;
+    press(ta, "'");
+    expect(ta.value).toBe("''");
+    expect(ta.selectionStart).toBe(1);
+    press(ta, "'"); // step over
+    expect(ta.value).toBe("''");
+    expect(ta.selectionStart).toBe(2);
+  });
+  it('types over an existing closing bracket', () => {
+    const { ta } = mounted('()');
+    ta.selectionStart = ta.selectionEnd = 1;
+    press(ta, ')');
+    expect(ta.value).toBe('()');
+    expect(ta.selectionStart).toBe(2);
+  });
+  it('Backspace inside an empty pair deletes both halves', () => {
+    const { ta } = mounted('()');
+    ta.selectionStart = ta.selectionEnd = 1;
+    press(ta, 'Backspace');
+    expect(ta.value).toBe('');
+  });
+  it('does not auto-close a bracket typed inside a string literal (#2 review)', () => {
+    const { ta } = mounted("''");
+    ta.selectionStart = ta.selectionEnd = 1; // caret inside the string
+    const e = press(ta, '(');
+    expect(e.defaultPrevented).toBe(false); // not handled as a bracket → the '(' types literally
+    expect(ta.value).toBe("''");            // no stray ')' inserted
+  });
+  it('matches the real bracket pair, not one inside a string (#2 review)', () => {
+    const { app, ta } = mounted("'(' (a)");
+    ta.selectionStart = ta.selectionEnd = 4; // caret on the real '(' (index 4); the string's is masked
+    ta.dispatchEvent(new MouseEvent('click')); // repaint at the caret (not gated, keeps the caret)
+    expect(app.dom.editorMarkPre.querySelectorAll('.mark-bracket').length).toBe(2);
+  });
+  it('a non-bracket key falls through — Tab still inserts two spaces', () => {
+    const { ta } = mounted('ab');
+    ta.selectionStart = ta.selectionEnd = 1;
+    const e = press(ta, 'Tab');
+    expect(e.defaultPrevented).toBe(true);
+    expect(ta.value).toBe('a  b');
+  });
+  it('highlights the bracket pair adjacent to the caret on caret moves', () => {
+    const { app, ta } = mounted('(a)');
+    ta.selectionStart = ta.selectionEnd = 0; // caret before '('
+    ta.dispatchEvent(new Event('keyup'));
+    expect(app.dom.editorMarkPre.querySelectorAll('.mark-bracket').length).toBe(2);
+    ta.selectionStart = ta.selectionEnd = 1; // between '(' and a → not adjacent in match sense
+    ta.dispatchEvent(new MouseEvent('click'));
+    // caret after 'a' is not on a bracket boundary; no pair highlight
+    expect(app.dom.editorMarkPre.querySelectorAll('.mark-bracket').length).toBe(0);
+  });
+  it('suppresses bracket marks while the search panel is open', () => {
+    const { app, ta } = mounted('(a)');
+    press(ta, 'f', { metaKey: true }); // open search
+    ta.selectionStart = ta.selectionEnd = 0;
+    app.dom.editorSync(); // repaint overlay
+    expect(app.dom.editorMarkPre.querySelectorAll('.mark-bracket').length).toBe(0);
+  });
+  it('a ⌘ chord is not bracket input (lets the shortcut through)', () => {
+    const { ta } = mounted('');
+    ta.selectionStart = ta.selectionEnd = 0;
+    const e = press(ta, '[', { metaKey: true });
+    expect(e.defaultPrevented).toBe(false);
+    expect(ta.value).toBe('');
+  });
+  it('a plain Ctrl chord is not bracket input (no AltGraph)', () => {
+    const { ta } = mounted('');
+    ta.selectionStart = ta.selectionEnd = 0;
+    const e = new KeyboardEvent('keydown', { key: '[', ctrlKey: true, cancelable: true });
+    Object.defineProperty(e, 'getModifierState', { value: undefined }); // env without the API
+    ta.dispatchEvent(e);
+    expect(ta.value).toBe('');
+  });
+  it('an AltGr-typed bracket still auto-closes (real input, not a chord)', () => {
+    const { ta } = mounted('');
+    ta.selectionStart = ta.selectionEnd = 0;
+    const e = new KeyboardEvent('keydown', { key: '(', ctrlKey: true, altKey: true, cancelable: true });
+    e.getModifierState = (k) => k === 'AltGraph';
+    ta.dispatchEvent(e);
+    expect(ta.value).toBe('()');
+  });
+  it('an IME composition keydown does not auto-close', () => {
+    const { ta } = mounted('');
+    ta.selectionStart = ta.selectionEnd = 0;
+    const e = new KeyboardEvent('keydown', { key: '(', cancelable: true });
+    Object.defineProperty(e, 'isComposing', { value: true });
+    ta.dispatchEvent(e);
+    expect(ta.value).toBe('');
+    expect(e.defaultPrevented).toBe(false);
+  });
+});
+
+describe('autocomplete dropdown (#26)', () => {
+  const CANDIDATES = [
+    { label: 'SELECT', kind: 'keyword', insert: 'SELECT', detail: 'keyword' },
+    { label: 'count', kind: 'agg', insert: 'count(', detail: 'count([x])', ret: 'UInt64', doc: 'Counts rows.' },
+    { label: 'concat', kind: 'fn', insert: 'concat(', detail: 'concat(s, …)', ret: 'String' }, // sig, no doc
+    { label: 'cobalt', kind: 'mystery', insert: 'cobalt', detail: '?' }, // unknown kind → glyph fallback
+    { label: 'ontime', kind: 'table', insert: 'ontime', detail: 'table', parent: 'airline' },
+    { label: 'Year', kind: 'column', insert: 'Year', detail: 'UInt16', parent: 'ontime' },
+    { label: 'Month', kind: 'column', insert: 'Month', detail: 'UInt8', parent: 'ontime' },
+  ];
+  function mounted(sql = '', completions = CANDIDATES) {
+    const app = makeApp();
+    app.completions = completions;
+    app.activeTab().sql = sql;
+    const container = document.createElement('div');
+    mountEditor(app, container);
+    const ta = app.dom.editorTextarea;
+    ta.value = sql;
+    return { app, container, ta };
+  }
+  const dropdown = (c) => c.querySelector('.ac-dropdown');
+  const rows = (c) => [...c.querySelectorAll('.ac-row')];
+  const labels = (c) => rows(c).map((r) => r.querySelector('.ac-label').textContent);
+  const typeAt = (ta, value, pos) => {
+    ta.value = value; ta.selectionStart = ta.selectionEnd = pos;
+    ta.dispatchEvent(new Event('input'));
+  };
+  const press = (ta, k, opts = {}) => {
+    const e = new KeyboardEvent('keydown', { key: k, cancelable: true, ...opts });
+    ta.dispatchEvent(e);
+    return e;
+  };
+
+  it('shows ranked candidates after typing ≥1 word char', () => {
+    const { container, ta } = mounted();
+    typeAt(ta, 'co', 2);
+    expect(dropdown(container)).not.toBeNull();
+    expect(labels(container)).toEqual(expect.arrayContaining(['concat', 'count', 'cobalt']));
+    expect(labels(container)).not.toContain('Year'); // no 'co'
+  });
+  it('does not trigger on an empty word', () => {
+    const { container, ta } = mounted();
+    typeAt(ta, 'select ', 7); // caret after the space → empty word
+    expect(dropdown(container)).toBeNull();
+  });
+  it('does not complete over a non-empty selection', () => {
+    const { container, ta } = mounted();
+    ta.value = 'count'; ta.selectionStart = 0; ta.selectionEnd = 5;
+    ta.dispatchEvent(new Event('input'));
+    expect(dropdown(container)).toBeNull();
+  });
+  it('a qualified word (table.) lists only that table\'s columns', () => {
+    const { container, ta } = mounted();
+    typeAt(ta, 'ontime.', 7);
+    expect(labels(container).sort()).toEqual(['Month', 'Year']);
+  });
+  it('arrows move the active row (wrapping); Enter accepts and a function inserts name(', () => {
+    const { app, container, ta } = mounted();
+    expect(app.dom.editorComplete.isOpen()).toBe(false);
+    typeAt(ta, 'co', 2);
+    expect(app.dom.editorComplete.isOpen()).toBe(true);
+    expect(rows(container)[0].classList.contains('on')).toBe(true);
+    press(ta, 'ArrowUp'); // wrap to last
+    expect(rows(container)[rows(container).length - 1].classList.contains('on')).toBe(true);
+    press(ta, 'ArrowDown'); // wrap back to first
+    expect(rows(container)[0].classList.contains('on')).toBe(true);
+    const accepted = labels(container)[0];
+    press(ta, 'Enter');
+    expect(app.dom.editorComplete.isOpen()).toBe(false);
+    expect(dropdown(container)).toBeNull();
+    expect(ta.value).toContain(accepted + '('); // count/concat → name(
+  });
+  it('Tab accepts a column as-is; Escape dismisses', () => {
+    const { container, ta } = mounted();
+    typeAt(ta, 'Yea', 3);
+    press(ta, 'Escape');
+    expect(dropdown(container)).toBeNull();
+    typeAt(ta, 'Yea', 3);
+    press(ta, 'Tab');
+    expect(ta.value).toBe('Year');
+  });
+  it('a non-nav key while open falls through and leaves the dropdown up', () => {
+    const { container, ta } = mounted();
+    typeAt(ta, 'co', 2);
+    press(ta, 'x'); // not consumed by the dropdown
+    expect(dropdown(container)).not.toBeNull();
+  });
+  it('clicking (mousedown) a row accepts it', () => {
+    const { container, ta } = mounted();
+    typeAt(ta, 'ont', 3);
+    rows(container).find((r) => r.querySelector('.ac-label').textContent === 'ontime')
+      .dispatchEvent(new MouseEvent('mousedown', { cancelable: true }));
+    expect(ta.value).toBe('ontime');
+    expect(dropdown(container)).toBeNull();
+  });
+  describe('footer description (#27 — lazy + cached; not the params)', () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+    const flush = async () => { await Promise.resolve(); await Promise.resolve(); };
+    const acDoc = (c) => c.querySelector('.ac-doc');
+
+    it('shows a function description (lazy + debounced) and never repeats the params', async () => {
+      const { app, container, ta } = mounted();
+      app.entityDoc = vi.fn(async (n) => (n === 'count' ? 'Counts rows.' : ''));
+      typeAt(ta, 'cou', 3); // 'count' is the active match
+      expect(container.querySelector('.ac-sig')).toBeNull(); // params no longer duplicated below
+      expect(acDoc(container)).toBeNull();                   // debounced — not fetched yet
+      vi.advanceTimersByTime(200);
+      await flush();
+      expect(app.entityDoc).toHaveBeenCalledWith('count');
+      expect(acDoc(container).textContent).toBe('Counts rows.');
+    });
+    it('shows a keyword doc from the static map (no fetch)', () => {
+      const { app, container, ta } = mounted();
+      app.refData = { keywordDocs: { SELECT: 'Selects rows.' } };
+      typeAt(ta, 'SEL', 3);
+      expect(acDoc(container).textContent).toBe('Selects rows.');
+      expect(app.entityDoc).not.toHaveBeenCalled();
+    });
+    it('hides the footer for a function whose description is empty', async () => {
+      const { app, container, ta } = mounted();
+      app.entityDoc = vi.fn(async () => '');
+      typeAt(ta, 'conc', 4); // 'concat' → fn, empty doc
+      vi.advanceTimersByTime(200);
+      await flush();
+      expect(acDoc(container)).toBeNull();
+      expect(container.querySelector('.ac-footer').style.display).toBe('none');
+    });
+    it('hides the footer for entries with no description source (table/column)', () => {
+      const { container, ta } = mounted();
+      typeAt(ta, 'ont', 3); // 'ontime' → table
+      expect(container.querySelector('.ac-footer').style.display).toBe('none');
+    });
+    it('ignores a doc fetch that resolves after the dropdown closed', async () => {
+      const { app, container, ta } = mounted();
+      app.entityDoc = vi.fn(async () => 'late doc');
+      typeAt(ta, 'cou', 3);
+      vi.advanceTimersByTime(200); // fetch now in flight
+      press(ta, 'Escape');         // close before it resolves
+      await flush();
+      expect(dropdown(container)).toBeNull(); // no crash, nothing resurrected
+    });
+  });
+  it('no matching candidates → no dropdown', () => {
+    const { container, ta } = mounted();
+    typeAt(ta, 'zzz', 3);
+    expect(dropdown(container)).toBeNull();
+  });
+  it('is suppressed while the search panel is open', () => {
+    const { container, ta } = mounted();
+    press(ta, 'f', { metaKey: true }); // open search
+    typeAt(ta, 'co', 2);
+    expect(dropdown(container)).toBeNull();
+  });
+  it('scroll dismisses; blur is wired', () => {
+    const { container, ta } = mounted();
+    typeAt(ta, 'co', 2);
+    ta.dispatchEvent(new Event('blur')); // covers the deferred-hide listener
+    ta.dispatchEvent(new Event('scroll'));
+    expect(dropdown(container)).toBeNull();
+  });
+  it('a tab switch (editorSync) dismisses an open dropdown (#7 review)', () => {
+    const { app, container, ta } = mounted();
+    typeAt(ta, 'co', 2);
+    expect(dropdown(container)).not.toBeNull();
+    app.dom.editorSync(); // switching tabs reassigns ta.value
+    expect(dropdown(container)).toBeNull();
+  });
+  it('tolerates an unset app.completions (defaults to empty, no crash)', () => {
+    const app = makeApp(); // no app.completions
+    const container = document.createElement('div');
+    mountEditor(app, container);
+    const ta = app.dom.editorTextarea;
+    expect(() => typeAt(ta, 'co', 2)).not.toThrow();
+    expect(container.querySelector('.ac-dropdown')).toBeNull();
+  });
+  it('a modified Enter (⌘↵) dismisses without accepting, so it bubbles to Run', () => {
+    const { container, ta } = mounted();
+    typeAt(ta, 'co', 2);
+    const e = press(ta, 'Enter', { metaKey: true });
+    expect(ta.value).toBe('co');            // no token spliced in
+    expect(dropdown(container)).toBeNull(); // dismissed
+    expect(e.defaultPrevented).toBe(false); // not consumed → global Run shortcut fires
+  });
+  it('a caret-moving key (ArrowLeft) dismisses the dropdown', () => {
+    const { container, ta } = mounted();
+    typeAt(ta, 'co', 2);
+    press(ta, 'ArrowLeft');
+    expect(dropdown(container)).toBeNull();
+  });
+  it('clicking in the editor dismisses the dropdown', () => {
+    const { container, ta } = mounted();
+    typeAt(ta, 'co', 2);
+    ta.dispatchEvent(new MouseEvent('click'));
+    expect(dropdown(container)).toBeNull();
+  });
+  it('anchors the popover in CSS px, bridging html{zoom} via the rect/offsetWidth scale', () => {
+    const { container, ta } = mounted();
+    ta.getBoundingClientRect = () => ({ left: 120, top: 60, width: 120, height: 24, right: 240, bottom: 84 });
+    Object.defineProperty(ta, 'offsetWidth', { value: 100, configurable: true });
+    typeAt(ta, 'co', 2);
+    // scale = 120/100 = 1.2; x = 14 + 2*7.8 = 29.6; left = round(120/1.2 + 29.6) = 130
+    expect(dropdown(container).style.left).toBe('130px');
+  });
+});
+
+describe('signature help + hover docs (#27)', () => {
+  const REF = {
+    functions: {
+      sum: { kind: 'agg', sig: 'sum(x)', ret: 'numeric', desc: 'Sum of values.' },
+      substring: { kind: 'fn', sig: 'substring(s, off, len)', ret: 'String', desc: 'A substring.' },
+      now: { kind: 'fn', sig: 'now()', ret: 'DateTime', desc: '' }, // signature, no description
+      CAST: { kind: 'cast', sig: 'CAST(x, T)', ret: '', desc: '' }, // canonically uppercase
+      lpad: { kind: 'fn', sig: 'lpad(s, len[, pad])', ret: 'String', desc: '' }, // optional/bracketed param
+    },
+    keywordDocs: { PREWHERE: 'Filter applied before reading other columns.' },
+    keywordSet: new Set(['PREWHERE']),
+    funcSet: new Set(['sum', 'substring']),
+  };
+  // Hover descriptions are fetched lazily per entity (#27); stub the loader.
+  const DOCS = { sum: 'Sum of values.', substring: 'A substring.' };
+  function mounted(sql = '') {
+    const app = makeApp();
+    app.refData = REF;
+    app.entityDoc = vi.fn(async (name) => DOCS[name] || '');
+    app.completions = []; // no candidates → no dropdown to suppress signature help
+    app.activeTab().sql = sql;
+    const container = document.createElement('div');
+    mountEditor(app, container);
+    const ta = app.dom.editorTextarea;
+    ta.value = sql;
+    return { app, container, ta };
+  }
+  // Flush the microtasks the lazy doc fetch resolves on (fake timers don't fake promises).
+  const flush = async () => { await Promise.resolve(); await Promise.resolve(); };
+  const sig = (c) => c.querySelector('.sig-help');
+  const card = (c) => c.querySelector('.hover-card');
+  const caretMove = (ta, pos) => { ta.selectionStart = ta.selectionEnd = pos; ta.dispatchEvent(new Event('keyup')); };
+
+  it('shows signature help with the active argument bolded inside a call', () => {
+    const { container, ta } = mounted('substring(a, b');
+    caretMove(ta, 'substring(a, '.length); // caret on the 2nd argument
+    const el = sig(container);
+    expect(el).not.toBeNull();
+    expect(el.querySelector('.sig-name').textContent).toBe('substring');
+    expect(el.querySelector('.sig-arg.on').textContent).toBe('off'); // arg index 1
+    expect(el.textContent).toContain('→ String');
+  });
+  it('dismisses signature help when the caret leaves the call', () => {
+    const { container, ta } = mounted('sum(a)');
+    caretMove(ta, 4);
+    expect(sig(container)).not.toBeNull();
+    caretMove(ta, 6); // after the ')'
+    expect(sig(container)).toBeNull();
+  });
+  it('is suppressed while the autocomplete dropdown is open', () => {
+    const { app, container, ta } = mounted();
+    app.completions = [{ label: 'avg', kind: 'agg', insert: 'avg(', detail: 'avg(x)' }];
+    ta.value = 'sum(a'; ta.selectionStart = ta.selectionEnd = 5;
+    ta.dispatchEvent(new Event('input'));
+    expect(container.querySelector('.ac-dropdown')).not.toBeNull();
+    expect(sig(container)).toBeNull();
+  });
+  it('Esc dismisses the signature popover (and is consumed)', () => {
+    const { container, ta } = mounted('sum(a');
+    caretMove(ta, 5);
+    expect(sig(container)).not.toBeNull();
+    const e = new KeyboardEvent('keydown', { key: 'Escape', cancelable: true });
+    ta.dispatchEvent(e);
+    expect(sig(container)).toBeNull();
+    expect(e.defaultPrevented).toBe(true);
+  });
+  it('resolves the function case-insensitively — UPPER and lower (#3 review)', () => {
+    const a = mounted('SUM(x'); // typed upper; canonical key is lowercase 'sum'
+    caretMove(a.ta, 4);
+    expect(sig(a.container)).not.toBeNull();
+    expect(sig(a.container).querySelector('.sig-name').textContent).toBe('SUM');
+    const b = mounted('cast(x'); // typed lower; canonical key is uppercase 'CAST'
+    caretMove(b.ta, 5);
+    expect(sig(b.container)).not.toBeNull();
+    expect(sig(b.container).textContent).toContain('x, T'); // CAST(x, T) metadata resolved via toUpperCase
+  });
+  it('ignores a comma inside a string literal when counting arguments (#2 review)', () => {
+    const v = "substring('a, b', "; // the real 2nd-arg comma is the one after the string
+    const { container, ta } = mounted(v);
+    caretMove(ta, v.length);
+    const el = sig(container);
+    expect(el).not.toBeNull();
+    expect(el.querySelector('.sig-arg.on').textContent).toBe('off'); // arg index 1, not miscounted by the string's comma
+  });
+  it('splits bracketed/optional params cleanly so the active arg aligns (#2 review)', () => {
+    const v = 'lpad(a, b, '; // sig is lpad(s, len[, pad]) — caret on the 3rd arg
+    const { container, ta } = mounted(v);
+    caretMove(ta, v.length);
+    const el = sig(container);
+    expect(el).not.toBeNull();
+    const argTexts = [...el.querySelectorAll('.sig-arg')].map((a) => a.textContent);
+    expect(argTexts).toEqual(['s', 'len', 'pad']); // not ['s','len[',' pad]'] — brackets stripped
+    expect(el.querySelector('.sig-arg.on').textContent).toBe('pad'); // arg index 2 aligns
+  });
+
+  describe('hover docs', () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+    const move = (ta, clientX, clientY = 14) => ta.dispatchEvent(new MouseEvent('mousemove', { clientX, clientY }));
+
+    it('shows the signature immediately and fills in the lazily-fetched description', async () => {
+      const { app, container, ta } = mounted('sum(x)');
+      // equal rect/offsetWidth → scale 1 via the real ratio (not the fallback)
+      ta.getBoundingClientRect = () => ({ left: 0, top: 0, width: 100, right: 100, bottom: 24, height: 24 });
+      Object.defineProperty(ta, 'offsetWidth', { value: 100, configurable: true });
+      move(ta, 22); // → col 1 → the 'sum' token
+      vi.advanceTimersByTime(360);
+      expect(card(container).textContent).toContain('sum(x)'); // signature shown synchronously
+      expect(card(container).querySelector('.hover-doc')).toBeNull(); // doc not fetched yet
+      await flush();
+      expect(app.entityDoc).toHaveBeenCalledWith('sum');
+      expect(card(container).textContent).toContain('Sum of values.'); // lazy doc filled in
+    });
+    it('ignores a late doc fetch once the pointer has left the token', async () => {
+      const { container, ta } = mounted('sum(x)');
+      ta.getBoundingClientRect = () => ({ left: 0, top: 0, width: 100, right: 100, bottom: 24, height: 24 });
+      Object.defineProperty(ta, 'offsetWidth', { value: 100, configurable: true });
+      move(ta, 22);
+      vi.advanceTimersByTime(360); // sig shown, doc fetch in flight
+      ta.dispatchEvent(new MouseEvent('mouseleave')); // hover dismissed
+      await flush(); // the doc resolves but must not resurrect the card
+      expect(card(container)).toBeNull();
+    });
+    it('shows no card when hovering a function word inside a string literal (#1 review)', async () => {
+      const { container, ta } = mounted("x = 'sum'"); // 'sum' is inside the string
+      ta.getBoundingClientRect = () => ({ left: 0, top: 0, width: 100, right: 100, bottom: 24, height: 24 });
+      Object.defineProperty(ta, 'offsetWidth', { value: 100, configurable: true });
+      move(ta, 14 + 6 * 7.8); // col 6 → the 'u' of 'sum', inside the string
+      vi.advanceTimersByTime(360);
+      await flush();
+      expect(card(container)).toBeNull(); // masked text → wordAt returns null → no phantom card
+    });
+    it('hovering a keyword shows its built-in doc', () => {
+      const { container, ta } = mounted('PREWHERE x');
+      move(ta, 14 + 2 * 7.8); // → col 2 → 'PREWHERE'
+      vi.advanceTimersByTime(360);
+      expect(card(container).textContent).toContain('Filter applied before reading');
+    });
+    it('no card over an unknown word, or above the text; mouseleave clears it', () => {
+      const { container, ta } = mounted('sum(zzz)');
+      move(ta, 14 + 5 * 7.8); // → 'zzz' (unknown)
+      vi.advanceTimersByTime(360);
+      expect(card(container)).toBeNull();
+      move(ta, 22, -100); // above the text → offset null
+      vi.advanceTimersByTime(360);
+      expect(card(container)).toBeNull();
+      move(ta, 22); // 'sum' → shows
+      vi.advanceTimersByTime(360);
+      expect(card(container)).not.toBeNull();
+      ta.dispatchEvent(new MouseEvent('mouseleave'));
+      expect(card(container)).toBeNull();
+    });
+    it('hover is suppressed while find is open, and the scroll handler hides popovers', () => {
+      const { container, ta } = mounted('sum(x)');
+      ta.dispatchEvent(new KeyboardEvent('keydown', { key: 'f', metaKey: true, cancelable: true })); // open find
+      move(ta, 22);
+      vi.advanceTimersByTime(360);
+      expect(card(container)).toBeNull(); // suppressed while find open
+    });
+    it('a function whose lazy doc is empty shows just its signature (no stray text)', async () => {
+      const { container, ta } = mounted('now()');
+      move(ta, 14 + 1 * 7.8); // → 'now'
+      vi.advanceTimersByTime(360);
+      await flush(); // entityDoc('now') → '' → no doc div added, no literal "null"
+      const el = card(container);
+      expect(el.textContent).toBe('now() → DateTime'); // signature only, nothing appended
+      expect(el.textContent).not.toContain('null'); // the #2 regression: a null child was rendered as "null"
+      expect(el.querySelector('.hover-doc')).toBeNull();
+    });
+    it('tolerates hovering before reference data has loaded (no refData)', () => {
+      const app = makeApp(); // no app.refData → getFunctions/getKeywordDocs default to {}
+      const container = document.createElement('div');
+      mountEditor(app, container);
+      const ta = app.dom.editorTextarea;
+      ta.value = 'sum(x)';
+      ta.dispatchEvent(new MouseEvent('mousemove', { clientX: 22, clientY: 14 }));
+      vi.advanceTimersByTime(360);
+      expect(container.querySelector('.hover-card')).toBeNull();
+    });
+  });
+});
diff --git a/tests/unit/sql-highlight.test.js b/tests/unit/sql-highlight.test.js
index eb61059..f45e45e 100644
--- a/tests/unit/sql-highlight.test.js
+++ b/tests/unit/sql-highlight.test.js
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { tokenize, SQL_KEYWORDS, SQL_FUNCS } from '../../src/core/sql-highlight.js';
+import { tokenize, maskLiterals, SQL_KEYWORDS, SQL_FUNCS } from '../../src/core/sql-highlight.js';
 
 const types = (sql) => tokenize(sql).map((t) => t[0]);
 const text = (sql) => tokenize(sql).map((t) => t[1]).join('');
@@ -47,6 +47,16 @@ describe('tokenize', () => {
   it('emits "other" for unknown single chars', () => {
     expect(tokenize('@')).toEqual([['other', '@']]);
   });
+  it('accepts dynamic keyword/func sets, overriding the built-ins (#25)', () => {
+    const keywords = new Set(['FOO']);
+    const funcs = new Set(['bar']);
+    const toks = tokenize('FOO bar SELECT count', { keywords, funcs });
+    expect(toks).toContainEqual(['keyword', 'FOO']); // keyword match is case-insensitive
+    expect(toks).toContainEqual(['func', 'bar']);
+    // built-ins no longer classify once overridden
+    expect(toks).toContainEqual(['ident', 'SELECT']);
+    expect(toks).toContainEqual(['ident', 'count']);
+  });
 });
 
 describe('keyword/func sets', () => {
@@ -55,3 +65,21 @@ describe('keyword/func sets', () => {
     expect(SQL_FUNCS.has('count')).toBe(true);
   });
 });
+
+describe('maskLiterals (#2 review)', () => {
+  const NUL = '\0';
+  it('replaces string, comment, and backtick-ident chars with NUL, keeping code + length', () => {
+    const src = "a('(', b) -- )\n`c,d` /* x */";
+    const out = maskLiterals(src);
+    expect(out.length).toBe(src.length);          // offsets preserved
+    expect(out.slice(0, 2)).toBe('a(');           // code untouched
+    expect(out.slice(2, 5)).toBe(NUL.repeat(3));  // the string '(' → NUL (its bracket won't pair)
+    expect(out[5]).toBe(',');                     // the comma OUTSIDE the string stays code
+    expect(out.includes('c,d')).toBe(false);      // the comma inside the backtick ident is masked
+    expect(out.includes('--')).toBe(false);       // line comment masked
+    expect(out.includes('/*')).toBe(false);       // block comment masked
+  });
+  it('leaves a string of pure code unchanged', () => {
+    expect(maskLiterals('count(x, y)')).toBe('count(x, y)');
+  });
+});