spark-html-bun 0.1.2 → 0.1.4

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,8 +1,8 @@
 {
   "name": "spark-html-bun",
-  "version": "0.1.2",
-  "description": "Dev server, build, and preview for spark-html apps \u2014 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",
+  "version": "0.1.4",
+  "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-html",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -24,7 +24,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/wilkinnovo/spark.git"
+    "url": "git+https://github.com/wilkinnovo/spark-html.git"
   },
   "keywords": [
     "bun",

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
@@ -42,7 +46,7 @@
  *     devRoutes?({ config }) → { '/path': { type, body() } },  // dev serving
  *     transformHtml?(html, { dev }) }                  // dev page injection
  */
-import { join, resolve, extname, basename, sep } from 'node:path';
+import { join, resolve, dirname, extname, basename, sep } from 'node:path';
 import { existsSync, watch, readdirSync, statSync, readFileSync } from 'node:fs';
 import { rm, mkdir, cp, readFile } from 'node:fs/promises';
 
@@ -123,52 +127,107 @@ 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
 }
 connect();
 `;
 
+// Resolve a bare package to the { dir, entry } of its module entry file, so we
+// can serve the entry AND its sibling files under one /@modules/<pkg>/ prefix.
+// Cached — the resolution doesn't change while the server is up.
+const moduleInfoCache = new Map();
+function moduleEntry(pkg, projectRoot) {
+  const key = projectRoot + '\0' + pkg;
+  if (moduleInfoCache.has(key)) return moduleInfoCache.get(key);
+  let info = null;
+  try {
+    const file = Bun.resolveSync(pkg, projectRoot);
+    info = { dir: dirname(file), entry: file.slice(file.lastIndexOf('/') + 1) };
+  } catch { /* unresolvable — leave null */ }
+  moduleInfoCache.set(key, info);
+  return info;
+}
+
 // Import map for the app's bare specifiers: every dependency in package.json
-// maps to /@modules/<name>, which the dev server resolves with Bun's resolver.
-// Spark packages are single-file modules whose only bare import is
-// 'spark-html' (also in the map), so no rewriting is needed anywhere.
+// maps to /@modules/<name>/<entry-file>. The trailing entry filename matters —
+// a package's own relative imports (e.g. spark-html-theme's `./init.js`) resolve
+// against that URL, so they land at /@modules/<name>/init.js and stay inside the
+// package instead of collapsing to /@modules/init.js (a 404 that blanks the app).
 function buildImportMap(projectRoot) {
   const imports = {};
   try {
     const pkg = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf8'));
     for (const dep of Object.keys({ ...pkg.dependencies, ...pkg.devDependencies })) {
-      imports[dep] = `/@modules/${dep}`;
+      const info = moduleEntry(dep, projectRoot);
+      if (info) imports[dep] = `/@modules/${dep}/${info.entry}`;
     }
   } catch { /* no package.json — no bare imports to map */ }
   return imports;
@@ -206,7 +265,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;
 }
 
@@ -243,15 +303,22 @@ export async function dev(overrides = {}) {
         return new Response(await route.body(), { headers: { 'Content-Type': route.type } });
       }
 
-      // Bare-specifier modules: /@modules/<name> → Bun-resolved entry file.
+      // Bare-specifier modules: /@modules/<name>/<file> → the package's entry
+      // (or a sibling file it imports relatively), served from the entry's dir.
       if (path.startsWith('/@modules/')) {
-        const spec = path.slice('/@modules/'.length);
-        try {
-          const file = Bun.resolveSync(spec, projectRoot);
-          return new Response(Bun.file(file), { headers: { 'Content-Type': 'text/javascript' } });
-        } catch {
-          return new Response(`/* cannot resolve "${spec}" */`, { status: 404, headers: { 'Content-Type': 'text/javascript' } });
+        const rest = path.slice('/@modules/'.length);
+        const slash = rest.indexOf('/');
+        const pkg = slash === -1 ? rest : rest.slice(0, slash);
+        const subpath = slash === -1 ? '' : rest.slice(slash + 1);
+        const info = moduleEntry(pkg, projectRoot);
+        if (info) {
+          const file = resolve(info.dir, subpath || info.entry);
+          // Guard against escaping the package dir via a crafted subpath.
+          if (file.startsWith(info.dir + sep) && isFile(file)) {
+            return new Response(Bun.file(file), { headers: { 'Content-Type': 'text/javascript' } });
+          }
         }
+        return new Response(`/* cannot resolve "${rest}" */`, { status: 404, headers: { 'Content-Type': 'text/javascript' } });
       }
 
       // Static lookup: project root first (index.html, src/…), then publicDir.
@@ -294,15 +361,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);