create-volt 0.5.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,75 @@ 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.9.0] - 2026-06-28
+
+### Changed
+- The setup wizard is now the single place to configure an app, and it shows
+  **all** add-ons: tick db/auth/realtime/mailer + fill their settings. Enabling
+  is pure config — **Apply writes `.env`** (a `VOLT_ADDONS` list + settings) and
+  **adds any needed packages to `package.json` + runs `npm install`**, then
+  starts the app, which **auto-wires** whatever `.env` enables (auth routes,
+  realtime sockets, db). Add-on code ships bundled under `.volt/addons`; nothing
+  is copied into your `lib/`.
+- `create-volt config` now just opens that in-app wizard (`server.js --edit`) —
+  one implementation, localhost-only (shell/SSH access is the auth).
+
+### Removed
+- The standalone create-volt config page and its `--host`/key flags (superseded
+  by the in-app wizard, which is localhost-only + SSH-tunnel for remote).
+
+### Note
+- Backend of an enabled add-on is wired automatically; the frontend UI (login
+  form, chat) is yours to build — or start from `--template guestbook`.
+
+## [0.8.0] - 2026-06-28
+
+### Added
+- **First-run setup wizard** baked into the app: on first run (no `.env`) or with
+  `npm run dev -- --edit` (`-e`), `server.js` serves a disposable local config
+  page; click **Apply** and it writes `.env`, loads it, and starts the app
+  in-process — the setup page then disappears. It self-detects which add-ons are
+  present and only asks for their settings.
+- **Auto-open browser** on first run (and prints the link); skips opening on
+  headless/remote boxes (no `DISPLAY`). Opt out with `--no-open` / `VOLT_NO_OPEN`.
+- **`--start`** flag for `create-volt`: scaffold, then launch the dev server
+  (which opens the setup page) in one go.
+- **`.env` auto-loader** in templates — no `node --env-file` needed; reads the
+  file directly, so it behaves identically on Windows/PowerShell.
+- **Test connection** button in the wizard: actually connects with the entered
+  DB credentials before you save.
+
+### Changed
+- `create-volt config` is **localhost-only by default** (shell/SSH access is the
+  auth — no key). Expose on a LAN with `--host 0.0.0.0`, which then mints a key.
+
+## [0.7.0] - 2026-06-28
+
+### Added
+- `create-volt config` — a disposable, key-gated local page (built with Volt) for
+  add-ons. Tick the add-ons (or **All**), fill settings (DB driver/URL, SMTP,
+  port), then **Apply**: it copies the add-on files into the app *and* writes
+  `.env`, and shows copy-able install + wiring. Prints localhost **and** LAN
+  links plus an SSH-tunnel hint for remote/headless boxes; a random key gates the
+  page and the apply endpoint. Dependency-free (node:http). Run apps with
+  `node --env-file=.env`.
+
+### Removed
+- The `create-volt add` command (from 0.6.0) — applying add-ons now happens
+  through `create-volt config`, which both copies files and writes `.env`.
+
+## [0.6.0] - 2026-06-28
+
+### Added
+- `create-volt add <integration>` — layer composable add-ons into an existing
+  app instead of cloning whole templates. Copies self-contained files and prints
+  the wiring (never edits your code); supports `--dry-run` and `--force`, and
+  `create-volt add` with no name lists what's available. Integrations:
+  - `db` — document store over memory / MongoDB / MySQL / Postgres
+  - `mailer` — console (dev) / SMTP (prod) email
+  - `auth` — magic-link login + sessions (builds on db + mailer)
+  - `realtime` — Socket.io chat with rooms, presence, and typing
+
 ## [0.5.0] - 2026-06-28
 
 ### Added
@@ -60,6 +129,10 @@ 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.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
+[0.7.0]: https://github.com/MIR-2025/volt/releases/tag/v0.7.0
+[0.6.0]: https://github.com/MIR-2025/volt/releases/tag/v0.6.0
 [0.5.0]: https://github.com/MIR-2025/volt/releases/tag/v0.5.0
 [0.4.0]: https://github.com/MIR-2025/volt/releases/tag/v0.4.0
 [0.3.2]: https://github.com/MIR-2025/volt/releases/tag/v0.3.2

