create-volt 0.37.0 → 0.38.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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.38.0] - 2026-06-29
+
+### Added
+- **Smart hot reload (live DOM morph).** Editing markdown / HTML / templates now
+  patches only the changed DOM nodes instead of a full page reload — focus, caret,
+  scroll, and untouched subtrees survive. CSS edits swap the stylesheet in place;
+  JS edits (and client-rendered `#app` pages) still do a full reload, and any morph
+  error falls back to one. The watcher tells the client which file changed.
+- **Themes hot-reload in dev.** Editing `_theme.js` / `_theme.css` / a bundled
+  theme now reflects immediately — theme imports are mtime cache-busted in dev
+  (previously a restart was needed). Pages + posts share the live resolver
+  (`themeResolver`).
+
 ## [0.37.0] - 2026-06-29
 
 ### Added
@@ -495,6 +508,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.38.0]: https://github.com/MIR-2025/volt/releases/tag/v0.38.0
 [0.37.0]: https://github.com/MIR-2025/volt/releases/tag/v0.37.0
 [0.36.0]: https://github.com/MIR-2025/volt/releases/tag/v0.36.0
 [0.35.0]: https://github.com/MIR-2025/volt/releases/tag/v0.35.0

package/addons/pages/files/lib/pages.js

@@ -123,6 +123,11 @@ function themeCss(dir) {
 // local pages/_theme.js; else the built-in default. A theme may `export const css`
 // (served at /_theme.css, shared with the editor); otherwise pages/_theme.css or
 // the default CSS is used.
+const DEV = process.env.NODE_ENV !== "production";
+// In dev, cache-bust theme imports by mtime so editing _theme.js shows up without
+// a restart (ESM caches a given URL forever); unchanged files keep the same URL.
+const freshUrl = (f) => pathToFileURL(f).href + (DEV ? "?t=" + fs.statSync(f).mtimeMs : "");
+
 export async function loadTheme(dir, env) {
   const wrap = (m) => {
     const layout = m && (m.layout || m.default);
@@ -132,7 +137,7 @@ export async function loadTheme(dir, env) {
     // a theme bundled by create-volt (.volt/themes/<name>/index.js) — no npm needed
     const bundled = path.resolve(dir, "..", ".volt", "themes", env.THEME, "index.js");
     if (fs.existsSync(bundled)) {
-      const t = wrap(await import(pathToFileURL(bundled).href));
+      const t = wrap(await import(freshUrl(bundled)));
       if (t) return t;
     }
     for (const id of [`volt-theme-${env.THEME}`, env.THEME]) {
@@ -146,20 +151,27 @@ export async function loadTheme(dir, env) {
   }
   const local = path.join(dir, "_theme.js");
   if (fs.existsSync(local)) {
-    const t = wrap(await import(pathToFileURL(local).href));
+    const t = wrap(await import(freshUrl(local)));
     if (t) return t;
   }
   return { layout: defaultLayout(dir), css: themeCss(dir) };
 }
 
+// A theme getter that caches in production but re-resolves every call in dev, so
+// theme edits hot-reload. Shared by pages + posts so they render the same theme.
+export function themeResolver(dir) {
+  let cached = null;
+  return async () => (cached && !DEV ? cached : (cached = await loadTheme(dir, process.env)));
+}
+
 export async function pagesRouter({ dir }) {
   const express = (await import("express")).default;
   const { marked } = await import("marked");
   ensure(dir);
-  const { layout, css } = await loadTheme(dir, process.env);
+  const getTheme = themeResolver(dir);
   const r = express.Router();
-  r.get("/_theme.css", (_req, res) => res.type("css").send(css));
-  r.get("/:slug", (req, res, next) => {
+  r.get("/_theme.css", async (_req, res) => res.type("css").send((await getTheme()).css));
+  r.get("/:slug", async (req, res, next) => {
     const slug = req.params.slug;
     if (!isSafeSlug(slug)) return next(); // safe slug only — no traversal
     const file = path.join(dir, slug + ".md");
@@ -169,6 +181,7 @@ export async function pagesRouter({ dir }) {
     // preserve complex layouts; everything else is markdown rendered with marked.
     const content = meta.format === "html" ? body : marked.parse(body);
     const m = { ...meta, title: meta.title || slug };
+    const { layout } = await getTheme();
     res.type("html").send(layout({ title: m.title, head: metaHead(m), content, meta: m }));
   });
   return r;

package/addons/posts/files/lib/posts.js

@@ -6,7 +6,7 @@ import fs from "node:fs";
 import path from "node:path";
 // express + marked are imported lazily in postsRouter() so the pure helpers load
 // without those deps. Theme + SEO come from the pages add-on (a dependency).
-import { parseFrontMatter, isSafeSlug, metaHead, loadTheme } from "../../../pages/files/lib/pages.js";
+import { parseFrontMatter, isSafeSlug, metaHead, themeResolver } from "../../../pages/files/lib/pages.js";
 
 const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
 const slugify = (s) => String(s).toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -115,24 +115,25 @@ export async function postsRouter({ dir, themeDir }) {
   const express = (await import("express")).default;
   const { marked } = await import("marked");
   fs.mkdirSync(dir, { recursive: true });
-  const { layout } = await loadTheme(themeDir || dir, process.env); // same theme as pages
+  const getTheme = themeResolver(themeDir || dir); // same theme as pages (live in dev)
   const PER = Math.max(1, Number(process.env.POSTS_PER_PAGE) || 10);
-  const render = ({ title, content, meta = {} }) => {
+  const render = async ({ title, content, meta = {} }) => {
     const m = { ...meta, title };
+    const { layout } = await getTheme();
     return layout({ title, head: metaHead(m), content, meta: m });
   };
   const r = express.Router();
 
-  r.get("/blog", (req, res) => {
+  r.get("/blog", async (req, res) => {
     const all = readPosts(dir);
     const page = Math.max(1, parseInt(req.query.page, 10) || 1);
     const totalPages = Math.max(1, Math.ceil(all.length / PER));
     const slice = all.slice((page - 1) * PER, page * PER);
     const heading = process.env.SITE_NAME || "Blog";
-    res.type("html").send(render({ title: heading, meta: { description: heading + " — latest posts" }, content: renderList(slice, { heading, page, totalPages, baseUrl: "/blog" }) }));
+    res.type("html").send(await render({ title: heading, meta: { description: heading + " — latest posts" }, content: renderList(slice, { heading, page, totalPages, baseUrl: "/blog" }) }));
   });
 
-  r.get("/blog/:slug", (req, res, next) => {
+  r.get("/blog/:slug", async (req, res, next) => {
     if (!isSafeSlug(req.params.slug)) return next();
     const post = readPosts(dir).find((p) => p.slug === req.params.slug);
     if (!post) return next();
@@ -145,7 +146,7 @@ export async function postsRouter({ dir, themeDir }) {
       ...(post.meta.author ? { author: { "@type": "Person", name: post.meta.author } } : {}),
     });
     res.type("html").send(
-      render({
+      await render({
         title,
         meta: { ...post.meta, title, type: "article", jsonld: post.meta.jsonld || autoLd },
         content: renderPost(post, marked),
@@ -153,18 +154,18 @@ export async function postsRouter({ dir, themeDir }) {
     );
   });
 
-  r.get("/category/:name", (req, res, next) => {
+  r.get("/category/:name", async (req, res, next) => {
     if (!isSafeSlug(req.params.name)) return next();
     const list = readPosts(dir).filter((p) => slugify(p.meta.category) === req.params.name);
     if (!list.length) return next();
-    res.type("html").send(render({ title: "Category: " + req.params.name, content: renderList(list, { heading: "Category: " + req.params.name, baseUrl: "/category/" + req.params.name }) }));
+    res.type("html").send(await render({ title: "Category: " + req.params.name, content: renderList(list, { heading: "Category: " + req.params.name, baseUrl: "/category/" + req.params.name }) }));
   });
 
-  r.get("/tag/:name", (req, res, next) => {
+  r.get("/tag/:name", async (req, res, next) => {
     if (!isSafeSlug(req.params.name)) return next();
     const list = readPosts(dir).filter((p) => tagsOf(p.meta).some((t) => slugify(t) === req.params.name));
     if (!list.length) return next();
-    res.type("html").send(render({ title: "Tag: " + req.params.name, content: renderList(list, { heading: "Tag: " + req.params.name, baseUrl: "/tag/" + req.params.name }) }));
+    res.type("html").send(await render({ title: "Tag: " + req.params.name, content: renderList(list, { heading: "Tag: " + req.params.name, baseUrl: "/tag/" + req.params.name }) }));
   });
 
   r.get("/feed.xml", (_req, res) => {

package/package.json

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

package/templates/blog/public/volt.js

@@ -262,11 +262,88 @@ function bindNodeHole(comment, value) {
 
 (function startHotReload() {
   if (typeof window === "undefined") return; // not a browser (SSR / Node imports / tests)
+
+  // Patch `from` to match `to` in place — only changed nodes are touched, so
+  // focus, caret, scroll, and untouched subtrees survive. Positional (no keys),
+  // which is plenty for a dev reload; the caller falls back to a full reload if
+  // anything throws.
+  const morph = (from, to) => {
+    const active = document.activeElement;
+    if (from.nodeType !== to.nodeType || from.nodeName !== to.nodeName) {
+      from.replaceWith(document.importNode(to, true));
+      return;
+    }
+    if (from.nodeType === 3 || from.nodeType === 8) {
+      if (from.nodeValue !== to.nodeValue) from.nodeValue = to.nodeValue;
+      return;
+    }
+    if (from.nodeType !== 1) return;
+    for (const a of [...to.attributes]) {
+      if (from === active && a.name === "value") continue; // don't fight the typist
+      if (from.getAttribute(a.name) !== a.value) from.setAttribute(a.name, a.value);
+    }
+    for (const a of [...from.attributes]) if (!to.hasAttribute(a.name)) from.removeAttribute(a.name);
+    let f = from.firstChild,
+      t = to.firstChild;
+    while (f && t) {
+      const nf = f.nextSibling,
+        nt = t.nextSibling;
+      morph(f, t);
+      f = nf;
+      t = nt;
+    }
+    while (f) {
+      const nf = f.nextSibling;
+      from.removeChild(f);
+      f = nf;
+    }
+    while (t) {
+      const nt = t.nextSibling;
+      from.appendChild(document.importNode(t, true));
+      t = nt;
+    }
+  };
+
+  const bustStyles = () => {
+    for (const link of document.querySelectorAll('link[rel="stylesheet"]')) {
+      const u = new URL(link.getAttribute("href"), location.href);
+      u.searchParams.set("_hr", Date.now());
+      link.setAttribute("href", u.pathname + u.search);
+    }
+  };
+
+  let busy = false;
+  const onChange = async (info) => {
+    const file = (info && info.file) || "";
+    if (/\.css(\?|$)/i.test(file)) return bustStyles(); // pure CSS → swap, no reload
+    if (/\.(js|mjs)(\?|$)/i.test(file)) return location.reload(); // JS changed → must re-run
+    if (busy) return;
+    busy = true;
+    try {
+      const html = await (await fetch(location.href, { headers: { "x-volt-hot": "1" } })).text();
+      const doc = new DOMParser().parseFromString(html, "text/html");
+      // a client-rendered app (#app filled by JS, empty in server HTML) can't be
+      // morphed without wiping it — full reload instead.
+      const cur = document.querySelector("#app");
+      const next = doc.querySelector("#app");
+      if (cur && cur.children.length && next && !next.children.length) {
+        location.reload();
+        return;
+      }
+      morph(document.body, doc.body);
+      if (document.title !== doc.title) document.title = doc.title;
+      if (/_theme/.test(file)) bustStyles(); // theme/layout edit may change CSS too
+    } catch {
+      location.reload();
+    } finally {
+      busy = false;
+    }
+  };
+
   const connect = () => {
     if (!window.io) return false;
-    const socket = window.io();
-    socket.on("volt:reload", () => location.reload());
-    console.log("[volt] hot reload connected");
+    window.io().on("volt:reload", onChange);
+    console.log("[volt] hot reload connected (live morph)");
     return true;
   };
   if (!connect()) window.addEventListener("load", connect);

package/templates/blog/server.js

@@ -205,7 +205,7 @@ async function startApp() {
     clearTimeout(timer);
     timer = setTimeout(() => {
       console.log(`[volt] change: ${file ?? "?"} → reload`);
-      io.emit("volt:reload");
+      io.emit("volt:reload", { file });
     }, 80);
   };
   const watchRecursive = (dir) => {

package/templates/default/public/volt.js

@@ -262,11 +262,88 @@ function bindNodeHole(comment, value) {
 
 (function startHotReload() {
   if (typeof window === "undefined") return; // not a browser (SSR / Node imports / tests)
+
+  // Patch `from` to match `to` in place — only changed nodes are touched, so
+  // focus, caret, scroll, and untouched subtrees survive. Positional (no keys),
+  // which is plenty for a dev reload; the caller falls back to a full reload if
+  // anything throws.
+  const morph = (from, to) => {
+    const active = document.activeElement;
+    if (from.nodeType !== to.nodeType || from.nodeName !== to.nodeName) {
+      from.replaceWith(document.importNode(to, true));
+      return;
+    }
+    if (from.nodeType === 3 || from.nodeType === 8) {
+      if (from.nodeValue !== to.nodeValue) from.nodeValue = to.nodeValue;
+      return;
+    }
+    if (from.nodeType !== 1) return;
+    for (const a of [...to.attributes]) {
+      if (from === active && a.name === "value") continue; // don't fight the typist
+      if (from.getAttribute(a.name) !== a.value) from.setAttribute(a.name, a.value);
+    }
+    for (const a of [...from.attributes]) if (!to.hasAttribute(a.name)) from.removeAttribute(a.name);
+    let f = from.firstChild,
+      t = to.firstChild;
+    while (f && t) {
+      const nf = f.nextSibling,
+        nt = t.nextSibling;
+      morph(f, t);
+      f = nf;
+      t = nt;
+    }
+    while (f) {
+      const nf = f.nextSibling;
+      from.removeChild(f);
+      f = nf;
+    }
+    while (t) {
+      const nt = t.nextSibling;
+      from.appendChild(document.importNode(t, true));
+      t = nt;
+    }
+  };
+
+  const bustStyles = () => {
+    for (const link of document.querySelectorAll('link[rel="stylesheet"]')) {
+      const u = new URL(link.getAttribute("href"), location.href);
+      u.searchParams.set("_hr", Date.now());
+      link.setAttribute("href", u.pathname + u.search);
+    }
+  };
+
+  let busy = false;
+  const onChange = async (info) => {
+    const file = (info && info.file) || "";
+    if (/\.css(\?|$)/i.test(file)) return bustStyles(); // pure CSS → swap, no reload
+    if (/\.(js|mjs)(\?|$)/i.test(file)) return location.reload(); // JS changed → must re-run
+    if (busy) return;
+    busy = true;
+    try {
+      const html = await (await fetch(location.href, { headers: { "x-volt-hot": "1" } })).text();
+      const doc = new DOMParser().parseFromString(html, "text/html");
+      // a client-rendered app (#app filled by JS, empty in server HTML) can't be
+      // morphed without wiping it — full reload instead.
+      const cur = document.querySelector("#app");
+      const next = doc.querySelector("#app");
+      if (cur && cur.children.length && next && !next.children.length) {
+        location.reload();
+        return;
+      }
+      morph(document.body, doc.body);
+      if (document.title !== doc.title) document.title = doc.title;
+      if (/_theme/.test(file)) bustStyles(); // theme/layout edit may change CSS too
+    } catch {
+      location.reload();
+    } finally {
+      busy = false;
+    }
+  };
+
   const connect = () => {
     if (!window.io) return false;
-    const socket = window.io();
-    socket.on("volt:reload", () => location.reload());
-    console.log("[volt] hot reload connected");
+    window.io().on("volt:reload", onChange);
+    console.log("[volt] hot reload connected (live morph)");
     return true;
   };
   if (!connect()) window.addEventListener("load", connect);

package/templates/default/server.js

@@ -205,7 +205,7 @@ async function startApp() {
     clearTimeout(timer);
     timer = setTimeout(() => {
       console.log(`[volt] change: ${file ?? "?"} → reload`);
-      io.emit("volt:reload");
+      io.emit("volt:reload", { file });
     }, 80);
   };
   const watchRecursive = (dir) => {

package/templates/docs/public/volt.js

@@ -262,11 +262,88 @@ function bindNodeHole(comment, value) {
 
 (function startHotReload() {
   if (typeof window === "undefined") return; // not a browser (SSR / Node imports / tests)
+
+  // Patch `from` to match `to` in place — only changed nodes are touched, so
+  // focus, caret, scroll, and untouched subtrees survive. Positional (no keys),
+  // which is plenty for a dev reload; the caller falls back to a full reload if
+  // anything throws.
+  const morph = (from, to) => {
+    const active = document.activeElement;
+    if (from.nodeType !== to.nodeType || from.nodeName !== to.nodeName) {
+      from.replaceWith(document.importNode(to, true));
+      return;
+    }
+    if (from.nodeType === 3 || from.nodeType === 8) {
+      if (from.nodeValue !== to.nodeValue) from.nodeValue = to.nodeValue;
+      return;
+    }
+    if (from.nodeType !== 1) return;
+    for (const a of [...to.attributes]) {
+      if (from === active && a.name === "value") continue; // don't fight the typist
+      if (from.getAttribute(a.name) !== a.value) from.setAttribute(a.name, a.value);
+    }
+    for (const a of [...from.attributes]) if (!to.hasAttribute(a.name)) from.removeAttribute(a.name);
+    let f = from.firstChild,
+      t = to.firstChild;
+    while (f && t) {
+      const nf = f.nextSibling,
+        nt = t.nextSibling;
+      morph(f, t);
+      f = nf;
+      t = nt;
+    }
+    while (f) {
+      const nf = f.nextSibling;
+      from.removeChild(f);
+      f = nf;
+    }
+    while (t) {
+      const nt = t.nextSibling;
+      from.appendChild(document.importNode(t, true));
+      t = nt;
+    }
+  };
+
+  const bustStyles = () => {
+    for (const link of document.querySelectorAll('link[rel="stylesheet"]')) {
+      const u = new URL(link.getAttribute("href"), location.href);
+      u.searchParams.set("_hr", Date.now());
+      link.setAttribute("href", u.pathname + u.search);
+    }
+  };
+
+  let busy = false;
+  const onChange = async (info) => {
+    const file = (info && info.file) || "";
+    if (/\.css(\?|$)/i.test(file)) return bustStyles(); // pure CSS → swap, no reload
+    if (/\.(js|mjs)(\?|$)/i.test(file)) return location.reload(); // JS changed → must re-run
+    if (busy) return;
+    busy = true;
+    try {
+      const html = await (await fetch(location.href, { headers: { "x-volt-hot": "1" } })).text();
+      const doc = new DOMParser().parseFromString(html, "text/html");
+      // a client-rendered app (#app filled by JS, empty in server HTML) can't be
+      // morphed without wiping it — full reload instead.
+      const cur = document.querySelector("#app");
+      const next = doc.querySelector("#app");
+      if (cur && cur.children.length && next && !next.children.length) {
+        location.reload();
+        return;
+      }
+      morph(document.body, doc.body);
+      if (document.title !== doc.title) document.title = doc.title;
+      if (/_theme/.test(file)) bustStyles(); // theme/layout edit may change CSS too
+    } catch {
+      location.reload();
+    } finally {
+      busy = false;
+    }
+  };
+
   const connect = () => {
     if (!window.io) return false;
-    const socket = window.io();
-    socket.on("volt:reload", () => location.reload());
-    console.log("[volt] hot reload connected");
+    window.io().on("volt:reload", onChange);
+    console.log("[volt] hot reload connected (live morph)");
     return true;
   };
   if (!connect()) window.addEventListener("load", connect);

package/templates/docs/server.js

@@ -205,7 +205,7 @@ async function startApp() {
     clearTimeout(timer);
     timer = setTimeout(() => {
       console.log(`[volt] change: ${file ?? "?"} → reload`);
-      io.emit("volt:reload");
+      io.emit("volt:reload", { file });
     }, 80);
   };
   const watchRecursive = (dir) => {

package/templates/guestbook/public/volt.js

@@ -262,11 +262,88 @@ function bindNodeHole(comment, value) {
 
 (function startHotReload() {
   if (typeof window === "undefined") return; // not a browser (SSR / Node imports / tests)
+
+  // Patch `from` to match `to` in place — only changed nodes are touched, so
+  // focus, caret, scroll, and untouched subtrees survive. Positional (no keys),
+  // which is plenty for a dev reload; the caller falls back to a full reload if
+  // anything throws.
+  const morph = (from, to) => {
+    const active = document.activeElement;
+    if (from.nodeType !== to.nodeType || from.nodeName !== to.nodeName) {
+      from.replaceWith(document.importNode(to, true));
+      return;
+    }
+    if (from.nodeType === 3 || from.nodeType === 8) {
+      if (from.nodeValue !== to.nodeValue) from.nodeValue = to.nodeValue;
+      return;
+    }
+    if (from.nodeType !== 1) return;
+    for (const a of [...to.attributes]) {
+      if (from === active && a.name === "value") continue; // don't fight the typist
+      if (from.getAttribute(a.name) !== a.value) from.setAttribute(a.name, a.value);
+    }
+    for (const a of [...from.attributes]) if (!to.hasAttribute(a.name)) from.removeAttribute(a.name);
+    let f = from.firstChild,
+      t = to.firstChild;
+    while (f && t) {
+      const nf = f.nextSibling,
+        nt = t.nextSibling;
+      morph(f, t);
+      f = nf;
+      t = nt;
+    }
+    while (f) {
+      const nf = f.nextSibling;
+      from.removeChild(f);
+      f = nf;
+    }
+    while (t) {
+      const nt = t.nextSibling;
+      from.appendChild(document.importNode(t, true));
+      t = nt;
+    }
+  };
+
+  const bustStyles = () => {
+    for (const link of document.querySelectorAll('link[rel="stylesheet"]')) {
+      const u = new URL(link.getAttribute("href"), location.href);
+      u.searchParams.set("_hr", Date.now());
+      link.setAttribute("href", u.pathname + u.search);
+    }
+  };
+
+  let busy = false;
+  const onChange = async (info) => {
+    const file = (info && info.file) || "";
+    if (/\.css(\?|$)/i.test(file)) return bustStyles(); // pure CSS → swap, no reload
+    if (/\.(js|mjs)(\?|$)/i.test(file)) return location.reload(); // JS changed → must re-run
+    if (busy) return;
+    busy = true;
+    try {
+      const html = await (await fetch(location.href, { headers: { "x-volt-hot": "1" } })).text();
+      const doc = new DOMParser().parseFromString(html, "text/html");
+      // a client-rendered app (#app filled by JS, empty in server HTML) can't be
+      // morphed without wiping it — full reload instead.
+      const cur = document.querySelector("#app");
+      const next = doc.querySelector("#app");
+      if (cur && cur.children.length && next && !next.children.length) {
+        location.reload();
+        return;
+      }
+      morph(document.body, doc.body);
+      if (document.title !== doc.title) document.title = doc.title;
+      if (/_theme/.test(file)) bustStyles(); // theme/layout edit may change CSS too
+    } catch {
+      location.reload();
+    } finally {
+      busy = false;
+    }
+  };
+
   const connect = () => {
     if (!window.io) return false;
-    const socket = window.io();
-    socket.on("volt:reload", () => location.reload());
-    console.log("[volt] hot reload connected");
+    window.io().on("volt:reload", onChange);
+    console.log("[volt] hot reload connected (live morph)");
     return true;
   };
   if (!connect()) window.addEventListener("load", connect);

package/templates/starter/public/volt.js

@@ -262,11 +262,88 @@ function bindNodeHole(comment, value) {
 
 (function startHotReload() {
   if (typeof window === "undefined") return; // not a browser (SSR / Node imports / tests)
+
+  // Patch `from` to match `to` in place — only changed nodes are touched, so
+  // focus, caret, scroll, and untouched subtrees survive. Positional (no keys),
+  // which is plenty for a dev reload; the caller falls back to a full reload if
+  // anything throws.
+  const morph = (from, to) => {
+    const active = document.activeElement;
+    if (from.nodeType !== to.nodeType || from.nodeName !== to.nodeName) {
+      from.replaceWith(document.importNode(to, true));
+      return;
+    }
+    if (from.nodeType === 3 || from.nodeType === 8) {
+      if (from.nodeValue !== to.nodeValue) from.nodeValue = to.nodeValue;
+      return;
+    }
+    if (from.nodeType !== 1) return;
+    for (const a of [...to.attributes]) {
+      if (from === active && a.name === "value") continue; // don't fight the typist
+      if (from.getAttribute(a.name) !== a.value) from.setAttribute(a.name, a.value);
+    }
+    for (const a of [...from.attributes]) if (!to.hasAttribute(a.name)) from.removeAttribute(a.name);
+    let f = from.firstChild,
+      t = to.firstChild;
+    while (f && t) {
+      const nf = f.nextSibling,
+        nt = t.nextSibling;
+      morph(f, t);
+      f = nf;
+      t = nt;
+    }
+    while (f) {
+      const nf = f.nextSibling;
+      from.removeChild(f);
+      f = nf;
+    }
+    while (t) {
+      const nt = t.nextSibling;
+      from.appendChild(document.importNode(t, true));
+      t = nt;
+    }
+  };
+
+  const bustStyles = () => {
+    for (const link of document.querySelectorAll('link[rel="stylesheet"]')) {
+      const u = new URL(link.getAttribute("href"), location.href);
+      u.searchParams.set("_hr", Date.now());
+      link.setAttribute("href", u.pathname + u.search);
+    }
+  };
+
+  let busy = false;
+  const onChange = async (info) => {
+    const file = (info && info.file) || "";
+    if (/\.css(\?|$)/i.test(file)) return bustStyles(); // pure CSS → swap, no reload
+    if (/\.(js|mjs)(\?|$)/i.test(file)) return location.reload(); // JS changed → must re-run
+    if (busy) return;
+    busy = true;
+    try {
+      const html = await (await fetch(location.href, { headers: { "x-volt-hot": "1" } })).text();
+      const doc = new DOMParser().parseFromString(html, "text/html");
+      // a client-rendered app (#app filled by JS, empty in server HTML) can't be
+      // morphed without wiping it — full reload instead.
+      const cur = document.querySelector("#app");
+      const next = doc.querySelector("#app");
+      if (cur && cur.children.length && next && !next.children.length) {
+        location.reload();
+        return;
+      }
+      morph(document.body, doc.body);
+      if (document.title !== doc.title) document.title = doc.title;
+      if (/_theme/.test(file)) bustStyles(); // theme/layout edit may change CSS too
+    } catch {
+      location.reload();
+    } finally {
+      busy = false;
+    }
+  };
+
   const connect = () => {
     if (!window.io) return false;
-    const socket = window.io();
-    socket.on("volt:reload", () => location.reload());
-    console.log("[volt] hot reload connected");
+    window.io().on("volt:reload", onChange);
+    console.log("[volt] hot reload connected (live morph)");
     return true;
   };
   if (!connect()) window.addEventListener("load", connect);

package/templates/starter/server.js

@@ -231,7 +231,7 @@ async function startApp() {
     clearTimeout(timer);
     timer = setTimeout(() => {
       console.log(`[volt] change: ${file ?? "?"} → reload`);
-      io.emit("volt:reload");
+      io.emit("volt:reload", { file });
     }, 80);
   };
   const watchRecursive = (dir) => {