create-volt 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# create-volt
+
+Scaffold a new [Volt](https://github.com/) app in one command — a tiny,
+**no-build**, signals-based UI with **Socket.io hot reload**. Think
+`create-react-app`, but the whole framework is one ~260-line file you can read.
+
+## Usage
+
+```bash
+npm create volt@latest my-app
+# or
+npx create-volt my-app
+# or with pnpm / yarn / bun
+pnpm create volt my-app
+yarn create volt my-app
+bun create volt my-app
+```
+
+Then:
+
+```bash
+cd my-app
+npm run dev        # → http://localhost:26628
+```
+
+Edit `public/app.js` and save — the page hot-reloads itself.
+
+## Options
+
+| Flag             | Effect                                                  |
+| ---------------- | ------------------------------------------------------- |
+| `--skip-install` | Don't run the install step (scaffold files only)        |
+| `--force`        | Scaffold into an existing non-empty directory           |
+| `-h`, `--help`   | Show help                                               |
+| `-v`, `--version`| Print the create-volt version                           |
+
+The installer auto-detects whichever package manager invoked it
+(npm / pnpm / yarn / bun) and uses it for `install`.
+
+## What you get
+
+```
+my-app/
+├── public/
+│   ├── volt.js       the Volt library (no build step)
+│   └── app.js        your app — Counter + Todos demo
+├── views/index.html  the HTML shell
+├── server.js         dev server (Express + Socket.io + file watcher)
+├── package.json
+└── .gitignore
+```
+
+## Requirements
+
+Node.js ≥ 16.7. Works on Linux, macOS and Windows.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+// create-volt — scaffold a new Volt app, à la create-react-app.
+//
+//   npm create volt@latest my-app
+//   npx create-volt my-app
+//   npm create volt@latest my-app -- --skip-install
+//
+// Cross-platform: pure node: APIs, path.join everywhere, recursive fs.cpSync,
+// and the install step shells out to whichever package manager invoked it.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const pkg = require("./package.json");
+
+// --- tiny ANSI helpers (no deps; degrade to plain text when not a TTY) ---
+const tty = process.stdout.isTTY;
+const c = (code) => (s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const bold = c(1), dim = c(2), cyan = c(36), green = c(32), red = c(31), yellow = c(33);
+
+function die(msg) {
+  console.error(`\n${red("✖")} ${msg}\n`);
+  process.exit(1);
+}
+
+const HELP = `
+${bold("⚡ create-volt")} — scaffold a new Volt app
+
+${bold("Usage")}
+  npm create volt@latest <project-directory> [options]
+  npx create-volt <project-directory> [options]
+
+${bold("Options")}
+  --skip-install   Don't run the package manager install step
+  --force          Scaffold into an existing non-empty directory
+  -h, --help       Show this help
+  -v, --version    Show the create-volt version
+
+${bold("Example")}
+  npm create volt@latest my-app
+  cd my-app && npm run dev
+`;
+
+// --- arg parsing ---
+const argv = process.argv.slice(2);
+const flags = new Set(argv.filter((a) => a.startsWith("-")));
+const positionals = argv.filter((a) => !a.startsWith("-"));
+
+if (flags.has("-h") || flags.has("--help")) {
+  console.log(HELP);
+  process.exit(0);
+}
+if (flags.has("-v") || flags.has("--version")) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const skipInstall = flags.has("--skip-install");
+const force = flags.has("--force");
+
+const rawName = positionals[0];
+if (!rawName) die(`Please specify a project directory:\n    ${cyan("npm create volt@latest")} ${green("<project-directory>")}`);
+
+// Validate: a single path segment, npm-name-ish, no traversal.
+const projectName = rawName.replace(/\/+$/, "");
+if (projectName.includes("..") || /[<>:"|?*\x00-\x1f]/.test(projectName)) {
+  die(`Invalid project name: ${green(rawName)}`);
+}
+if (!/^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(path.basename(projectName))) {
+  die(`"${path.basename(projectName)}" is not a valid npm package name. Use lowercase letters, digits and dashes.`);
+}
+
+const targetDir = path.resolve(process.cwd(), projectName);
+const appName = path.basename(targetDir);
+const templateDir = path.join(__dirname, "template");
+
+// --- target directory checks ---
+if (fs.existsSync(targetDir)) {
+  const existing = fs.readdirSync(targetDir).filter((f) => f !== ".git");
+  if (existing.length && !force) {
+    die(`Directory ${green(projectName)} already exists and is not empty.\n  Pass ${cyan("--force")} to scaffold into it anyway.`);
+  }
+} else {
+  fs.mkdirSync(targetDir, { recursive: true });
+}
+
+console.log(`\n${bold("⚡ Creating a new Volt app in")} ${cyan(targetDir)}\n`);
+
+// --- copy the template tree (recursive, cross-platform) ---
+fs.cpSync(templateDir, targetDir, { recursive: true });
+
+// npm strips a real ".gitignore" from published packages, so the template ships
+// it as "gitignore" — rename it back in the generated project.
+const shippedGitignore = path.join(targetDir, "gitignore");
+if (fs.existsSync(shippedGitignore)) {
+  fs.renameSync(shippedGitignore, path.join(targetDir, ".gitignore"));
+}
+
+// --- stamp the project name into package.json ---
+const appPkgPath = path.join(targetDir, "package.json");
+const appPkg = JSON.parse(fs.readFileSync(appPkgPath, "utf8"));
+appPkg.name = appName;
+fs.writeFileSync(appPkgPath, JSON.stringify(appPkg, null, 2) + "\n");
+
+const created = [
+  "public/volt.js   — the Volt library (no build step)",
+  "public/app.js    — your app (Counter + Todos demo)",
+  "views/index.html — the HTML shell",
+  "server.js        — dev server with hot reload",
+];
+console.log(green("✔") + " Files created:");
+for (const line of created) console.log("  " + dim(line));
+console.log("");
+
+// --- detect the package manager that invoked us (npm / pnpm / yarn / bun) ---
+function detectPM() {
+  const ua = process.env.npm_config_user_agent || "";
+  if (ua.startsWith("pnpm")) return "pnpm";
+  if (ua.startsWith("yarn")) return "yarn";
+  if (ua.startsWith("bun")) return "bun";
+  return "npm";
+}
+const pm = detectPM();
+
+// --- install dependencies (unless skipped) ---
+let installed = false;
+if (!skipInstall) {
+  console.log(`${bold("Installing dependencies with")} ${cyan(pm)}…\n`);
+  const res = spawnSync(pm, ["install"], {
+    cwd: targetDir,
+    stdio: "inherit",
+    shell: process.platform === "win32", // .cmd shims need a shell on Windows
+  });
+  if (res.status === 0) {
+    installed = true;
+  } else {
+    console.log(`\n${yellow("!")} ${pm} install did not complete — you can run it yourself below.`);
+  }
+}
+
+// --- next steps ---
+const runCmd = pm === "npm" ? "npm run dev" : `${pm} dev`;
+const installCmd = pm === "yarn" ? "yarn" : `${pm} install`;
+console.log(`\n${green("✔")} ${bold("Done!")} Next steps:\n`);
+console.log(`  ${cyan("cd")} ${projectName}`);
+if (!installed) console.log(`  ${cyan(installCmd)}`);
+console.log(`  ${cyan(runCmd)}`);
+console.log(`\nThen open ${cyan("http://localhost:26628")} and edit ${bold("public/app.js")}.\n`);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "create-volt",
+  "version": "0.1.0",
+  "description": "Scaffold a new Volt app — no-build, signals-based UI with Socket.io hot reload.",
+  "type": "module",
+  "bin": {
+    "create-volt": "index.js"
+  },
+  "files": [
+    "index.js",
+    "template"
+  ],
+  "engines": {
+    "node": ">=16.7.0"
+  },
+  "author": "Richard Whitney",
+  "homepage": "https://github.com/MIR-2025/volt#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MIR-2025/volt.git",
+    "directory": "packages/create-volt"
+  },
+  "bugs": {
+    "url": "https://github.com/MIR-2025/volt/issues"
+  },
+  "keywords": [
+    "volt",
+    "create-volt",
+    "scaffold",
+    "signals",
+    "no-build",
+    "hot-reload",
+    "ui"
+  ],
+  "license": "MIT"
+}

package/template/README.md

@@ -0,0 +1,41 @@
+# ⚡ Volt app
+
+A tiny, **no-build**, signals-based UI app with **Socket.io hot reload**.
+Not React: no JSX, no virtual DOM, no re-render-the-world. State lives in
+*signals*; only the exact text/attribute that changed updates.
+
+## Run
+
+```bash
+npm install        # if you scaffolded with --skip-install
+npm run dev        # → http://localhost:26628   (PORT env to override)
+```
+
+Edit anything in `public/` or `views/` and save — the dev server pushes a
+reload over Socket.io and the page refreshes itself.
+
+## Project layout
+
+```
+public/volt.js     the Volt library (a single ~260-line file, no build step)
+public/app.js      your app — the Counter + Todos demo to start from
+views/index.html   the HTML shell (loads socket.io then app.js as a module)
+server.js          the dev server (Express + Socket.io + file watcher)
+```
+
+## API
+
+```js
+import { signal, computed, effect, el, html, mount } from "/volt.js";
+```
+
+- **`signal(initial)`** → a getter/setter function. `n()` reads, `n(next)` writes.
+- **`computed(fn)`** → read-only derived signal, auto-updating.
+- **`effect(fn)`** → runs `fn`, re-runs when any signal it read changes. Returns a disposer.
+- **`el(tag, props?, ...children)`** → a DOM element. `onClick` = listener; a function
+  prop = reactive attribute; a function child = live region.
+- **``html`...` ``** → tagged-template markup. `${signal}` holes update in place;
+  `onclick=${fn}` = listener; `value=${signal}` = reactive attribute.
+- **`mount(target, ...children)`** → append children into a selector/element.
+
+Scaffolded with [`create-volt`](https://www.npmjs.com/package/create-volt).

package/template/gitignore

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

package/template/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/template/public/app.js

@@ -0,0 +1,66 @@
+// app.js — demo app. Shows BOTH authoring styles on one shared signal engine,
+// with live hot reload. Edit anything here (or in index.html) and save: the
+// dev server pushes a reload over Socket.io and the page refreshes.
+
+import { signal, computed, el, html, mount } from "/volt.js";
+
+// --- Counter, written with el() helpers (imperative, zero template parsing) ---
+function Counter() {
+  const n = signal(0);
+  return el("div", { class: "card-x p-4 mb-4" },
+    el("h2", { class: "h5 mb-3" }, "Counter — built with el()"),
+    el("div", { class: "d-flex align-items-center gap-3" },
+      el("button", { class: "btn btn-outline-secondary", onClick: () => n(n() - 1) }, "−"),
+      el("span", { class: "fs-4 fw-bold", style: "min-width:3ch;text-align:center" },
+        () => String(n())), // function-child: only this text node updates
+      el("button", { class: "btn btn-primary", onClick: () => n(n() + 1) }, "+"),
+      el("span", { class: "text-muted ms-2" },
+        () => (n() % 2 === 0 ? "even" : "odd")),
+    ),
+  );
+}
+
+// --- Todo list, written with html`` templates (markup-first) ---
+function Todos() {
+  const items = signal([]); // [{ id, text, done }]
+  const draft = signal("");
+  const remaining = computed(() => items().filter((t) => !t.done).length);
+
+  const add = () => {
+    const text = draft().trim();
+    if (!text) return;
+    items([...items(), { id: Date.now() + Math.random(), text, done: false }]);
+    draft("");
+  };
+  const toggle = (id) =>
+    items(items().map((t) => (t.id === id ? { ...t, done: !t.done } : t)));
+  const remove = (id) => items(items().filter((t) => t.id !== id));
+
+  const row = (t) => html`
+    <li class="list-group-item d-flex align-items-center gap-2">
+      <input class="form-check-input mt-0" type="checkbox"
+             checked=${t.done} onchange=${() => toggle(t.id)} />
+      <span class=${() => "flex-grow-1 " + (t.done ? "text-decoration-line-through text-muted" : "")}>
+        ${t.text}
+      </span>
+      <button class="btn btn-sm btn-outline-danger" onclick=${() => remove(t.id)}>✕</button>
+    </li>`;
+
+  return html`
+    <div class="card-x p-4">
+      <h2 class="h5 mb-3">Todos — built with html\`\`</h2>
+      <div class="input-group mb-3">
+        <input class="form-control" placeholder="Add a task…"
+               value=${draft}
+               oninput=${(e) => draft(e.target.value)}
+               onkeydown=${(e) => e.key === "Enter" && add()} />
+        <button class="btn btn-primary" onclick=${add}>Add</button>
+      </div>
+      <ul class="list-group mb-2">
+        ${() => items().map(row)}
+      </ul>
+      <small class="text-muted">${remaining} remaining</small>
+    </div>`;
+}
+
+mount("#app", Counter(), Todos());

package/template/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/template/server.js

@@ -0,0 +1,64 @@
+// server.js — minimal dev server for a Volt app. Express serves the static
+// client and the index view; Socket.io carries the hot-reload signal; a file
+// watcher on views/ and public/ broadcasts a (debounced) reload on any save.
+//
+// Cross-platform: paths are resolved relative to this file, and the watcher
+// falls back to a manual recursive walk where native recursive fs.watch is
+// unavailable (older Linux Node builds).
+//
+//   npm run dev            # start the dev server
+//   PORT=4000 npm run dev  # override the port
+
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import express from "express";
+import { Server as SocketServer } from "socket.io";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PORT = Number(process.env.PORT) || 26628;
+
+const app = express();
+app.use(express.static(path.join(__dirname, "public")));
+app.get("/", (_req, res) => res.sendFile(path.join(__dirname, "views", "index.html")));
+
+const server = http.createServer(app);
+const io = new SocketServer(server);
+
+// --- Hot reload: watch views/ + public/, debounce bursts, broadcast a reload ---
+const watchDirs = ["views", "public"].map((d) => path.join(__dirname, d));
+let timer = null;
+function onChange(file) {
+  clearTimeout(timer);
+  timer = setTimeout(() => {
+    console.log(`[volt] change: ${file ?? "?"} → reload`);
+    io.emit("volt:reload");
+  }, 80);
+}
+
+// Watch a directory recursively. Tries native recursive fs.watch first; if the
+// platform/runtime doesn't support it, walks the tree and watches each dir.
+function watchRecursive(dir) {
+  try {
+    fs.watch(dir, { recursive: true }, (_event, file) => onChange(file));
+    return;
+  } catch {
+    // Native recursive watch unsupported — fall back to per-directory watchers.
+  }
+  const watchDir = (d) => {
+    try {
+      fs.watch(d, (_event, file) => onChange(file));
+    } catch {
+      /* directory vanished between walk and watch — ignore */
+    }
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      if (entry.isDirectory()) watchDir(path.join(d, entry.name));
+    }
+  };
+  watchDir(dir);
+}
+
+for (const dir of watchDirs) watchRecursive(dir);
+
+server.listen(PORT, () => console.log(`⚡ Volt dev server → http://localhost:${PORT}`));

package/template/views/index.html

@@ -0,0 +1,40 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Volt — signals, no build, hot reload</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, .input-group-text { background: #0f1115; color: #e7e9ee; border-color: #232a36; }
+    .form-control:focus { background: #0f1115; color: #e7e9ee; border-color: #ffd24a; box-shadow: none; }
+    .list-group-item { background: #0f1115; color: #e7e9ee; border-color: #232a36; }
+    a { color: #ffd24a; }
+  </style>
+</head>
+<body>
+  <main class="container py-5" style="max-width: 720px;">
+    <header class="text-center mb-5">
+      <h1 class="brand display-5"><span class="accent">⚡ Volt</span></h1>
+      <p class="text-muted mb-0">
+        Fine-grained signals · no JSX · no virtual DOM · live hot reload.
+        Edit <code>public/app.js</code> and save — this page reloads itself.
+      </p>
+    </header>
+
+    <div id="app"></div>
+
+    <footer class="text-center text-muted mt-5">
+      <small>Both cards run on the same signal engine — one uses <code>el()</code>, the other <code>html``</code>.</small>
+    </footer>
+  </main>
+
+  <!-- Socket.io client (auto-served by the dev server) powers hot reload. -->
+  <script src="/socket.io/socket.io.js"></script>
+  <script type="module" src="/app.js"></script>
+</body>
+</html>