create-volt 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to `create-volt` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.12.0] - 2026-06-28
+
+### Added
+- **`--template starter`** — a complete, no-build app shell, fully wired and on
+  out of the box: top nav over **Home**, magic-link **Account**, per-user
+  **Notes** (auth-gated CRUD, db-backed), and **Chat** (realtime rooms + presence
+  + typing). Ships a default `.env` enabling db+mailer+auth+realtime; includes
+  the setup wizard (`--edit`) and Studio (`--studio`). The SaaS-style starting
+  point.
+- Templates can now ship a default `.env` (as `env`, renamed on scaffold).
+
+## [0.11.0] - 2026-06-28
+
+### Added
+- **`create-volt studio`** (and `npm run dev -- --studio`) — an ephemeral,
+  localhost-only **data browser**, à la Prisma Studio. Browse collections and
+  documents across any driver (memory / MongoDB / MySQL / Postgres) and delete
+  docs. It's **never a route in the running app** — it exists only while you run
+  it, binds `127.0.0.1`, and disappears on Ctrl-C (shell/SSH access is the auth).
+  Internal collections (auth tokens/sessions) are hidden.
+- Stores gained `collections()` (enumerate collection names) on every adapter.
+
+### Security
+- Admin/data surfaces are **ephemeral by design** — no standing `/admin` route in
+  the running app to attack (verified: the app 404s admin routes). Same model as
+  the config editor: on-demand, loopback-only, gone when the app runs.
+
 ## [0.10.0] - 2026-06-28
 
 ### Added
@@ -146,6 +173,8 @@ All notable changes to `create-volt` are documented here. The format follows
   watching and full-page hot reload. Supports `--skip-install` and `--force`,
   and auto-detects npm / pnpm / yarn / bun for the install step.
 
+[0.12.0]: https://github.com/MIR-2025/volt/releases/tag/v0.12.0
+[0.11.0]: https://github.com/MIR-2025/volt/releases/tag/v0.11.0
 [0.10.0]: https://github.com/MIR-2025/volt/releases/tag/v0.10.0
 [0.9.0]: https://github.com/MIR-2025/volt/releases/tag/v0.9.0
 [0.8.0]: https://github.com/MIR-2025/volt/releases/tag/v0.8.0

package/README.md

@@ -28,8 +28,9 @@ Pick one with `--template` (default: `default`):
 
 | Template    | What you get                                                          |
 | ----------- | -------------------------------------------------------------------- |
-| `default`   | The Counter + Todos demo on the Volt signal engine. Minimal.        |
-| `guestbook` | A real app: magic-link auth, Socket.io real-time message board, and pluggable **MongoDB / MySQL / Postgres** storage (in-memory by default, so it runs with zero setup). |
+| `default`   | The Counter + Todos demo on the Volt signal engine. Minimal. Add-ons off; turn them on in the wizard. |
+| `starter`   | A full app shell, everything on out of the box: top nav + Home, magic-link **Account**, per-user **Notes** (CRUD), and **Chat** (realtime). The SaaS-style starting point. |
+| `guestbook` | A focused real app: magic-link auth + a Socket.io message board, over pluggable **MongoDB / MySQL / Postgres** storage (in-memory by default). |
 
 Then:
 
@@ -66,6 +67,19 @@ SSH-tunnel hint on a remote box). Enabling an add-on wires its **backend**
 automatically — the **frontend** UI (login form, chat) is yours to build, or
 start from `--template guestbook`, which has it wired end-to-end.
 
+## Studio (data browser)
+
+Browse your database on demand — ephemeral and localhost-only, like Prisma Studio:
+
+```bash
+npm run dev -- --studio    # or: npx create-volt studio
+```
+
+It connects the DB in your `.env`, lets you view/delete documents across any
+driver, and is **never** a route in the running app (no standing `/admin` to
+attack — shell/SSH access is the gate). Needs a persistent driver (MongoDB /
+MySQL / Postgres) to show data; the memory driver is per-process.
+
 ## Updating Volt
 
 Volt is vendored as a single file (`public/volt.js`), not an npm dependency.

package/addons/db/files/lib/stores/memory.js

@@ -29,5 +29,5 @@ export function createMemoryStore() {
     },
   });
 
-  return { name: "memory", async init() {}, collection };
+  return { name: "memory", async init() {}, collection, async collections() { return [...cols.keys()]; } };
 }