package/README.md

@@ -40,6 +40,32 @@ npm run dev        # → http://localhost:26628
 
 Edit `public/app.js` and save — the page hot-reloads itself.
 
+## Add-on integrations
+
+Apps ship with the add-ons **bundled** (under `.volt/addons`) but off. The
+**setup wizard** turns them on — it opens on first run, or anytime with:
+
+```bash
+npm run dev -- --edit      # or: npx create-volt config
+```
+
+Tick the features you want, fill in their settings, and **Apply**. Enabling is
+pure config: it writes `.env` (a `VOLT_ADDONS` list + settings) and adds any
+needed packages to `package.json` + runs `npm install`. The app then auto-wires
+whatever's enabled. Available add-ons:
+
+| Add-on     | What it gives you                                                    |
+| ---------- | ------------------------------------------------------------------- |
+| `db`       | document store: memory / MongoDB / MySQL / Postgres, one interface  |
+| `mailer`   | console (dev) / SMTP (prod) email                                   |
+| `auth`     | magic-link login + sessions (pulls in db + mailer)                  |
+| `realtime` | Socket.io chat: rooms, presence, typing (pulls in db)              |
+
+The wizard is localhost-only (shell/SSH access is the auth; it prints an
+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.
+
 ## Updating Volt
 
 Volt is vendored as a single file (`public/volt.js`), not an npm dependency.

package/addons/auth/files/lib/auth.js

@@ -0,0 +1,121 @@
+// auth.js — passwordless magic-link login (no passwords), per the house auth
+// convention: submit email → one-time token + UA stored, link emailed →
+// opening the link shows a confirm page (same browser) → confirm starts a
+// session cookie. Tokens are single-use and expire. Needs the `db` and
+// `mailer` add-ons (store.collection + mailer.send).
+
+import crypto from "node:crypto";
+import express from "express";
+
+const TOKEN_TTL = 15 * 60 * 1000; // 15 minutes
+const SESSION_TTL = 30 * 24 * 60 * 60 * 1000; // 30 days
+export const SESSION_COOKIE = "volt_sid";
+
+const token = () => crypto.randomBytes(32).toString("hex");
+const normalize = (e) => String(e || "").trim().toLowerCase();
+const validEmail = (e) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(e);
+
+export function parseCookies(header = "") {
+  const out = {};
+  for (const part of header.split(";")) {
+    const i = part.indexOf("=");
+    if (i !== -1) out[part.slice(0, i).trim()] = decodeURIComponent(part.slice(i + 1).trim());
+  }
+  return out;
+}
+
+export async function sessionFromReq(store, req) {
+  const sid = parseCookies(req.headers.cookie)[SESSION_COOKIE];
+  if (!sid) return null;
+  const s = await store.collection("auth_sessions").get(sid);
+  if (!s) return null;
+  if (s.expiresAt < Date.now()) {
+    await store.collection("auth_sessions").delete(sid);
+    return null;
+  }
+  return s;
+}
+
+export function requireAuth(store) {
+  return async (req, res, next) => {
+    const session = await sessionFromReq(store, req);
+    if (!session) return res.status(401).json({ ok: false, error: "Sign in first." });
+    req.user = session;
+    next();
+  };
+}
+
+const confirmPage = (tok) => `<!doctype html><html><head><meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Confirm login</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}.card-x{background:#161a22;border:1px solid #232a36;border-radius:14px}.accent{color:#ffd24a}</style>
+</head><body><main class="container py-5" style="max-width:480px">
+<div class="card-x p-4 text-center">
+  <h1 class="h5 mb-3"><span class="accent">Confirm login</span></h1>
+  <p class="text-muted">Open in the same browser you requested the link from.</p>
+  <button id="b" class="btn btn-primary w-100">Confirm login</button>
+  <p id="s" class="mt-3 mb-0 small text-muted"></p>
+</div></main><script>
+const t=${JSON.stringify(tok)},b=document.getElementById("b"),s=document.getElementById("s");
+b.onclick=async()=>{b.disabled=true;s.textContent="Confirming…";
+try{const r=await fetch("/api/confirm",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({token:t})});
+const d=await r.json();if(d.ok){location.href="/";}else{s.textContent=d.error||"Failed.";b.disabled=false;}}
+catch{s.textContent="Network error.";b.disabled=false;}};
+</script></body></html>`;
+
+export function authRouter({ store, mailer }) {
+  const tokens = store.collection("auth_tokens");
+  const sessions = store.collection("auth_sessions");
+  const router = express.Router();
+  router.use(express.json());
+
+  router.post("/api/login", async (req, res) => {
+    const email = normalize(req.body?.email);
+    if (!validEmail(email)) return res.status(400).json({ ok: false, error: "Enter a valid email." });
+    const tok = token();
+    await tokens.put(tok, { email, ua: req.headers["user-agent"] || "", expiresAt: Date.now() + TOKEN_TTL, used: false });
+    const link = `${req.protocol}://${req.get("host")}/verify?token=${tok}`;
+    await mailer.send({
+      to: email,
+      subject: "Your login link",
+      text: `Sign in: ${link}\n\nExpires shortly, single use.`,
+      html: `<p>Sign in: <a href="${link}">${link}</a></p>`,
+    });
+    res.json({ ok: true, dev: mailer.name === "console" });
+  });
+
+  router.get("/verify", (req, res) => res.type("html").send(confirmPage(String(req.query.token || ""))));
+
+  router.post("/api/confirm", async (req, res) => {
+    const rec = await tokens.get(String(req.body?.token || ""));
+    if (!rec) return res.status(400).json({ ok: false, error: "Invalid link." });
+    if (rec.used) return res.status(400).json({ ok: false, error: "Link already used." });
+    if (rec.expiresAt < Date.now()) return res.status(400).json({ ok: false, error: "Link expired." });
+    const ua = req.headers["user-agent"] || "";
+    if (rec.ua && ua && rec.ua !== ua) return res.status(400).json({ ok: false, error: "Open the link in the same browser." });
+
+    await tokens.put(rec.id, { ...rec, used: true });
+    const sid = token();
+    await sessions.put(sid, { email: rec.email, expiresAt: Date.now() + SESSION_TTL });
+    res.setHeader(
+      "Set-Cookie",
+      `${SESSION_COOKIE}=${encodeURIComponent(sid)}; HttpOnly; SameSite=Lax; Path=/; Max-Age=${SESSION_TTL / 1000}`,
+    );
+    res.json({ ok: true, email: rec.email });
+  });
+
+  router.post("/api/logout", async (req, res) => {
+    const session = await sessionFromReq(store, req);
+    if (session) await sessions.delete(session.id);
+    res.setHeader("Set-Cookie", `${SESSION_COOKIE}=; HttpOnly; Path=/; Max-Age=0`);
+    res.json({ ok: true });
+  });
+
+  router.get("/api/me", async (req, res) => {
+    const session = await sessionFromReq(store, req);
+    res.json({ email: session?.email || null });
+  });
+
+  return router;
+}

package/addons/auth/meta.json

@@ -0,0 +1,8 @@
+{
+  "description": "Passwordless magic-link auth: single-use token, same-browser guard, session cookie. Builds on db + mailer.",
+  "dependsOn": ["db", "mailer"],
+  "sentinel": "lib/auth.js",
+  "install": ["express"],
+  "optional": {},
+  "wiring": "import { createStore } from \"./lib/store.js\";\nimport { createMailer } from \"./lib/mailer.js\";\nimport { authRouter, sessionFromReq, requireAuth } from \"./lib/auth.js\";\n\nconst store = await createStore();\nconst mailer = await createMailer();\n\napp.use(authRouter({ store, mailer }));   // adds /api/login, /verify, /api/confirm, /api/logout, /api/me\n\n// protect a route:\napp.post(\"/api/things\", requireAuth(store), (req, res) => {\n  res.json({ ok: true, you: req.user.email });\n});\n\n// or check anywhere:\nconst session = await sessionFromReq(store, req);   // { email } | null"
+}

package/addons/db/files/lib/store.js

@@ -0,0 +1,42 @@
+// store.js — a tiny document store with swappable backends. Pick one with the
+// DB_DRIVER env var (default: memory). Every backend exposes the same API:
+//
+//   const store = await createStore();
+//   const col = store.collection("things");
+//   await col.put(id, doc);   // upsert (doc gets an `id`)
+//   await col.get(id);        // → doc | null
+//   await col.all();          // → doc[]
+//   await col.find({ k: v }); // → doc[]  (simple equality match)
+//   await col.delete(id);
+
+import { createMemoryStore } from "./stores/memory.js";
+import { createMongoStore } from "./stores/mongo.js";
+import { createSqlStore } from "./stores/sql.js";
+
+export async function createStore() {
+  const driver = (process.env.DB_DRIVER || "memory").toLowerCase();
+
+  let store;
+  switch (driver) {
+    case "memory":
+      store = createMemoryStore();
+      break;
+    case "mongodb":
+    case "mongo":
+      store = await createMongoStore({ uri: process.env.MONGODB_URI, dbName: process.env.MONGODB_DATABASE });
+      break;
+    case "mysql":
+      store = await createSqlStore({ dialect: "mysql", uri: process.env.DATABASE_URL });
+      break;
+    case "postgres":
+    case "postgresql":
+    case "pg":
+      store = await createSqlStore({ dialect: "postgres", uri: process.env.DATABASE_URL });
+      break;
+    default:
+      throw new Error(`Unknown DB_DRIVER "${driver}" (use memory | mongodb | mysql | postgres)`);
+  }
+
+  await store.init();
+  return store;
+}

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

@@ -0,0 +1,33 @@
+// memory.js — in-memory document store. Zero-dependency dev fallback; data is
+// lost on restart. Same collection API as the Mongo / SQL adapters.
+
+export function createMemoryStore() {
+  const cols = new Map(); // name -> Map(id -> doc)
+  const col = (n) => {
+    if (!cols.has(n)) cols.set(n, new Map());
+    return cols.get(n);
+  };
+  const match = (doc, query) => Object.entries(query).every(([k, v]) => doc[k] === v);
+
+  const collection = (n) => ({
+    async put(id, doc) {
+      const saved = { ...doc, id };
+      col(n).set(id, saved);
+      return saved;
+    },
+    async get(id) {
+      return col(n).get(id) ?? null;
+    },
+    async all() {
+      return [...col(n).values()];
+    },
+    async find(query = {}) {
+      return [...col(n).values()].filter((d) => match(d, query));
+    },
+    async delete(id) {
+      col(n).delete(id);
+    },
+  });
+
+  return { name: "memory", async init() {}, collection };
+}

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

@@ -0,0 +1,43 @@
+// mongo.js — MongoDB document store. Lazy-loads the `mongodb` driver, so it's
+// only needed when DB_DRIVER=mongodb. Each collection maps to a Mongo
+// collection; the document id is stored as `_id`.
+
+export async function createMongoStore({ uri, dbName }) {
+  let MongoClient;
+  try {
+    ({ MongoClient } = await import("mongodb"));
+  } catch {
+    throw new Error("DB_DRIVER=mongodb but 'mongodb' isn't installed. Run: npm install mongodb");
+  }
+  if (!uri) throw new Error("DB_DRIVER=mongodb requires MONGODB_URI");
+
+  const client = new MongoClient(uri);
+  await client.connect();
+  const db = client.db(dbName || undefined);
+  const strip = ({ _id, ...rest }) => rest;
+
+  const collection = (n) => {
+    const c = db.collection(n);
+    return {
+      async put(id, doc) {
+        await c.replaceOne({ _id: id }, { _id: id, ...doc, id }, { upsert: true });
+        return { ...doc, id };
+      },
+      async get(id) {
+        const d = await c.findOne({ _id: id });
+        return d ? strip(d) : null;
+      },
+      async all() {
+        return (await c.find().toArray()).map(strip);
+      },
+      async find(query = {}) {
+        return (await c.find(query).toArray()).map(strip);
+      },
+      async delete(id) {
+        await c.deleteOne({ _id: id });
+      },
+    };
+  };
+
+  return { name: "mongodb", async init() {}, collection };
+}

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

@@ -0,0 +1,79 @@
+// sql.js — MySQL / Postgres document store. Documents are kept as JSON in one
+// `documents(coll, id, data)` table, so any collection works without a schema.
+// Lazy-loads mysql2 or pg and normalizes the two dialect differences:
+//   • placeholders:  MySQL `?`            Postgres `$1, $2, …`
+//   • upsert:        ON DUPLICATE KEY     ON CONFLICT … DO UPDATE
+//
+// find() filters in JS (reads the collection, then matches) — fine for an
+// example; add real indexes/queries if a collection grows large.
+
+export async function createSqlStore({ dialect, uri }) {
+  if (!uri) throw new Error(`DB_DRIVER=${dialect} requires a connection string (DATABASE_URL)`);
+
+  let run; // (sql, params) => rows[]
+  if (dialect === "mysql") {
+    let mysql;
+    try {
+      mysql = (await import("mysql2/promise")).default;
+    } catch {
+      throw new Error("DB_DRIVER=mysql but 'mysql2' isn't installed. Run: npm install mysql2");
+    }
+    const pool = mysql.createPool(uri);
+    run = async (sql, params = []) => (await pool.query(sql, params))[0];
+  } else {
+    let pg;
+    try {
+      pg = await import("pg");
+    } catch {
+      throw new Error("DB_DRIVER=postgres but 'pg' isn't installed. Run: npm install pg");
+    }
+    const pool = new pg.default.Pool({ connectionString: uri });
+    run = async (sql, params = []) => (await pool.query(sql, params)).rows;
+  }
+
+  const ph = dialect === "mysql" ? () => "?" : (i) => `$${i}`;
+  const upsert =
+    dialect === "mysql"
+      ? `INSERT INTO documents (coll, id, data) VALUES (${ph(1)}, ${ph(2)}, ${ph(3)}) ON DUPLICATE KEY UPDATE data = VALUES(data)`
+      : `INSERT INTO documents (coll, id, data) VALUES (${ph(1)}, ${ph(2)}, ${ph(3)}) ON CONFLICT (coll, id) DO UPDATE SET data = EXCLUDED.data`;
+
+  const parse = (rows) => rows.map((r) => JSON.parse(r.data));
+  const match = (doc, query) => Object.entries(query).every(([k, v]) => doc[k] === v);
+
+  const store = {
+    name: dialect,
+    async init() {
+      await run(
+        `CREATE TABLE IF NOT EXISTS documents (
+           coll VARCHAR(64) NOT NULL,
+           id   VARCHAR(128) NOT NULL,
+           data TEXT NOT NULL,
+           PRIMARY KEY (coll, id)
+         )`,
+      );
+    },
+    collection(n) {
+      return {
+        async put(id, doc) {
+          const saved = { ...doc, id };
+          await run(upsert, [n, id, JSON.stringify(saved)]);
+          return saved;
+        },
+        async get(id) {
+          const rows = await run(`SELECT data FROM documents WHERE coll = ${ph(1)} AND id = ${ph(2)}`, [n, id]);
+          return rows[0] ? JSON.parse(rows[0].data) : null;
+        },
+        async all() {
+          return parse(await run(`SELECT data FROM documents WHERE coll = ${ph(1)}`, [n]));
+        },
+        async find(query = {}) {
+          return (await this.all()).filter((d) => match(d, query));
+        },
+        async delete(id) {
+          await run(`DELETE FROM documents WHERE coll = ${ph(1)} AND id = ${ph(2)}`, [n, id]);
+        },
+      };
+    },
+  };
+  return store;
+}

package/addons/db/meta.json

@@ -0,0 +1,12 @@
+{
+  "description": "Pluggable document store: memory (default) / MongoDB / MySQL / Postgres, one interface.",
+  "dependsOn": [],
+  "sentinel": "lib/store.js",
+  "install": [],
+  "optional": {
+    "mongodb": "DB_DRIVER=mongodb",
+    "mysql2": "DB_DRIVER=mysql",
+    "pg": "DB_DRIVER=postgres"
+  },
+  "wiring": "import { createStore } from \"./lib/store.js\";\n\nconst store = await createStore();              // reads DB_DRIVER (default: memory)\nconst notes = store.collection(\"notes\");\nawait notes.put(\"abc\", { text: \"hi\" });\nconst one = await notes.get(\"abc\");\nconst all = await notes.all();\nconst some = await notes.find({ done: false });\n\nEnv for a real database:\n  DB_DRIVER=mongodb  MONGODB_URI=...  [MONGODB_DATABASE=...]\n  DB_DRIVER=mysql    DATABASE_URL=mysql://user:pass@host:3306/db   (npm i mysql2)\n  DB_DRIVER=postgres DATABASE_URL=postgres://user:pass@host:5432/db (npm i pg)"
+}

package/addons/mailer/files/lib/mailer.js

@@ -0,0 +1,33 @@
+// mailer.js — sends email. In dev (no SMTP_URL) it prints messages to the
+// console so you can see them; in production it uses nodemailer when SMTP_URL
+// is set and the package is installed.
+
+export async function createMailer() {
+  const smtp = process.env.SMTP_URL;
+  const from = process.env.MAIL_FROM || "App <no-reply@example.com>";
+
+  if (smtp) {
+    let nodemailer;
+    try {
+      nodemailer = (await import("nodemailer")).default;
+    } catch {
+      console.warn("[mailer] SMTP_URL set but 'nodemailer' isn't installed — using console. Run: npm install nodemailer");
+    }
+    if (nodemailer) {
+      const transport = nodemailer.createTransport(smtp);
+      return {
+        name: "smtp",
+        async send({ to, subject, text, html }) {
+          await transport.sendMail({ to, from, subject, text, html });
+        },
+      };
+    }
+  }
+
+  return {
+    name: "console",
+    async send({ to, subject, text }) {
+      console.log(`\n📨  Email to ${to} — ${subject}\n    ${String(text || "").replace(/\n/g, "\n    ")}\n`);
+    },
+  };
+}

package/addons/mailer/meta.json

@@ -0,0 +1,10 @@
+{
+  "description": "Email sender: prints to the console in dev, uses SMTP (nodemailer) when SMTP_URL is set.",
+  "dependsOn": [],
+  "sentinel": "lib/mailer.js",
+  "install": [],
+  "optional": {
+    "nodemailer": "real SMTP sending (set SMTP_URL)"
+  },
+  "wiring": "import { createMailer } from \"./lib/mailer.js\";\n\nconst mailer = await createMailer();\nawait mailer.send({ to, subject, text, html });\n\nEnv for real email:\n  SMTP_URL=smtp://user:pass@smtp.example.com:587   (npm i nodemailer)\n  MAIL_FROM=\"You <no-reply@you.com>\""
+}

package/addons/realtime/files/lib/realtime.js

@@ -0,0 +1,78 @@
+// realtime.js — Socket.io live chat: rooms, presence, and typing indicators.
+// Messages persist to the `messages` collection (db add-on). User identity
+// comes from the auth session cookie when the auth add-on is present;
+// otherwise each socket is an anonymous "guest-XXXX".
+
+import crypto from "node:crypto";
+
+function parseCookies(header = "") {
+  const out = {};
+  for (const part of header.split(";")) {
+    const i = part.indexOf("=");
+    if (i !== -1) out[part.slice(0, i).trim()] = decodeURIComponent(part.slice(i + 1).trim());
+  }
+  return out;
+}
+
+// Resolve a display name for a socket: the signed-in email, or a guest id.
+async function identify(socket, store) {
+  try {
+    const sid = parseCookies(socket.handshake.headers.cookie)["volt_sid"];
+    if (sid && store) {
+      const s = await store.collection("auth_sessions").get(sid);
+      if (s && s.expiresAt > Date.now()) return s.email;
+    }
+  } catch {
+    /* ignore — fall through to guest */
+  }
+  return "guest-" + crypto.randomBytes(2).toString("hex");
+}
+
+export function attachRealtime(io, { store } = {}) {
+  const messages = store ? store.collection("messages") : null;
+  const presence = new Map(); // room -> Map(socketId -> name)
+
+  const usersIn = (room) => [...new Set([...(presence.get(room)?.values() || [])])];
+  const broadcastPresence = (room) => io.to(room).emit("chat:presence", { room, users: usersIn(room) });
+
+  io.on("connection", async (socket) => {
+    const name = await identify(socket, store);
+    let current = null;
+
+    socket.on("chat:join", async ({ room }) => {
+      if (!room) return;
+      if (current) {
+        socket.leave(current);
+        presence.get(current)?.delete(socket.id);
+        broadcastPresence(current);
+      }
+      current = String(room);
+      socket.join(current);
+      if (!presence.has(current)) presence.set(current, new Map());
+      presence.get(current).set(socket.id, name);
+
+      const history = messages ? (await messages.find({ room: current })).sort((a, b) => a.createdAt - b.createdAt).slice(-100) : [];
+      socket.emit("chat:history", { room: current, messages: history });
+      broadcastPresence(current);
+    });
+
+    socket.on("chat:message", async ({ room, body }) => {
+      const text = String(body || "").trim();
+      if (!room || !text) return;
+      const msg = { id: crypto.randomBytes(8).toString("hex"), room: String(room), name, body: text.slice(0, 500), createdAt: Date.now() };
+      if (messages) await messages.put(msg.id, msg);
+      io.to(String(room)).emit("chat:message", msg);
+    });
+
+    socket.on("chat:typing", ({ room }) => {
+      if (room) socket.to(String(room)).emit("chat:typing", { name });
+    });
+
+    socket.on("disconnect", () => {
+      if (current) {
+        presence.get(current)?.delete(socket.id);
+        broadcastPresence(current);
+      }
+    });
+  });
+}

package/addons/realtime/files/public/chat-client.js

@@ -0,0 +1,30 @@
+// chat-client.js — thin browser wrapper around the Socket.io chat events.
+// Pair it with Volt signals in your app.js. Requires the socket.io client
+// (load /socket.io/socket.io.js before your module).
+//
+//   import { createChat } from "/chat-client.js";
+//   const chat = createChat({
+//     onHistory:  ({ room, messages }) => ...,
+//     onMessage:  (msg) => ...,
+//     onPresence: ({ room, users }) => ...,
+//     onTyping:   ({ name }) => ...,
+//   });
+//   chat.join("general");
+//   chat.send("general", "hello");
+//   chat.typing("general");
+
+export function createChat({ onHistory, onMessage, onPresence, onTyping } = {}) {
+  if (!window.io) throw new Error("Socket.io client not loaded — add <script src=\"/socket.io/socket.io.js\"></script>");
+  const socket = window.io();
+  if (onHistory) socket.on("chat:history", onHistory);
+  if (onMessage) socket.on("chat:message", onMessage);
+  if (onPresence) socket.on("chat:presence", onPresence);
+  if (onTyping) socket.on("chat:typing", onTyping);
+
+  return {
+    socket,
+    join: (room) => socket.emit("chat:join", { room }),
+    send: (room, body) => socket.emit("chat:message", { room, body }),
+    typing: (room) => socket.emit("chat:typing", { room }),
+  };
+}

package/addons/realtime/meta.json

@@ -0,0 +1,8 @@
+{
+  "description": "Socket.io live chat: rooms, presence (who's online), typing indicators. Persists messages via db; shows emails when auth is present.",
+  "dependsOn": ["db"],
+  "sentinel": "lib/realtime.js",
+  "install": ["socket.io"],
+  "optional": {},
+  "wiring": "import http from \"node:http\";\nimport { Server as SocketServer } from \"socket.io\";\nimport { createStore } from \"./lib/store.js\";\nimport { attachRealtime } from \"./lib/realtime.js\";\n\nconst server = http.createServer(app);   // wrap the Express app\nconst io = new SocketServer(server);\nattachRealtime(io, { store: await createStore() });\nserver.listen(PORT);                     // listen on `server`, not `app`\n\nIn the page: load /socket.io/socket.io.js, then in your module:\n  import { createChat } from \"/chat-client.js\";\n  const chat = createChat({ onMessage, onHistory, onPresence, onTyping });\n  chat.join(\"general\"); chat.send(\"general\", \"hi\");"
+}