spark-html-bun 0.1.1 → 0.1.3

package/README.md

@@ -26,8 +26,12 @@ bun dev
   (built from your `package.json`), so the browser runs your ES modules directly
   — **no bundling in dev**. Scoped component HMR rides a plain WebSocket
   (`/__spark_hmr`) + `fs.watch`: edit a component and only its instances
-  re-mount, sibling state preserved (slotted / loop-managed hosts full-reload,
-  always correct).
+  re-mount — fresh markup **and** fresh scoped CSS — sibling state preserved
+  (slotted / loop-managed hosts full-reload, always correct; components not on
+  the current page are a no-op — the next mount fetches them fresh). Editing a
+  `.css` file swaps the matching `<link>` in place with no reload; editing page
+  HTML or a JS module reloads. Editor save patterns (temp file + rename) are
+  debounced into a single update.
 - **`spark build`** — empties `dist/`, copies `public/` verbatim (components ship
   as authored), bundles the HTML entry's scripts/styles with `Bun.build`
   (hashed under `assets/`, `base` honored), then runs the **pipeline** in order.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spark-html-bun",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Dev server, build, and preview for spark-html apps — built entirely on Bun. Scoped component HMR over a plain WebSocket, import-map dev serving (no bundling in dev), Bun.build for the app shell, and an explicit post-build pipeline (prerender, image, font, manifest, offline, sri). Zero dependencies.",
   "homepage": "https://wilkinnovo.github.io/spark",
   "type": "module",

package/src/index.js

@@ -27,8 +27,12 @@
  *    from /@modules/<name>) — no bundling in dev at all, the browser runs
  *    your ES modules directly. Scoped component HMR rides a plain WebSocket
  *    (/__spark_hmr) + fs.watch: edit a component file and only its instances
- *    re-mount, sibling state preserved (slotted/loop-managed hosts full-reload,
- *    always correct — the exact semantics of the Vite plugin).
+ *    re-mount — fresh markup AND fresh scoped CSS — sibling state preserved
+ *    (slotted/loop-managed hosts full-reload, always correct; a component not
+ *    mounted on the current page is a no-op — fragments are no-cache, the next
+ *    mount fetches it fresh). Stylesheet (.css) edits swap the matching <link>
+ *    in place, no reload; page HTML / JS module edits full-reload. Broadcasts
+ *    are debounced so editor save patterns (temp file + rename) send one update.
  *  • build — empty outDir, copy publicDir verbatim (components ship as
  *    authored), Bun.build the HTML entry (scripts/styles bundled + hashed
  *    under assets/, HTML rewritten, base honored via publicPath), then run
@@ -60,6 +64,13 @@ function decodePath(pathname) {
   try { return decodeURIComponent(pathname); } catch { return null; }
 }
 
