create-volt 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ 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
@@ -162,6 +173,7 @@ 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

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:
 

package/index.js

@@ -39,7 +39,7 @@ ${bold("Usage")}
   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
@@ -245,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.11.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/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));

package/templates/starter/public/volt.js

@@ -0,0 +1,265 @@
+// volt.js — a tiny, no-build, signals-based UI library.
+//
+// Not React: there is no JSX, no virtual DOM, and no "re-render the whole
+// component" step. State lives in *signals*; reading a signal inside a piece of
+// UI subscribes that exact piece; writing the signal re-runs only those
+// subscribers and touches only the precise text node / attribute that changed.
+//
+// Two ways to author UI, same engine underneath:
+//   1. html``  — tagged-template markup with ${signal} holes
+//   2. el(...)  — imperative DOM helpers with function-children
+// They interoperate freely (drop an el() node into an html`` template, etc.).
+//
+// Public API: signal, computed, effect, el, html, mount.
+
+// ---------------------------------------------------------------------------
+// Reactive core (signals + effects with ownership-based disposal)
+// ---------------------------------------------------------------------------
+
+let activeEffect = null;
+
+// A signal is a function: call with no args to read, one arg to write.
+//   const n = signal(0);  n();      // read  → 0
+//                         n(n()+1); // write → notifies subscribers
+export function signal(value) {
+  const subs = new Set();
+  return function sig(...args) {
+    if (args.length) {
+      const next = args[0];
+      if (next === value) return value; // no-op on identical value
+      value = next;
+      for (const eff of [...subs]) eff.run(); // copy: run() mutates subs
+      return value;
+    }
+    if (activeEffect) {
+      subs.add(activeEffect);
+      activeEffect.deps.add(subs);
+    }
+    return value;
+  };
+}
+
+// effect(fn) runs fn now, tracks every signal it reads, and re-runs it whenever
+// any of those change. Effects created *inside* another effect are owned by it
+// and disposed before each re-run — so dynamic regions clean up after themselves.
+export function effect(fn) {
+  const eff = {
+    deps: new Set(),
+    children: new Set(),
+    parent: activeEffect,
+    run() {
+      disposeChildren(eff);
+      cleanupDeps(eff);
+      const prev = activeEffect;
+      activeEffect = eff;
+      try {
+        fn();
+      } finally {
+        activeEffect = prev;
+      }
+    },
+    dispose() {
+      disposeChildren(eff);
+      cleanupDeps(eff);
+      if (eff.parent) eff.parent.children.delete(eff);
+    },
+  };
+  if (activeEffect) activeEffect.children.add(eff);
+  eff.run();
+  return () => eff.dispose();
+}
+
+// computed(fn) is a read-only derived signal: () => value, auto-updating.
+export function computed(fn) {
+  const s = signal(undefined);
+  effect(() => s(fn()));
+  return () => s();
+}
+
+function cleanupDeps(eff) {
+  for (const subs of eff.deps) subs.delete(eff);
+  eff.deps.clear();
+}
+
+function disposeChildren(eff) {
+  for (const child of [...eff.children]) child.dispose();
+  eff.children.clear();
+}
+
+// ---------------------------------------------------------------------------
+// DOM helpers
+// ---------------------------------------------------------------------------
+
+// el(tag, props?, ...children) → a real DOM element.
+//   props: { onClick: fn }        → event listener
+//          { class: () => ... }   → reactive attribute (function = live)
+//          { id: 'x' }            → static attribute
+//   children: strings, numbers, nodes, arrays, or functions (functions = live)
+export function el(tag, props, ...children) {
+  const node = document.createElement(tag);
+  if (props) {
+    for (const [key, val] of Object.entries(props)) {
+      if (key.startsWith("on") && typeof val === "function") {
+        node.addEventListener(key.slice(2).toLowerCase(), val);
+      } else if (typeof val === "function") {
+        effect(() => setAttr(node, key, val()));
+      } else {
+        setAttr(node, key, val);
+      }
+    }
+  }
+  for (const child of children) appendChild(node, child);
+  return node;
+}
+
+// mount(target, ...children) appends children into target (selector or element).
+// Top-level function-children are reactive too.
+export function mount(target, ...children) {
+  const parent = typeof target === "string" ? document.querySelector(target) : target;
+  for (const child of children) appendChild(parent, child);
+  return parent;
+}
+
+function setAttr(node, name, value) {
+  if (name === "value") {
+    node.value = value ?? "";
+    return;
+  }
+  if (name === "checked" || name === "disabled" || name === "selected") {
+    node[name] = !!value && value !== "false";
+    return;
+  }
+  if (value === false || value == null) {
+    node.removeAttribute(name);
+    return;
+  }
+  node.setAttribute(name, value);
+}
+
+// Append a child, making function-children into self-updating dynamic regions
+// bounded by two comment anchors (so they can render text, nodes, or lists).
+function appendChild(parent, child) {
+  if (typeof child === "function") {
+    const start = document.createComment("");
+    const end = document.createComment("");
+    parent.appendChild(start);
+    parent.appendChild(end);
+    effect(() => renderRange(start, end, child()));
+    return;
+  }
+  for (const node of toNodes(child)) parent.appendChild(node);
+}
+
+// Replace everything between the start/end anchors with `value`'s nodes.
+function renderRange(start, end, value) {
+  let n = start.nextSibling;
+  while (n && n !== end) {
+    const t = n.nextSibling;
+    n.remove();
+    n = t;
+  }
+  for (const node of toNodes(value)) end.parentNode.insertBefore(node, end);
+}
+
+// Normalize any child value into an array of DOM nodes.
+function toNodes(value) {
+  if (value == null || value === false || value === true) return [];
+  if (Array.isArray(value)) return value.flatMap(toNodes);
+  if (value instanceof Node) return [value];
+  return [document.createTextNode(String(value))];
+}
+
+// ---------------------------------------------------------------------------
+// html`` template layer (parses once, wires holes to the same primitives)
+// ---------------------------------------------------------------------------
+
+const PH = (i) => `__voltph${i}__`;
+const PH_RE = /__voltph(\d+)__/g;
+
+// We're inside an open tag (attribute context) if the last '<' comes after the
+// last '>' in the accumulated string.
+function isAttrContext(str) {
+  return str.lastIndexOf("<") > str.lastIndexOf(">");
+}
+
+export function html(strings, ...values) {
+  let acc = "";
+  strings.forEach((str, i) => {
+    acc += str;
+    if (i < values.length) {
+      acc += isAttrContext(acc) ? PH(i) : `<!--${PH(i)}-->`;
+    }
+  });
+
+  const tpl = document.createElement("template");
+  tpl.innerHTML = acc.trim();
+
+  // Bind attribute holes.
+  for (const node of tpl.content.querySelectorAll("*")) {
+    for (const attr of [...node.attributes]) {
+      PH_RE.lastIndex = 0;
+      if (PH_RE.test(attr.value)) bindAttr(node, attr, values);
+    }
+  }
+
+  // Bind node holes (comment placeholders).
+  const walker = document.createTreeWalker(tpl.content, NodeFilter.SHOW_COMMENT);
+  const holes = [];
+  let c;
+  while ((c = walker.nextNode())) {
+    const m = c.data.match(/^__voltph(\d+)__$/);
+    if (m) holes.push([c, Number(m[1])]);
+  }
+  for (const [comment, i] of holes) bindNodeHole(comment, values[i]);
+
+  const nodes = [...tpl.content.childNodes];
+  return nodes.length === 1 ? nodes[0] : nodes;
+}
+
+function bindAttr(node, attr, values) {
+  const name = attr.name;
+  const raw = attr.value;
+  const single = raw.match(/^__voltph(\d+)__$/);
+  node.removeAttribute(name);
+
+  // onX=${fn} → event listener
+  if (name.startsWith("on") && single) {
+    node.addEventListener(name.slice(2).toLowerCase(), values[Number(single[1])]);
+    return;
+  }
+
+  // Otherwise a (possibly mixed) attribute value. If any hole is a function it
+  // is read inside the effect, so the attribute stays live.
+  effect(() => {
+    const text = raw.replace(PH_RE, (_, j) => {
+      const v = values[Number(j)];
+      return String(typeof v === "function" ? v() : v ?? "");
+    });
+    setAttr(node, name, text);
+  });
+}
+
+function bindNodeHole(comment, value) {
+  const start = document.createComment("");
+  comment.parentNode.insertBefore(start, comment); // `comment` becomes the end anchor
+  if (typeof value === "function") {
+    effect(() => renderRange(start, comment, value()));
+  } else {
+    renderRange(start, comment, value);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hot reload client — listens for the dev server's reload event over Socket.io
+// ---------------------------------------------------------------------------
+
+(function startHotReload() {
+  const connect = () => {
+    if (!window.io) return false;
+    const socket = window.io();
+    socket.on("volt:reload", () => location.reload());
+    console.log("[volt] hot reload connected");
+    return true;
+  };
+  if (!connect()) window.addEventListener("load", connect);
+})();

package/templates/starter/server.js

@@ -0,0 +1,421 @@
+// server.js — dev server with a built-in first-run setup wizard.
+//
+// First run (no .env) or `node server.js --edit` (-e) opens a disposable, local
+// config page: tick add-ons, fill settings, Apply. Apply writes .env (a
+// VOLT_ADDONS list + settings) and adds any needed packages to package.json,
+// runs npm install, then starts the app — which wires whatever .env enables.
+// Add-on code is bundled under .volt/addons; nothing is copied into your code.
+//
+// No build step, no env-file flag: .env is auto-loaded below.
+
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import express from "express";
+import { Server as SocketServer } from "socket.io";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ENV_PATH = path.join(__dirname, ".env");
+const PKG_PATH = path.join(__dirname, "package.json");
+const ADDONS_DIR = path.join(__dirname, ".volt", "addons"); // bundled add-on sources
+const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
+const PKG_VERSIONS = { mongodb: "^6.8.0", mysql2: "^3.11.0", pg: "^8.12.0", nodemailer: "^6.9.0" };
+const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js" };
+
+// --- tiny .env loader (no dependency); never overrides an existing env var ---
+function readEnvFile() {
+  const out = {};
+  if (!fs.existsSync(ENV_PATH)) return out;
+  for (const line of fs.readFileSync(ENV_PATH, "utf8").split("\n")) {
+    const m = line.match(/^\s*([A-Za-z0-9_]+)\s*=\s*(.*?)\s*$/);
+    if (m) out[m[1]] = m[2];
+  }
+  return out;
+}
+function loadEnv() {
+  for (const [k, v] of Object.entries(readEnvFile())) if (!(k in process.env)) process.env[k] = v;
+}
+
+// Add-ons available to enable (bundled under .volt/addons by create-volt).
+function availableAddons() {
+  if (!fs.existsSync(ADDONS_DIR)) return [];
+  return fs
+    .readdirSync(ADDONS_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => {
+      const m = JSON.parse(fs.readFileSync(path.join(ADDONS_DIR, e.name, "meta.json"), "utf8"));
+      return { name: e.name, description: m.description, dependsOn: m.dependsOn || [] };
+    });
+}
+
+// Which add-ons does VOLT_ADDONS turn on (dependencies expanded)?
+function enabledFrom(env) {
+  const metas = Object.fromEntries(availableAddons().map((a) => [a.name, a]));
+  const out = new Set();
+  const visit = (n) => {
+    if (!metas[n] || out.has(n)) return;
+    out.add(n);
+    for (const d of metas[n].dependsOn) visit(d);
+  };
+  for (const n of String(env.VOLT_ADDONS || "").split(",").map((s) => s.trim()).filter(Boolean)) visit(n);
+  return out;
+}
+
+const imp = (rel) => import(pathToFileURL(path.join(__dirname, rel)).href);
+const addonMod = (n) => imp(path.join(".volt", "addons", n, "files", "lib", LIB_FILE[n]));
+
+function openBrowser(url) {
+  if (process.env.VOLT_NO_OPEN || process.argv.includes("--no-open")) return false;
+  const plat = process.platform;
+  if (plat === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return false;
+  const cmd = plat === "darwin" ? "open" : plat === "win32" ? "cmd" : "xdg-open";
+  const args = plat === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {}); // launcher missing — emits async, don't crash
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// --- the actual app: wires whichever add-ons .env enables ---
+async function startApp() {
+  const PORT = Number(process.env.PORT) || DEFAULT_PORT;
+  const enabled = enabledFrom(process.env);
+  const app = express();
+  app.disable("x-powered-by");
+  app.use((_req, res, next) => {
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("X-Frame-Options", "SAMEORIGIN");
+    res.setHeader("Referrer-Policy", "same-origin");
+    next();
+  });
+  app.use(express.static(path.join(__dirname, "public")));
+
+  let store = null;
+  let mailer = null;
+  if (enabled.has("db")) store = await (await addonMod("db")).createStore();
+  if (enabled.has("mailer")) mailer = await (await addonMod("mailer")).createMailer();
+  if (enabled.has("auth") && store && mailer) app.use((await addonMod("auth")).authRouter({ store, mailer }));
+
+  // notes — a per-user CRUD example (auth-gated, owner-scoped, db-backed)
+  if (enabled.has("db") && enabled.has("auth") && store) {
+    const guard = (await addonMod("auth")).requireAuth(store);
+    const notes = store.collection("notes");
+    const r = express.Router();
+    r.use(express.json());
+    r.get("/api/notes", guard, async (req, res) => {
+      const list = (await notes.find({ owner: req.user.email })).sort((a, b) => b.createdAt - a.createdAt);
+      res.json({ notes: list });
+    });
+    r.post("/api/notes", guard, async (req, res) => {
+      const text = String(req.body?.text || "").trim().slice(0, 2000);
+      if (!text) return res.status(400).json({ ok: false, error: "Empty note." });
+      const note = { id: crypto.randomBytes(8).toString("hex"), owner: req.user.email, text, createdAt: Date.now() };
+      await notes.put(note.id, note);
+      res.json({ ok: true, note });
+    });
+    r.delete("/api/notes/:id", guard, async (req, res) => {
+      const n = await notes.get(req.params.id);
+      if (n && n.owner === req.user.email) await notes.delete(req.params.id);
+      res.json({ ok: true });
+    });
+    app.use(r);
+  }
+
+  // expose which add-ons are on, and serve each enabled add-on's frontend assets
+  app.get("/__volt/addons", (_req, res) => res.json([...enabled]));
+  for (const n of enabled) {
+    const pub = path.join(ADDONS_DIR, n, "files", "public");
+    if (fs.existsSync(pub)) app.use(express.static(pub));
+  }
+
+  app.get("/", (_req, res) => res.sendFile(path.join(__dirname, "views", "index.html")));
+
+  const server = http.createServer(app);
+  const io = new SocketServer(server);
+  if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
+
+  let timer = null;
+  const onChange = (file) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      console.log(`[volt] change: ${file ?? "?"} → reload`);
+      io.emit("volt:reload");
+    }, 80);
+  };
+  const watchRecursive = (dir) => {
+    try {
+      fs.watch(dir, { recursive: true }, (_e, f) => onChange(f));
+      return;
+    } catch {
+      /* per-dir fallback */
+    }
+    const w = (d) => {
+      try {
+        fs.watch(d, (_e, f) => onChange(f));
+      } catch {
+        /* ignore */
+      }
+      for (const e of fs.readdirSync(d, { withFileTypes: true })) if (e.isDirectory()) w(path.join(d, e.name));
+    };
+    w(dir);
+  };
+  for (const d of ["views", "public"]) watchRecursive(path.join(__dirname, d));
+
+  const on = [...enabled];
+  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
+}
+
+// Packages an .env's selections need, beyond what package.json already has.
+function neededPackages(env) {
+  const pkg = JSON.parse(fs.readFileSync(PKG_PATH, "utf8"));
+  const deps = pkg.dependencies || {};
+  const want = [];
+  const driver = (env.match(/^\s*DB_DRIVER\s*=\s*(\w+)/m) || [])[1];
+  if (driver === "mongodb") want.push("mongodb");
+  if (driver === "mysql") want.push("mysql2");
+  if (driver === "postgres") want.push("pg");
+  if (/^\s*SMTP_URL\s*=\s*\S/m.test(env)) want.push("nodemailer");
+  return want.filter((p) => !deps[p]);
+}
+
+// --- the disposable setup wizard (localhost only) ---
+function startSetup() {
+  const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
+  const assets = {
+    "/setup.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "setup", "setup.js"))],
+    "/volt.js": ["text/javascript; charset=utf-8", fs.readFileSync(path.join(__dirname, "public", "volt.js"))],
+  };
+  const indexHtml = fs.readFileSync(path.join(__dirname, "setup", "index.html"));
+
+  const server = http.createServer((req, res) => {
+    const u = new URL(req.url, "http://localhost");
+    const p = u.pathname;
+    if (req.method === "GET" && p === "/") {
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      return res.end(indexHtml);
+    }
+    if (req.method === "GET" && assets[p]) {
+      res.setHeader("Content-Type", assets[p][0]);
+      return res.end(assets[p][1]);
+    }
+    if (req.method === "GET" && p === "/setup/state") {
+      res.setHeader("Content-Type", "application/json");
+      return res.end(JSON.stringify({ available: availableAddons(), current: readEnvFile(), defaultPort: DEFAULT_PORT }));
+    }
+    if (req.method === "POST" && p === "/setup/test-db") {
+      let body = "";
+      req.on("data", (c) => (body += c));
+      req.on("end", async () => {
+        const keys = ["DB_DRIVER", "MONGODB_URI", "MONGODB_DATABASE", "DATABASE_URL"];
+        const saved = Object.fromEntries(keys.map((k) => [k, process.env[k]]));
+        try {
+          const { env = {} } = JSON.parse(body);
+          for (const k of keys) {
+            if (env[k]) process.env[k] = env[k];
+            else delete process.env[k];
+          }
+          const store = await (await addonMod("db")).createStore();
+          await store.collection("__voltcheck").all();
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ ok: true, driver: store.name }));
+        } catch (e) {
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ ok: false, error: e.message }));
+        } finally {
+          for (const k of keys) {
+            if (saved[k] == null) delete process.env[k];
+            else process.env[k] = saved[k];
+          }
+        }
+      });
+      return;
+    }
+    if (req.method === "POST" && p === "/setup/apply") {
+      let body = "";
+      req.on("data", (c) => (body += c));
+      req.on("end", () => {
+        try {
+          const { env } = JSON.parse(body);
+          if (typeof env !== "string") throw new Error("missing env");
+
+          // 1) write .env, preserving any custom keys the form doesn't manage
+          let finalEnv = env;
+          if (fs.existsSync(ENV_PATH)) {
+            const managed = new Set([...env.matchAll(/^\s*([A-Za-z0-9_]+)\s*=/gm)].map((m) => m[1]));
+            const extra = readEnvFileLines().filter((line) => {
+              const m = line.match(/^\s*([A-Za-z0-9_]+)\s*=/);
+              return m && !managed.has(m[1]);
+            });
+            if (extra.length) finalEnv = env.replace(/\n*$/, "\n") + extra.join("\n") + "\n";
+          }
+          fs.writeFileSync(ENV_PATH, finalEnv);
+
+          // 2) declare any needed packages in package.json
+          const added = neededPackages(env);
+          if (added.length) {
+            const pkg = JSON.parse(fs.readFileSync(PKG_PATH, "utf8"));
+            pkg.dependencies = pkg.dependencies || {};
+            for (const name of added) pkg.dependencies[name] = PKG_VERSIONS[name] || "latest";
+            fs.writeFileSync(PKG_PATH, JSON.stringify(pkg, null, 2) + "\n");
+          }
+
+          const envPort = Number((env.match(/^\s*PORT\s*=\s*(\d+)/m) || [])[1]);
+          const newPort = process.env.PORT ? Number(process.env.PORT) : envPort || DEFAULT_PORT;
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ ok: true, port: newPort, installing: added }));
+
+          // 3) install (if needed), then hand off to the app
+          res.on("finish", () => {
+            const handoff = () => {
+              server.close(() => {
+                loadEnv();
+                startApp();
+              });
+              server.closeIdleConnections?.();
+            };
+            if (added.length) {
+              console.log(`[volt] installing ${added.join(", ")}…`);
+              const npm = spawn("npm", ["install"], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
+              npm.on("error", () => handoff());
+              npm.on("close", () => {
+                console.log("[volt] saved .env — starting the app…");
+                handoff();
+              });
+            } else {
+              console.log("[volt] saved .env — starting the app…");
+              handoff();
+            }
+          });
+        } catch (e) {
+          res.statusCode = 400;
+          res.end(JSON.stringify({ ok: false, error: e.message }));
+        }
+      });
+      return;
+    }
+    res.statusCode = 404;
+    res.end("not found");
+  });
+
+  server.listen(PORT, "127.0.0.1", () => {
+    const url = `http://localhost:${PORT}`;
+    console.log(`\n⚡ Volt setup → ${url}`);
+    console.log("  Configure your app; it starts automatically on Apply. (reopen later: npm run dev -- --edit)");
+    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 — the server is up here; bridge it from your LOCAL machine:");
+      console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
+      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
+    }
+    console.log("");
+    if (openBrowser(url)) console.log("  (opening your browser…)\n");
+  });
+}
+
+function readEnvFileLines() {
+  return fs.existsSync(ENV_PATH) ? fs.readFileSync(ENV_PATH, "utf8").split("\n") : [];
+}
+
+// --- 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 (process.argv.includes("--studio")) {
+  startStudio();
+} else if (editMode || !fs.existsSync(ENV_PATH)) {
+  startSetup();
+} else {
+  loadEnv();
+  startApp();
+}