package/addons/db/files/lib/stores/mongo.js

@@ -39,5 +39,12 @@ export async function createMongoStore({ uri, dbName }) {
     };
   };
 
-  return { name: "mongodb", async init() {}, collection };
+  return {
+    name: "mongodb",
+    async init() {},
+    collection,
+    async collections() {
+      return (await db.listCollections().toArray()).map((c) => c.name);
+    },
+  };
 }

package/addons/db/files/lib/stores/sql.js

@@ -52,6 +52,9 @@ export async function createSqlStore({ dialect, uri }) {
          )`,
       );
     },
+    async collections() {
+      return (await run(`SELECT DISTINCT coll FROM documents`)).map((r) => r.coll);
+    },
     collection(n) {
       return {
         async put(id, doc) {

package/addons/db/files/public/db-admin-ui.js

@@ -0,0 +1,72 @@
+// db-admin-ui.js — a tiny, auth-gated data browser (frontend for the db add-on).
+// Served at /db-admin-ui.js; mounted by public/app.js only when db + auth are on.
+// Works for every driver — it reads through the generic store API on the server.
+// Documents render as escaped JSON text (Volt holes → text nodes), never HTML.
+import { signal, computed, html } from "/volt.js";
+
+const j = async (url, opts) => {
+  const res = await fetch(url, opts);
+  return { status: res.status, body: await res.json().catch(() => ({})) };
+};
+
+export function dbAdminPanel() {
+  const ready = signal(false); // signed in + loaded
+  const denied = signal(false); // 401
+  const driver = signal("");
+  const collections = signal([]);
+  const current = signal("");
+  const docs = signal([]);
+  const note = signal("");
+
+  async function loadCollections() {
+    const { status, body } = await j("/admin/db/collections");
+    if (status === 401) {
+      denied(true);
+      return;
+    }
+    denied(false);
+    driver(body.driver || "");
+    collections(body.collections || []);
+    ready(true);
+    if (!current() && collections().length) openCollection(collections()[0]);
+  }
+  async function openCollection(name) {
+    current(name);
+    note("");
+    const { body } = await j(`/admin/db/collection?name=${encodeURIComponent(name)}`);
+    docs(body.ok ? body.docs : []);
+  }
+  async function del(id) {
+    if (!id) return;
+    await j(`/admin/db/doc?name=${encodeURIComponent(current())}&id=${encodeURIComponent(id)}`, { method: "DELETE" });
+    docs(docs().filter((d) => d.id !== id));
+    note("Deleted.");
+  }
+
+  loadCollections();
+
+  const collTab = (name) =>
+    html`<button class=${() => "btn btn-sm " + (current() === name ? "btn-primary" : "btn-outline-secondary")} onclick=${() => openCollection(name)}>${name}</button>`;
+
+  const docRow = (d) =>
+    html`<div class="d-flex justify-content-between align-items-start gap-2 py-1" style="border-top:1px solid #232a36">
+      <pre class="mb-0 small flex-grow-1" style="white-space:pre-wrap;color:#cfe3ff">${JSON.stringify(d, null, 2)}</pre>
+      <button class="btn btn-sm btn-outline-danger" onclick=${() => del(d.id)}>✕</button>
+    </div>`;
+
+  const heading = computed(() => `Data ${driver() ? `— ${driver()}` : ""}`);
+
+  return html`<div class="card-x p-4 mb-4">
+    <h2 class="h6 mb-3">${heading} <span class="text-muted small">— admin</span></h2>
+    ${() =>
+      denied()
+        ? html`<p class="text-muted small mb-0">Sign in to browse your data.</p>`
+        : !ready()
+          ? html`<p class="text-muted small mb-0">Loading…</p>`
+          : html`<div class="d-flex flex-wrap gap-1 mb-2">${() => (collections().length ? collections().map(collTab) : html`<span class="text-muted small">No collections yet.</span>`)}</div>
+              <div style="max-height:260px;overflow:auto">
+                ${() => (docs().length ? docs().map(docRow) : html`<span class="text-muted small">Empty.</span>`)}
+              </div>
+              ${() => (note() ? html`<p class="small text-muted mb-0 mt-2">${note}</p>` : null)}`}
+  </div>`;
+}

package/index.js

@@ -36,9 +36,10 @@ ${bold("Usage")}
   npx create-volt <project-directory> [options]
   npx create-volt@latest update              # refresh public/volt.js in an existing app
   npx create-volt@latest config              # open the app's setup wizard (edit add-ons + settings)
+  npx create-volt@latest studio              # browse your data — ephemeral, localhost (like Prisma Studio)
 
 ${bold("Options")}
-  --template <name>  Starter template: default | guestbook  (default: default)
+  --template <name>  Template: default | starter | guestbook  (default: default)
   --port <number>    Dev port for the app (default: derived from today's date)
   --skip-install   Don't run the package manager install step
   --no-git         Don't initialize a git repository
@@ -131,6 +132,21 @@ if (positionals[0] === "config") {
   process.exit(res.status ?? 0);
 }
 
+// --- `studio` subcommand: ephemeral, localhost-only data browser (server.js --studio) ---
+if (positionals[0] === "studio") {
+  const cwd = process.cwd();
+  if (!fs.existsSync(path.join(cwd, "server.js"))) {
+    die(`No ${cyan("server.js")} here — run ${cyan("create-volt studio")} from inside a Volt app.`);
+  }
+  if (portArg) process.env.PORT = String(Number(portArg) || "");
+  const res = spawnSync(process.execPath, ["server.js", "--studio"], {
+    cwd,
+    stdio: "inherit",
+    env: flags.has("--no-open") ? { ...process.env, VOLT_NO_OPEN: "1" } : process.env,
+  });
+  process.exit(res.status ?? 0);
+}
+
 // Resolve the dev port: --port wins, else derive it from today's date as
 // two-digit-year + month (no leading zero) + two-digit-day (house convention),
 // so apps scaffolded on different days don't collide on the same port.
@@ -229,6 +245,11 @@ const shippedGitignore = path.join(targetDir, "gitignore");
 if (fs.existsSync(shippedGitignore)) {
   fs.renameSync(shippedGitignore, path.join(targetDir, ".gitignore"));
 }
+// some templates ship a default .env as "env" (a real .env is stripped from npm)
+const shippedEnv = path.join(targetDir, "env");
+if (fs.existsSync(shippedEnv)) {
+  fs.renameSync(shippedEnv, path.join(targetDir, ".env"));
+}
 
 // Bundle the add-on sources so the app's setup wizard can enable them later
 // (only for templates that ship the wizard, i.e. have a setup/ dir).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-volt",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Scaffold a new Volt app — no-build, signals-based UI with Socket.io hot reload.",
   "type": "module",
   "bin": {

package/templates/default/server.js

@@ -299,9 +299,95 @@ function readEnvFileLines() {
   return fs.existsSync(ENV_PATH) ? fs.readFileSync(ENV_PATH, "utf8").split("\n") : [];
 }
 
-// --- gate: setup on first run / --edit, otherwise the app ---
+// --- Studio: an ephemeral, localhost-only data browser (à la Prisma Studio).
+// Not a route in the running app — it only exists while you run `--studio`, on
+// loopback, and disappears on Ctrl-C. Shell/SSH access is the auth. ---
+const HIDDEN_COLLECTIONS = new Set(["auth_tokens", "auth_sessions", "__voltcheck"]);
+async function startStudio() {
+  loadEnv();
+  if (!enabledFrom(process.env).has("db")) {
+    console.error("Studio needs the db add-on. Enable it: npm run dev -- --edit");
+    process.exit(1);
+  }
+  let store;
+  try {
+    store = await (await addonMod("db")).createStore();
+  } catch (e) {
+    console.error("Studio: couldn't connect the store — " + e.message);
+    process.exit(1);
+  }
+  const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
+  const visible = (n) => n && !HIDDEN_COLLECTIONS.has(n);
+  const assets = {
+    "/volt.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "public", "volt.js"))],
+    "/db-admin-ui.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(ADDONS_DIR, "db", "files", "public", "db-admin-ui.js"))],
+  };
+  const studioHtml = fs.readFileSync(path.join(__dirname, "setup", "studio.html"));
+  const json = (res, code, obj) => {
+    res.statusCode = code;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify(obj));
+  };
+
+  const server = http.createServer(async (req, res) => {
+    const u = new URL(req.url, "http://localhost");
+    const p = u.pathname;
+    try {
+      if (req.method === "GET" && p === "/") {
+        res.setHeader("Content-Type", "text/html; charset=utf-8");
+        return res.end(studioHtml);
+      }
+      if (req.method === "GET" && assets[p]) {
+        res.setHeader("Content-Type", assets[p][0]);
+        return res.end(assets[p][1]);
+      }
+      if (req.method === "GET" && p === "/admin/db/collections") {
+        const all = (await store.collections()) || [];
+        return json(res, 200, { driver: store.name, collections: all.filter(visible) });
+      }
+      if (req.method === "GET" && p === "/admin/db/collection") {
+        const name = u.searchParams.get("name") || "";
+        if (!visible(name)) return json(res, 403, { ok: false, error: "hidden" });
+        const docs = (await store.collection(name).all()).slice(0, 500);
+        return json(res, 200, { ok: true, name, docs });
+      }
+      if (req.method === "DELETE" && p === "/admin/db/doc") {
+        const name = u.searchParams.get("name") || "";
+        const id = u.searchParams.get("id") || "";
+        if (!visible(name)) return json(res, 403, { ok: false, error: "hidden" });
+        if (!id) return json(res, 400, { ok: false, error: "missing id" });
+        await store.collection(name).delete(id);
+        return json(res, 200, { ok: true });
+      }
+      res.statusCode = 404;
+      res.end("not found");
+    } catch (e) {
+      json(res, 500, { ok: false, error: e.message });
+    }
+  });
+
+  server.listen(PORT, "127.0.0.1", () => {
+    const url = `http://localhost:${PORT}`;
+    console.log(`\n⚡ Volt Studio → ${url}   (${store.name})`);
+    console.log("  Browse your data. localhost-only, disposable — Ctrl-C when done.");
+    const ssh = process.env.SSH_CONNECTION;
+    if (ssh) {
+      const host = ssh.split(" ")[2];
+      const user = process.env.USER || process.env.USERNAME || "you";
+      console.log("  Remote box — from your LOCAL machine:");
+      console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
+      console.log(`  …then open ${url}.`);
+    }
+    console.log("");
+    openBrowser(url);
+  });
+}
+
+// --- gate: studio / setup (first run, --edit) / the app ---
 const editMode = process.argv.includes("--edit") || process.argv.includes("-e");