+// One stat instead of existsSync + statSync — this runs per request candidate
+// on the dev/preview hot path.
+function isFile(p) {
+  const s = statSync(p, { throwIfNoEntry: false });
+  return s !== undefined && s.isFile();
+}
+
 const MIME = {
   '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript',
   '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml',
@@ -116,36 +127,73 @@ export async function loadConfig(root = process.cwd(), overrides = {}) {
 
 // The scoped-HMR client. The re-mount logic (unmount host → placeholder →
 // re-mount; slotted/managed hosts full-reload) rides a plain WebSocket the
-// dev server owns, instead of a bundler's HMR channel.
+// dev server owns, instead of a bundler's HMR channel. Messages:
+//   { name }   component fragment changed → re-mount its instances in place
+//   { css }    stylesheet changed → swap the matching <link> (no reload)
+//   { reload } page-level file changed → full reload
 const HMR_CLIENT = `
 import { mount, unmount } from 'spark-html';
+
+// Swap a stylesheet in place: load the cache-busted copy alongside, remove the
+// old one when it's ready — no flash of unstyled content.
+function swapCss(path) {
+  for (const link of document.querySelectorAll('link[rel="stylesheet"]')) {
+    const url = new URL(link.href, location.href);
+    if (url.origin !== location.origin || url.pathname !== path) continue;
+    url.searchParams.set('t', Date.now());
+    const next = link.cloneNode();
+    next.href = url.pathname + url.search;
+    next.onload = () => link.remove();
+    link.after(next);
+    console.log('[spark] ⚡ css-updated', path);
+  }
+}
+
+async function update(name) {
+  const hosts = [...document.querySelectorAll('[name="' + name + '"]')];
+  // Not mounted right now (e.g. it lives on another route): nothing to do —
+  // fragments are served no-cache, so the next mount fetches it fresh anyway.
+  if (!hosts.length) return;
+  // Scoped HMR only for simple top-level hosts; slotted or loop/if-managed
+  // hosts fall back to a full reload so the result is always correct.
+  if (hosts.some((h) => h.__sparkHadSlots || h.__sparkManaged)) { location.reload(); return; }
+  try {
+    // Drop the component's injected style so the re-mount installs the fresh
+    // one (bootComponent dedupes by data-spark tag and would keep the stale CSS).
+    const style = document.querySelector('style[data-spark="' + name + '"]');
+    if (style) style.remove();
+    for (const host of hosts) {
+      const ph = document.createElement('div');
+      ph.setAttribute('import', host.__sparkImportPath || ('components/' + name + '.html'));
+      const props = host.__sparkProps || {};
+      for (const k in props) {
+        const v = props[k];
+        try { ph.setAttribute(k, typeof v === 'string' ? v : JSON.stringify(v)); } catch (e) {}
+      }
+      const cls = host.getAttribute('class'); if (cls) ph.setAttribute('class', cls);
+      if (host.id) ph.id = host.id;
+      const parent = host.parentNode;
+      unmount(host);
+      host.replaceWith(ph);
+      await mount(parent);
+    }
+    console.log('[spark] ⚡ hot-updated', name);
+  } catch (e) { location.reload(); }
+}
+
 function connect() {
   const ws = new WebSocket((location.protocol === 'https:' ? 'wss://' : 'ws://') + location.host + '/__spark_hmr');
-  ws.onmessage = async (ev) => {
-    const { name } = JSON.parse(ev.data);
-    const hosts = [...document.querySelectorAll('[name="' + name + '"]')];
-    if (!hosts.length) { location.reload(); return; }
-    // Scoped HMR only for simple top-level hosts; slotted or loop/if-managed
-    // hosts fall back to a full reload so the result is always correct.
-    if (hosts.some((h) => h.__sparkHadSlots || h.__sparkManaged)) { location.reload(); return; }
-    try {
-      for (const host of hosts) {
-        const ph = document.createElement('div');
-        ph.setAttribute('import', host.__sparkImportPath || ('components/' + name + '.html'));
-        const props = host.__sparkProps || {};
-        for (const k in props) {
-          const v = props[k];
-          try { ph.setAttribute(k, typeof v === 'string' ? v : JSON.stringify(v)); } catch (e) {}
-        }
-        const cls = host.getAttribute('class'); if (cls) ph.setAttribute('class', cls);
-        if (host.id) ph.id = host.id;
-        const parent = host.parentNode;
-        unmount(host);
-        host.replaceWith(ph);
-        await mount(parent);
-      }
-      console.log('[spark] ⚡ hot-updated', name);
-    } catch (e) { location.reload(); }
+  // Updates run strictly one after another — a second save landing while a
+  // re-mount is mid-flight must not observe the placeholder (it would find no
+  // host and mis-classify the state), so every message queues on the chain.
+  let chain = Promise.resolve();
+  ws.onmessage = (ev) => {
+    const msg = JSON.parse(ev.data);
+    chain = chain.then(() => {
+      if (msg.reload) { location.reload(); return; }
+      if (msg.css) { swapCss(msg.css); return; }
+      return update(msg.name);
+    }).catch(() => {});
   };
   ws.onclose = () => setTimeout(connect, 1000); // server restarted — retry
 }
@@ -199,7 +247,8 @@ async function transformPage(html, config, { dev }) {
   const inject =
     `<script type="importmap">${importMap}</script>\n` +
     `<script type="module">${HMR_CLIENT}</script>\n`;
-  if (/<head[^>]*>/i.test(out)) return out.replace(/<head[^>]*>/i, (m) => `${m}\n${inject}`);
+  // `<head(\s…)?>` — never match a page's <header> element.
+  if (/<head(\s[^>]*)?>/i.test(out)) return out.replace(/<head(\s[^>]*)?>/i, (m) => `${m}\n${inject}`);
   return inject + out;
 }
 
@@ -253,7 +302,7 @@ export async function dev(overrides = {}) {
       let file = null;
       for (const b of [projectRoot, pub]) {
         const c = safeJoin(b, rel);
-        if (c && existsSync(c) && statSync(c).isFile()) { file = c; break; }
+        if (c && isFile(c)) { file = c; break; }
       }
 
       // SPA fallback: extensionless paths serve the app shell (the router
@@ -287,15 +336,56 @@ export async function dev(overrides = {}) {
     },
   });
 
-  // Watch component fragments; broadcast the component name on change.
+  // Watch the whole project for dev edits and broadcast the right HMR message:
+  // component fragments → scoped re-mount, stylesheets → in-place <link> swap,
+  // page HTML (the entry, or any other served page) → full reload. Broadcasts
+  // are debounced per key — editors save via temp-file + rename and emit
+  // several fs events per keystroke, and a duplicate message arriving while
+  // the client is mid-re-mount would mis-read the DOM.
   const componentsRoot = existsSync(join(pub, componentsDir)) ? join(pub, componentsDir) : join(projectRoot, componentsDir);
+  const outAbs = resolve(projectRoot, config.outDir);
+  const timers = new Map();
+  const broadcast = (key, msg) => {
+    clearTimeout(timers.get(key));
+    timers.set(key, setTimeout(() => {
+      timers.delete(key);
+      server.publish('spark-hmr', JSON.stringify(msg));
+    }, 50));
+  };
+  const onChange = (base) => (_event, filename) => {
+    if (!filename) return;
+    const rel = String(filename);
+    // Never react to build output, deps, or VCS internals.
+    if (/(^|\/)(node_modules|\.git)(\/|$)/.test(rel)) return;
+    const abs = join(base, rel);
+    if (abs === outAbs || abs.startsWith(outAbs + sep)) return;
+    if (rel.endsWith('.css')) {
+      // The URL the page loads this file under: public/ files are served from
+      // the site root, project files from their project-relative path.
+      const underPub = abs.startsWith(pub + sep);
+      const urlPath = '/' + (underPub ? abs.slice(pub.length + 1) : abs.slice(projectRoot.length + 1)).split(sep).join('/');
+      broadcast(urlPath, { css: urlPath });
+      return;
+    }
+    // App modules are served raw — an edit only takes effect on a fresh page.
+    if (/\.(js|mjs)$/.test(rel)) { broadcast('/', { reload: true }); return; }
+    if (!rel.endsWith('.html')) return;
+    if (abs.startsWith(componentsRoot + sep)) {
+      const name = rel.split('/').pop().replace(/\.html$/, '');
+      broadcast(name, { name });
+      return;
+    }
+    // A page (the entry or any other top-level HTML) — only a reload is correct.
+    broadcast('/', { reload: true });
+  };
   let unwatch = () => {};
-  if (existsSync(componentsRoot)) {
-    unwatch = watchTree(componentsRoot, (_event, filename) => {
-      if (!filename || !String(filename).endsWith('.html')) return;
-      const name = String(filename).split('/').pop().replace(/\.html$/, '');
-      server.publish('spark-hmr', JSON.stringify({ name }));
-    });
+  {
+    const stops = [watchTree(projectRoot, onChange(projectRoot))];
+    // publicDir outside the project root (unusual, but configurable).
+    if (existsSync(pub) && !pub.startsWith(projectRoot + sep) && pub !== projectRoot) {
+      stops.push(watchTree(pub, onChange(pub)));
+    }
+    unwatch = () => stops.forEach((s) => s());
   }
 
   const stop = server.stop.bind(server);
@@ -343,12 +433,17 @@ export async function build(overrides = {}) {
       const file = clean.startsWith('/') ? join(projectRoot, clean.slice(1)) : join(entryDir, clean);
       // Only bundle files that live in the PROJECT (src/…) — anything served
       // from publicDir ships verbatim and its URL already works.
-      if (existsSync(file) && !file.startsWith(pub + '/')) found.push({ url, file });
+      if (existsSync(file) && !file.startsWith(pub + sep)) found.push({ url, file });
     }
 
     if (found.length) {
+      // Bun.build DEDUPES duplicate entrypoints (the same file listed twice —
+      // or reached via two URL spellings — yields ONE output), so bundle the
+      // UNIQUE files and map file → hashed name; never map outputs back by
+      // found-index, which would splice the wrong asset URL into the page.
+      const files = [...new Set(found.map((f) => f.file))];
       const result = await Bun.build({
-        entrypoints: found.map((f) => f.file),
+        entrypoints: files,
         outdir: join(outDir, 'assets'),
         minify: true,
         splitting: true,
@@ -362,17 +457,19 @@ export async function build(overrides = {}) {
         throw new Error(`[spark] build failed:\n${msgs}`);
       }
       // Entry outputs come back in entrypoint order (verified for Bun's
-      // splitting output, incl. same-basename entries) — map each to its URL.
+      // splitting output, incl. same-basename entries) — map each unique
+      // file to its hashed name, then rewrite every tag that referenced it.
       const entryOuts = result.outputs.filter((o) => o.kind === 'entry-point');
-      found.forEach((f, i) => {
-        const name = entryOuts[i] && basename(entryOuts[i].path);
-        if (!name) return;
+      const outName = new Map(files.map((file, i) => [file, entryOuts[i] && basename(entryOuts[i].path)]));
+      for (const f of found) {
+        const name = outName.get(f.file);
+        if (!name) continue;
         const to = `${base}assets/${name}`;
         // Replace only the quoted attribute value, so a longer URL that ends
         // with this one (e.g. /lib/app.js vs /app.js) is never corrupted the
         // way a bare replaceAll(url) would corrupt it.
         for (const q of ['"', "'"]) html = html.split(`${q}${f.url}${q}`).join(`${q}${to}${q}`);
-      });
+      }
     }
     await Bun.write(join(outDir, config.entry.split('/').pop()), html);
   }
@@ -411,7 +508,7 @@ export async function preview(overrides = {}) {
         rel !== '' && rel.endsWith('/') ? safeJoin(outDir, join(rel, 'index.html')) : null,
       ].filter(Boolean);
       for (const f of tryFiles) {
-        if (existsSync(f) && statSync(f).isFile()) {
+        if (isFile(f)) {
           return new Response(Bun.file(f), { headers: { 'Content-Type': mime(f) } });
         }
       }