package/templates/starter/setup/index.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Set up your Volt app</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; }
+    .form-control, .form-select { background: #0f1115; color: #e7e9ee; border-color: #232a36; }
+    .form-control:focus, .form-select:focus { background: #0f1115; color: #e7e9ee; border-color: #ffd24a; box-shadow: none; }
+    code { color: #ffd24a; }
+  </style>
+</head>
+<body>
+  <main class="container py-5" style="max-width: 640px;">
+    <header class="mb-4">
+      <h1 class="h3"><span class="accent">⚡ Set up your Volt app</span></h1>
+      <p class="text-muted mb-0">Fill these in and the app starts. This page is disposable — it disappears once you click Apply. Re-open it anytime with <code>npm run dev -- --edit</code>.</p>
+    </header>
+    <div id="app"></div>
+  </main>
+  <script type="module" src="/setup.js"></script>
+</body>
+</html>

package/templates/starter/setup/setup.js

@@ -0,0 +1,160 @@
+// setup.js — first-run / --edit wizard, built with Volt. Tick add-ons + fill
+// settings → writes .env (a VOLT_ADDONS list + settings), adds any needed
+// packages, installs, and starts the app. Add-on code is bundled; enabling is
+// just config.
+import { signal, computed, html, mount } from "/volt.js";
+
+const { available, current, defaultPort } = await (await fetch("/setup/state")).json();
+const depsOf = Object.fromEntries(available.map((a) => [a.name, a.dependsOn || []]));
+const order = available.map((a) => a.name);
+const enabledNow = new Set(String(current.VOLT_ADDONS || "").split(",").map((s) => s.trim()).filter(Boolean));
+
+const state = signal({
+  addons: Object.fromEntries(available.map((a) => [a.name, enabledNow.has(a.name)])),
+  dbDriver: current.DB_DRIVER || "memory",
+  mongoUri: current.MONGODB_URI || "",
+  mongoDb: current.MONGODB_DATABASE || "",
+  dbUrl: current.DATABASE_URL || "",
+  smtpUrl: current.SMTP_URL || "",
+  mailFrom: current.MAIL_FROM || "",
+  port: current.PORT || String(defaultPort),
+});
+const set = (patch) => state({ ...state(), ...patch });
+const toggle = (n) => state({ ...state(), addons: { ...state().addons, [n]: !state().addons[n] } });
+const status = signal("");
+
+// selected add-ons, dependencies expanded, in display order
+function effective(s) {
+  const want = new Set();
+  const visit = (n) => {
+    if (want.has(n)) return;
+    want.add(n);
+    (depsOf[n] || []).forEach(visit);
+  };
+  for (const n of order) if (s.addons[n]) visit(n);
+  return order.filter((n) => want.has(n));
+}
+
+const clean = (v) => String(v).replace(/[\r\n]/g, "").trim(); // one value per line; no injection
+function genEnv(s) {
+  const eff = effective(s);
+  const out = [`VOLT_ADDONS=${eff.join(",")}`, `PORT=${clean(s.port)}`];
+  if (eff.includes("db")) {
+    out.push(`DB_DRIVER=${clean(s.dbDriver)}`);
+    if (s.dbDriver === "mongodb") {
+      out.push(`MONGODB_URI=${clean(s.mongoUri)}`);
+      if (s.mongoDb) out.push(`MONGODB_DATABASE=${clean(s.mongoDb)}`);
+    } else if (s.dbDriver === "mysql" || s.dbDriver === "postgres") {
+      out.push(`DATABASE_URL=${clean(s.dbUrl)}`);
+    }
+  }
+  if (eff.includes("mailer")) {
+    if (s.smtpUrl) out.push(`SMTP_URL=${clean(s.smtpUrl)}`);
+    else out.push("# SMTP_URL=        # unset → emails print to the console");
+    if (s.mailFrom) out.push(`MAIL_FROM=${clean(s.mailFrom)}`);
+  }
+  return out.join("\n") + "\n";
+}
+const env = computed(() => genEnv(state()));
+const eff = computed(() => effective(state()));
+
+async function testDb() {
+  const s = state();
+  const e = { DB_DRIVER: s.dbDriver };
+  if (s.dbDriver === "mongodb") {
+    e.MONGODB_URI = s.mongoUri;
+    e.MONGODB_DATABASE = s.mongoDb;
+  } else if (s.dbDriver === "mysql" || s.dbDriver === "postgres") {
+    e.DATABASE_URL = s.dbUrl;
+  }
+  status("Testing connection…");
+  try {
+    const r = await (await fetch("/setup/test-db", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ env: e }) })).json();
+    status(r.ok ? `✓ Connected (${r.driver}).` : `✗ ${r.error}`);
+  } catch {
+    status("Network error testing connection.");
+  }
+}
+
+async function apply() {
+  status("Saving…");
+  let d;
+  try {
+    d = await (await fetch("/setup/apply", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ addons: eff(), env: env() }) })).json();
+  } catch {
+    return status("Network error.");
+  }
+  if (!d.ok) return status("Error: " + d.error);
+  status(d.installing?.length ? `Installing ${d.installing.join(", ")}, then starting…` : "Starting the app…");
+  const target = `http://localhost:${d.port}/`;
+  const tries = d.installing?.length ? 90 : 20; // npm install can take a while
+  const go = async (n) => {
+    try {
+      await fetch(target, { mode: "no-cors" });
+      location.href = target;
+    } catch {
+      if (n > 0) setTimeout(() => go(n - 1), 500);
+      else location.href = target;
+    }
+  };
+  setTimeout(() => go(tries), 600);
+}
+
+// --- views ---
+const field = (label, key, placeholder = "") =>
+  html`<div class="mb-2">
+    <label class="form-label small mb-1">${label}</label>
+    <input class="form-control" placeholder=${placeholder} value=${() => state()[key]} oninput=${(e) => set({ [key]: e.target.value })} />
+  </div>`;
+
+const addonRow = (a) =>
+  html`<div class="form-check mb-2">
+    <input class="form-check-input" type="checkbox" id=${"x-" + a.name} checked=${() => state().addons[a.name]} onchange=${() => toggle(a.name)} />
+    <label class="form-check-label" for=${"x-" + a.name}>
+      <span class="accent">${a.name}</span>${a.dependsOn?.length ? html` <span class="text-muted small">(needs ${a.dependsOn.join(", ")})</span>` : ""}
+      <div class="small text-muted">${a.description}</div>
+    </label>
+  </div>`;
+
+const dbSettings = () =>
+  html`<div class="mb-2">
+      <label class="form-label small mb-1">Database (DB_DRIVER)</label>
+      <select class="form-select" value=${() => state().dbDriver} onchange=${(e) => set({ dbDriver: e.target.value })}>
+        <option value="memory">memory (no setup)</option>
+        <option value="mongodb">mongodb</option>
+        <option value="mysql">mysql</option>
+        <option value="postgres">postgres</option>
+      </select>
+    </div>
+    ${() =>
+      state().dbDriver === "mongodb"
+        ? html`${field("MONGODB_URI", "mongoUri", "mongodb://user:pass@host:27017/db")}${field("MONGODB_DATABASE", "mongoDb", "db")}`
+        : state().dbDriver === "mysql" || state().dbDriver === "postgres"
+          ? field("DATABASE_URL", "dbUrl", state().dbDriver + "://user:pass@host/db")
+          : null}
+    ${() => (state().dbDriver !== "memory" ? html`<button class="btn btn-sm btn-outline-secondary mb-2" onclick=${testDb}>Test connection</button>` : null)}`;
+
+mount(
+  "#app",
+  available.length
+    ? html`<div class="card-x p-4 mb-3">
+        <h2 class="h6 mb-3">Features</h2>
+        ${available.map(addonRow)}
+        <p class="small text-muted mb-0">Enabling a feature wires its backend automatically. Frontend UI (login form, chat) is yours to build — or start from <code>--template guestbook</code>.</p>
+      </div>`
+    : null,
+  html`<div class="card-x p-4 mb-3">
+    <h2 class="h6 mb-3">Settings</h2>
+    ${field("PORT", "port", String(defaultPort))}
+    ${() => (eff().includes("db") ? dbSettings() : null)}
+    ${() => (eff().includes("mailer") ? html`${field("SMTP_URL (optional)", "smtpUrl", "smtp://user:pass@smtp.host:587")}${field("MAIL_FROM", "mailFrom", "App <no-reply@you.com>")}` : null)}
+  </div>`,
+  html`<div class="card-x p-4 mb-3">
+    <div class="d-flex justify-content-between align-items-center mb-2">
+      <h2 class="h6 mb-0">.env</h2>
+      <button class="btn btn-primary btn-sm" onclick=${apply}>Apply & start →</button>
+    </div>
+    <pre class="mb-0" style="background:#0b0d11;border:1px solid #232a36;border-radius:10px;padding:12px;color:#cfe3ff;white-space:pre-wrap">${env}</pre>
+  </div>`,
+  () => (status() ? html`<p class="small accent">${status}</p>` : null),
+);

package/templates/starter/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/views/index.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Volt starter</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; }
+    .brand { font-weight: 800; letter-spacing: -.02em; }
+    .accent { color: #ffd24a; }
+    .card-x { background: #161a22; border: 1px solid #232a36; border-radius: 14px; }
+    .form-control, .form-select { background: #0f1115; color: #e7e9ee; border-color: #232a36; }
+    .form-control:focus, .form-select:focus { background: #0f1115; color: #e7e9ee; border-color: #ffd24a; box-shadow: none; }
+    .navx { background: #11151c; border-bottom: 1px solid #232a36; }
+    .navx .btn-link { color: #9aa4b2; text-decoration: none; }
+    .navx .btn-link.active { color: #ffd24a; }
+    a { color: #ffd24a; }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script src="/socket.io/socket.io.js"></script>
+  <script type="module" src="/app.js"></script>
+</body>
+</html>