-if (editMode || !fs.existsSync(ENV_PATH)) {
+if (process.argv.includes("--studio")) {
+  startStudio();
+} else if (editMode || !fs.existsSync(ENV_PATH)) {
   startSetup();
 } else {
   loadEnv();

package/templates/default/setup/studio.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Volt Studio</title>
+  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" />
+  <style>
+    body { background: #0f1115; color: #e7e9ee; }
+    .accent { color: #ffd24a; }
+    .card-x { background: #161a22; border: 1px solid #232a36; border-radius: 14px; }
+  </style>
+</head>
+<body>
+  <main class="container py-5" style="max-width: 820px;">
+    <header class="mb-4">
+      <h1 class="h3"><span class="accent">⚡ Volt Studio</span> <small class="text-muted">data browser</small></h1>
+      <p class="text-muted mb-0">Browse the database in your <code>.env</code>. Disposable &amp; localhost-only — close the terminal when done.</p>
+    </header>
+    <div id="app"></div>
+  </main>
+  <script type="module">
+    import { mount } from "/volt.js";
+    import { dbAdminPanel } from "/db-admin-ui.js";
+    mount("#app", dbAdminPanel());
+  </script>
+</body>
+</html>

package/templates/starter/README.md

@@ -0,0 +1,47 @@
+# ⚡ Volt starter
+
+A complete, **no-build** app shell — auth, realtime chat, a per-user notes CRUD,
+and a database, all wired and turned on out of the box. Edit files and save;
+the page hot-reloads.
+
+## Run
+
+```bash
+npm install
+npm run dev        # → http://localhost:26628
+```
+
+It ships with `VOLT_ADDONS=db,mailer,auth,realtime` in `.env`, so it runs the
+full stack immediately (in-memory by default — magic-link emails print to the
+console). Sign in from the **Account** tab, then use **Notes** and **Chat**.
+
+## Sections
+
+- **Home** — a simple dashboard.
+- **Account** — magic-link sign-in (no passwords).
+- **Notes** — per-user CRUD, auth-gated, stored in the db.
+- **Chat** — Socket.io rooms with presence + typing.
+
+## Configure & inspect
+
+```bash
+npm run dev -- --edit    # ephemeral wizard: toggle add-ons, set DB/SMTP, etc.
+npm run dev -- --studio  # ephemeral data browser (like Prisma Studio)
+```
+
+Both are localhost-only and disappear when you close them — no standing admin
+surface. Switch to a real database (MongoDB / MySQL / Postgres) anytime in the
+wizard.
+
+## Layout
+
+```
+public/app.js      the shell — nav + sections (Home/Notes/Chat/Account)
+public/volt.js     the Volt library (no build step)
+views/index.html   the HTML shell
+server.js          dev server + wizard + studio; wires enabled add-ons + notes
+.volt/addons/      bundled add-on sources (enabled via .env)
+.env               which add-ons are on, + their settings
+```
+
+Scaffolded with [`create-volt`](https://www.npmjs.com/package/create-volt) — `--template starter`.

package/templates/starter/env

@@ -0,0 +1,2 @@
+VOLT_ADDONS=db,mailer,auth,realtime
+DB_DRIVER=memory

package/templates/starter/gitignore

@@ -0,0 +1,5 @@
+node_modules
+npm-debug.log*
+.DS_Store
+.env
+*.local

package/templates/starter/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "volt-app",
+  "version": "0.1.0",
+  "private": true,
+  "description": "A Volt app — no-build, signals-based UI with Socket.io hot reload.",
+  "type": "module",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node server.js"
+  },
+  "dependencies": {
+    "express": "^4.19.2",
+    "socket.io": "^4.7.5"
+  }
+}

package/templates/starter/public/app.js

@@ -0,0 +1,159 @@
+// app.js — the starter app shell: a top nav over sections (Home, Notes, Chat,
+// Account). Built on Volt signals. Auth + realtime + db are wired server-side;
+// this is the UI. All dynamic text renders through Volt holes (text nodes,
+// HTML-escaped), so user content can't inject markup.
+import { signal, computed, el, html, mount } from "/volt.js";
+
+let enabled = [];
+try {
+  enabled = await (await fetch("/__volt/addons")).json();
+} catch {
+  /* ignore */
+}
+const hasAuth = enabled.includes("auth");
+const hasChat = enabled.includes("realtime");
+
+const api = async (url, body, method) => {
+  const res = await fetch(url, {
+    method: method || (body ? "POST" : "GET"),
+    headers: body ? { "Content-Type": "application/json" } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  return res.json().catch(() => ({}));
+};
+const shortName = (e) => String(e || "").split("@")[0];
+
+const me = signal(null);
+const section = signal("home");
+api("/api/me").then((r) => me(r.email || null));
+
+// --- Account ---
+function accountSection() {
+  const email = signal("");
+  const notice = signal("");
+  async function sendLink(e) {
+    e?.preventDefault?.();
+    const addr = email().trim();
+    if (!addr) return;
+    notice("Sending…");
+    const r = await api("/api/login", { email: addr });
+    notice(r.ok ? (r.dev ? "Magic link printed to the server console — open it to sign in." : `Link sent to ${addr}.`) : r.error || "Failed.");
+  }
+  async function logout() {
+    await api("/api/logout", {});
+    me(null);
+  }
+  return html`<div class="card-x p-4">
+    <h2 class="h6 mb-3">Account</h2>
+    ${() =>
+      me()
+        ? html`<div class="d-flex justify-content-between align-items-center">
+            <span class="text-muted small">Signed in as <span class="accent fw-semibold">${() => me()}</span></span>
+            <button class="btn btn-sm btn-outline-secondary" onclick=${logout}>Sign out</button>
+          </div>`
+        : html`<form class="d-flex gap-2" onsubmit=${sendLink}>
+            <input class="form-control" type="email" name="email" placeholder="you@example.com" maxlength="320" autocomplete="email" required value=${email} oninput=${(e) => email(e.target.value)} />
+            <button class="btn btn-primary" type="submit">Send magic link</button>
+          </form>`}
+    ${() => (notice() ? html`<p class="small text-muted mb-0 mt-2">${notice}</p>` : null)}
+  </div>`;
+}
+
+// --- Notes (per-user CRUD, auth-gated) ---
+function notesSection() {
+  const notes = signal([]);
+  const draft = signal("");
+  const err = signal("");
+  async function load() {
+    if (!me()) return;
+    const r = await api("/api/notes");
+    notes(r.notes || []);
+  }
+  async function add() {
+    const text = draft().trim();
+    if (!text) return;
+    const r = await api("/api/notes", { text });
+    if (r.ok) {
+      draft("");
+      load();
+    } else err(r.error || "Failed.");
+  }
+  async function del(id) {
+    await api("/api/notes/" + encodeURIComponent(id), null, "DELETE");
+    load();
+  }
+  // reload whenever auth state flips to signed-in
+  let loadedFor = null;
+  const sync = computed(() => {
+    if (me() && loadedFor !== me()) {
+      loadedFor = me();
+      load();
+    }
+    return me();
+  });
+
+  return html`<div class="card-x p-4">
+    <h2 class="h6 mb-3">Notes</h2>
+    ${() =>
+      !sync()
+        ? html`<p class="text-muted small mb-0">Sign in (Account) to keep notes.</p>`
+        : html`<div class="input-group mb-3">
+              <input class="form-control" maxlength="2000" placeholder="Write a note…" value=${draft} oninput=${(e) => draft(e.target.value)} onkeydown=${(e) => e.key === "Enter" && add()} />
+              <button class="btn btn-primary" onclick=${add}>Add</button>
+            </div>
+            ${() =>
+              notes().length
+                ? notes().map(
+                    (n) => html`<div class="d-flex justify-content-between align-items-start gap-2 py-2" style="border-top:1px solid #232a36">
+                      <span>${n.text}</span>
+                      <button class="btn btn-sm btn-outline-danger" onclick=${() => del(n.id)}>✕</button>
+                    </div>`,
+                  )
+                : html`<span class="text-muted small">No notes yet.</span>`}
+            ${() => (err() ? html`<p class="small text-danger mb-0 mt-2">${err}</p>` : null)}`}
+  </div>`;
+}
+
+// --- Home ---
+function homeSection() {
+  return html`<div class="card-x p-4">
+    <h2 class="h5 mb-2">Welcome ${() => (me() ? html`back, <span class="accent">${() => shortName(me())}</span>` : "to your Volt app")}</h2>
+    <p class="text-muted mb-3">A no-build, signals-based app — auth, realtime, and a database, all wired and configured by file. Edit <code>public/app.js</code> and save; it hot-reloads.</p>
+    <div class="d-flex flex-wrap gap-2">
+      <button class="btn btn-sm btn-outline-secondary" onclick=${() => section("notes")}>📝 Notes</button>
+      ${hasChat ? html`<button class="btn btn-sm btn-outline-secondary" onclick=${() => section("chat")}>💬 Chat</button>` : ""}
+      <button class="btn btn-sm btn-outline-secondary" onclick=${() => section("account")}>${() => (me() ? "👤 Account" : "🔑 Sign in")}</button>
+    </div>
+  </div>`;
+}
+
+// --- build sections once; toggle visibility (keeps state + one chat socket) ---
+const sections = { home: homeSection(), account: accountSection() };
+if (hasAuth) sections.notes = notesSection();
+if (hasChat) {
+  try {
+    sections.chat = (await import("/chat-ui.js")).chatPanel();
+  } catch {
+    /* chat UI unavailable */
+  }
+}
+
+const TABS = [
+  ["home", "Home"],
+  ...(hasAuth ? [["notes", "Notes"]] : []),
+  ...(sections.chat ? [["chat", "Chat"]] : []),
+  ["account", "Account"],
+];
+
+const nav = () =>
+  html`<nav class="navx py-2 mb-4">
+    <div class="container d-flex align-items-center" style="max-width:760px">
+      <span class="brand me-3"><span class="accent">⚡ Volt</span></span>
+      ${TABS.map(([key, label]) => html`<button class=${() => "btn btn-link btn-sm " + (section() === key ? "active" : "")} onclick=${() => section(key)}>${label}</button>`)}
+      <span class="ms-auto small text-muted">${() => (me() ? shortName(me()) : "guest")}</span>
+    </div>
+  </nav>`;
+
+const panel = (key) => el("div", { class: "container", style: () => "max-width:760px;display:" + (section() === key ? "block" : "none") }, sections[key]);
+
+mount("#app", nav(), ...Object.keys(sections).map(panel));