npm - spark-ssr - Versions diffs - 0.1.1 → 0.2.0 - Mend

spark-ssr 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -47,13 +47,16 @@ No `<script>`. No SQL. No ORM. No server file. No build step.
 {
   "db": "postgres://localhost:5432/myapp",
   "auth": { "table": "users", "identity": "email", "secret": "ENV.SESSION_SECRET" },
-  "cors": true
+  "cors": true,
+  "fonts": [{ "family": "Inter", "google": true, "weights": [400, 700] }]
 }
 ```
 `sqlite://./dev.db` works too (Bun ships both drivers). `ENV.*` values resolve
 from the environment at startup. `cors: true` allows all origins on `/api/*`;
-an array allows specific ones.
+an array allows specific ones. `fonts` renders spark-html-font's head tags
+(preloads, `@font-face` with a size-adjusted no-shift fallback, a
+`--font-<slug>` var) into every page — same shapes as its build-pipeline step.
 ## Routing
@@ -79,6 +82,41 @@ Without a `pages/` folder, `*.html` at the project root serve the same way.
 JSON body (`:body.title`), session (`:session.id`), headers
 (`:header.x-forwarded-for`), uploads (`:file.url`).
+## The page owns its \<head\>
+Literal `<title>`/`<meta>`/`<link>` tags at the top of a page lift into the
+document head, `{expr}`-interpolated against the page's data
+(spark-html-head's `/ssr` module does the lifting):
+```html
+<!-- pages/blog/[slug].html -->
+<title>{post.title} · My Blog</title>
+<meta name="description" content="{post.excerpt}">
+```
+## Client scripts and the family
+A page's plain `<script>` runs on the **server** (the escape hatch).
+`<script type="module">` and `<script src>` are **client** scripts — they lift
+into `<head>` after an auto-generated importmap, so bare imports of the Spark
+family just work, no build:
+```html
+<script type="module" src="/app.js"></script>
+```
+```js
+// public/app.js
+import { theme } from 'spark-html-theme';
+theme();
+```
+Every `spark-html-*` package in your dependencies is importmap-mapped and
+served at `/@modules/<name>/…`. Depend on **spark-html-theme** and the
+no-flash init snippet is inlined in every head automatically; depend on
+**spark-html-image** and `spark-ssr build` runs its webp/srcset pass over
+`dist/` (options: `"images"` in spark.json).
 ## Custom endpoints — api/
 `api/stats.html` auto-serves as `GET /api/stats`:
@@ -104,14 +142,22 @@ scope; the return value becomes the JSON response).
   stored URL into your INSERT.
 - **Error pages** — `404.html` / `500.html` at the project root.
 - **Static assets** — `public/` plus co-located page assets, served as-is.
+  Project internals (spark.json, package.json, `*.db`, dotfiles) are never
+  served.
 - **Hydration** — interactive pages ship fully-rendered HTML plus a generated
   client component; `mount()` takes over with the same spark-html runtime.
+- **Live reload** — in dev, every edit (pages, components, queries,
+  middleware, css) refreshes the browser via SSE. No restart, no flags.
+- **Auth-table hygiene** — the auth table's auto CRUD never returns password
+  hashes, and PATCH/DELETE are own-account only. Configuring `auth` registers
+  the table (login/signup endpoints) without any page declaring it; disable
+  public signup in `middleware.html` if the app is invite-only.
 ## Deploy
 ```bash
-bun spark-ssr build   # dist/ with a compiled single binary
-bun spark-ssr start   # run in production
+bun spark-ssr build   # dist/ with a compiled single binary (public/ flattens into dist root)
+bun spark-ssr start   # run in production (watch + live reload off)
 ```
 MIT

package/bin/cli.js CHANGED Viewed

@@ -15,7 +15,7 @@
  */
 import { join, resolve } from 'node:path';
 import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync, readdirSync, statSync } from 'node:fs';
-import { serve } from '../src/index.js';
+import { serve, loadConfig } from '../src/index.js';
 function parseArgs(argv) {
   const opts = { cmd: 'serve', compile: true };
@@ -41,7 +41,10 @@ Usage:
 // The project files a deployment needs — pages, components, api, public,
 // error pages, middleware, config. node_modules/dist/uploads stay behind.
-const SHIP_DIRS = ['pages', 'components', 'api', 'public'];
+// public/ is FLATTENED into dist root: assets keep the same URLs they had in
+// dev (/style.css, /img/…), and post-build passes (spark-html-image) resolve
+// root-absolute <img> paths against dist directly.
+const SHIP_DIRS = ['pages', 'components', 'api'];
 const SHIP_FILES = ['404.html', '500.html', 'middleware.html', 'spark.json', 'package.json'];
 async function build(root, compile) {
@@ -51,6 +54,11 @@ async function build(root, compile) {
   for (const d of SHIP_DIRS) {
     if (existsSync(join(root, d))) cpSync(join(root, d), join(dist, d), { recursive: true });
   }
+  if (existsSync(join(root, 'public'))) {
+    for (const f of readdirSync(join(root, 'public'))) {
+      cpSync(join(root, 'public', f), join(dist, f), { recursive: true });
+    }
+  }
   for (const f of SHIP_FILES) {
     if (existsSync(join(root, f))) cpSync(join(root, f), join(dist, f));
   }
@@ -67,8 +75,16 @@ async function build(root, compile) {
   }
   writeFileSync(join(dist, '__server.js'),
     "import { serve } from 'spark-ssr';\n" +
-    'serve({ root: process.cwd(), port: Number(process.env.PORT) || 3000 });\n');
+    'serve({ root: process.cwd(), port: Number(process.env.PORT) || 3000, watch: false });\n');
   console.log(`✓ assembled dist/`);
+  // spark-html-image, when the app depends on it: the same pass a
+  // spark-html-bun pipeline runs — webp variants + srcset for every local
+  // <img> in the assembled pages and components. Options: spark.json "images".
+  try {
+    const image = (await import('spark-html-image')).default;
+    await image(loadConfig(root).images || {}).run({ outDir: dist });
+    console.log('✓ images optimized (spark-html-image)');
+  } catch { /* not installed — plain assets ship as-is */ }
   if (compile) {
     const r = Bun.spawnSync(
       ['bun', 'build', '--compile', join(dist, '__server.js'), '--outfile', join(dist, 'app')],
@@ -89,7 +105,7 @@ if (opts.cmd === 'build') {
   await build(root, opts.compile);
 } else if (opts.cmd === 'start') {
   const dist = join(root, 'dist');
-  await serve({ root: existsSync(join(dist, '__server.js')) ? dist : root, port });
+  await serve({ root: existsSync(join(dist, '__server.js')) ? dist : root, port, watch: false });
 } else {
   await serve({ root, port });
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "spark-ssr",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Zero-config SSR for spark-html on Bun. The HTML template infers everything: filesystem routing, <spark-ssr> declarative queries, auto CRUD APIs, sessions, uploads, middleware. No build step.",
   "homepage": "https://wilkinnovo.github.io/spark-html",
   "type": "module",
@@ -30,7 +30,8 @@
   },
   "dependencies": {
     "linkedom": "^0.18.12",
-    "spark-html": "^0.27.7"
+    "spark-html": "^0.27.8",
+    "spark-html-head": "^0.3.0"
   },
   "keywords": [
     "spark-html",

package/src/config.js CHANGED Viewed

@@ -36,5 +36,10 @@ export function loadConfig(root) {
     auth: cfg.auth || null,
     cors: cfg.cors ?? false,
     uploads: cfg.uploads || 'uploads',
+    // Companion-package config, same shapes their build-pipeline steps take:
+    // "fonts" → spark-html-font tags in every <head>; "images" → options for
+    // the spark-html-image pass `spark-ssr build` runs when it's installed.
+    fonts: cfg.fonts || null,
+    images: cfg.images || null,
   };
 }

package/src/parse.js CHANGED Viewed

@@ -11,16 +11,30 @@
  */
 import { parseHTML } from 'linkedom';
+// ── comment masking ────────────────────────────────────────────────────
+// Every regex-based extraction here must mask comments first, so prose like
+// <!-- declare data in <spark-ssr>, no <script> needed --> never starts (or
+// ends) an extraction. restore() puts the comments back verbatim.
+export function maskComments(source) {
+  const comments = [];
+  const masked = String(source).replace(/<!--[\s\S]*?-->/g, (m) => {
+    comments.push(m);
+    return `\u0000c${comments.length - 1}\u0000`;
+  });
+  return { masked, restore: (s) => String(s).replace(/\u0000c(\d+)\u0000/g, (_, i) => comments[i]) };
+}
 // ── <spark-ssr> blocks ─────────────────────────────────────────────────
 export function extractBlocks(source) {
+  const { masked, restore } = maskComments(source);
   const blocks = [];
   const re = /<spark-ssr\b([^>]*?)\/>|<spark-ssr\b([^>]*)>([\s\S]*?)<\/spark-ssr>/gi;
-  const html = String(source).replace(re, (m, selfAttrs, attrs, inner) => {
+  const html = restore(masked.replace(re, (m, selfAttrs, attrs, inner) => {
     const attrStr = selfAttrs ?? attrs ?? '';
     const table = (attrStr.match(/\btable\s*=\s*"([^"]+)"/) || [])[1] || null;
     blocks.push({ table, routes: inner ? parseRoutes(inner) : [] });
     return '';
-  });
+  }));
   return { blocks, html };
 }

package/src/render.js CHANGED Viewed

@@ -6,6 +6,7 @@
  * re-attaches them client-side; static pages don't need them).
  */
 import { parseHTML } from 'linkedom';
+import { maskComments } from './parse.js';
 const FN_CACHE = new Map();
 function compile(expr) {
@@ -260,10 +261,12 @@ async function renderImport(node, scope, ctx, depth) {
   if (source == null) { node.innerHTML = ''; return; }
   // Components are pure UI on the server: strip <spark-ssr>/<script> from the
   // output, but read literal script defaults so {count} renders as 0.
+  // Comments are masked so prose mentioning those tags never truncates one.
   let script = '';
-  const clean = String(source)
+  const { masked, restore } = maskComments(source);
+  const clean = restore(masked
     .replace(/<spark-ssr\b[^>]*?\/>|<spark-ssr\b[^>]*>[\s\S]*?<\/spark-ssr>/gi, '')
-    .replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gi, (m, body) => { script += body + '\n'; return ''; });
+    .replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gi, (m, body) => { script += body + '\n'; return ''; }));
   node.innerHTML = clean;
   const compScope = Object.assign(Object.create(null), scriptLiterals(script), props);
   await walkChildren(node, compScope, ctx, depth + 1);

package/src/server.js CHANGED Viewed

@@ -10,9 +10,14 @@ import { existsSync, readFileSync, readdirSync, statSync, mkdirSync } from 'node
 import { createHmac, timingSafeEqual, randomBytes, randomUUID } from 'node:crypto';
 import { loadConfig } from './config.js';
 import { connect } from './db.js';
-import { extractBlocks, analyze, dataPlan, rewriteParams, singleShaped } from './parse.js';
-import { renderFragment } from './render.js';
+import { extractBlocks, analyze, dataPlan, rewriteParams, singleShaped, maskComments } from './parse.js';
+import { renderFragment, evalExpr } from './render.js';
 import { clientComponent, initModule } from './hydrate.js';
+// Head semantics live in one place for the whole family: spark-html-head owns
+// title/meta on the client (pushState updates); its /ssr module owns them
+// here — pages put literal <title>/<meta>/<link> tags in their markup, we
+// lift them into the document head with {expr} interpolated per request.
+import { liftHead, renderHead } from 'spark-html-head/ssr';
 const AsyncFunction = (async () => {}).constructor;
 const json = (data, status = 200, headers = {}) =>
@@ -63,12 +68,18 @@ function matchPage(pages, pathname) {
 }
 // Split the page's <script> (the server-side escape hatch) from its markup.
+// Client scripts — <script src> and inline <script type="module"> — are NOT
+// server code; they stay in the markup and liftHead sends them to the browser.
 function splitScript(html) {
   let code = '';
-  const out = String(html).replace(/<script\b(?![^>]*\bsrc=)[^>]*>([\s\S]*?)<\/script>/gi, (m, body) => {
-    code += body + '\n';
-    return '';
-  });
+  const { masked, restore } = maskComments(html);
+  const out = restore(masked.replace(
+    /<script\b(?![^>]*\bsrc=)(?![^>]*\btype\s*=\s*["']module["'])[^>]*>([\s\S]*?)<\/script>/gi,
+    (m, body) => {
+      code += body + '\n';
+      return '';
+    },
+  ));
   return { html: out, code: code.trim() };
 }
@@ -80,10 +91,13 @@ function pageData(page, cache) {
   const source = readFileSync(page.file, 'utf8');
   const { blocks, html } = extractBlocks(source);
   const { html: markup, code } = splitScript(html);
+  // Analyze BEFORE lifting the head, so a {var} used only in <title>/<meta>
+  // still registers as a data need.
   const analysis = analyze(markup);
   analysis.hasScript = !!code;
   const plan = dataPlan(analysis, blocks);
-  const data = { mtime, source, blocks, html: markup, code, analysis, plan };
+  const { head, scripts, body } = liftHead(markup);
+  const data = { mtime, source, blocks, html: body, head, scripts, code, analysis, plan };
   cache.set(page.file, data);
   return data;
 }
@@ -128,6 +142,88 @@ export async function serve(options = {}) {
   const ctx = { port: 0 };
+  // ── dev live reload ──
+  // The server side already re-reads files per request; this closes the loop
+  // on the browser side. A cheap mtime sweep (same walk refreshPages does)
+  // feeds an SSE channel, and every HTML response carries a two-line client
+  // that reloads the page on a ping. Production (`start` / dist) runs with
+  // watch:false and ships none of it.
+  const live = options.watch !== false;
+  const sseClients = new Set();
+  const sseEnc = new TextEncoder();
+  let watchTimer = null;
+  if (live) {
+    const IGNORE = new Set(['node_modules', 'dist', 'uploads']);
+    const mtimes = new Map();
+    const sweep = () => {
+      const seen = new Set();
+      let changed = false;
+      (function walk(dir) {
+        let names;
+        try { names = readdirSync(dir); } catch { return; }
+        for (const f of names) {
+          if (f.startsWith('.') || IGNORE.has(f)) continue;
+          const full = join(dir, f);
+          let st;
+          try { st = statSync(full); } catch { continue; }
+          if (st.isDirectory()) { walk(full); continue; }
+          if (!/\.(html|css|js|json)$/.test(f)) continue;
+          seen.add(full);
+          if (mtimes.get(full) !== st.mtimeMs) { mtimes.set(full, st.mtimeMs); changed = true; }
+        }
+      })(root);
+      for (const k of mtimes.keys()) if (!seen.has(k)) { mtimes.delete(k); changed = true; }
+      return changed;
+    };
+    sweep(); // baseline — the first pass records, it doesn't reload anyone
+    watchTimer = setInterval(() => {
+      if (!sweep()) return;
+      for (const c of sseClients) {
+        try { c.enqueue(sseEnc.encode('data: reload\n\n')); } catch { sseClients.delete(c); }
+      }
+    }, 250);
+    watchTimer.unref?.();
+  }
+  // Reconnect-then-reload: after a server restart the EventSource reconnects,
+  // and a fresh open following an error means "the server came back" — reload.
+  const RELOAD_CLIENT = '<script>(()=>{const e=new EventSource("/__spark/reload");let d=0;'
+    + 'e.onmessage=()=>location.reload();e.onerror=()=>{d=1};e.onopen=()=>{if(d)location.reload()}})()</script>';
+  // ── the Spark family, wired in ──
+  // Companion packages the app depends on get an importmap entry and are
+  // served at /@modules/<name>, so client scripts import them bare — the same
+  // packages a spark-html-bun/prerender build uses, working here unbundled.
+  let familyDeps = [];
+  try {
+    const pj = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    familyDeps = Object.keys({ ...pj.dependencies, ...pj.devDependencies })
+      .filter((n) => /^spark-html-[\w-]+$/.test(n));
+  } catch { /* no package.json — single-file project */ }
+  // spark-html-theme: inline its no-flash snippet in every <head> (the same
+  // one spark-html-theme/bun bakes into prerendered pages) so the saved/OS
+  // theme is on <html> before first paint.
+  let themeInit = '';
+  if (familyDeps.includes('spark-html-theme')) {
+    try {
+      const { themeInitScript } = await import('spark-html-theme/init');
+      themeInit = `<script>${themeInitScript()}</script>`;
+    } catch { /* older spark-html-theme without /init — theme() still works, with a flash */ }
+  }
+  // spark-html-font: `"fonts"` in spark.json renders the same head tags the
+  // font/bun pipeline step bakes at build time — preloads, @font-face with a
+  // size-adjusted fallback face, --font-<slug> vars.
+  let fontTags = '';
+  if (config.fonts) {
+    try {
+      const { fontHtml } = await import('spark-html-font');
+      fontTags = fontHtml({ fonts: config.fonts });
+    } catch (e) {
+      if (!quiet) console.warn(`[spark-ssr] "fonts" configured but spark-html-font is not installed — ${e.message}`);
+    }
+  }
   // ── request wrapper ──
   function wrapReq(request, url, params, session, server) {
     const headers = {};
@@ -228,7 +324,10 @@ export async function serve(options = {}) {
     on('GET', `api/${table}`, async (req) => {
       const { scoped } = await tableInfo(table);
       if (scoped && !req.session) return json({ error: 'unauthorized' }, 401);
-      return json(await tableRows(table, req));
+      const rows = await tableRows(table, req);
+      // Password hashes never leave the auth table, not even to a session.
+      if (isAuthTable) for (const r of rows) delete r.password;
+      return json(isAuthTable ? [...rows] : rows);
     });
     on('POST', `api/${table}`, async (req) => {
@@ -256,26 +355,38 @@ export async function serve(options = {}) {
       return json(row, 201);
     });
+    // Auth-table writes are own-account only: anyone could otherwise reset
+    // the author's password or delete their account through the auto CRUD.
+    const ownAccountOnly = (req) =>
+      isAuthTable && (!req.session || String(req.session.id) !== String(req.params.id));
     on('PATCH', `api/${table}/:id`, async (req) => {
       const { names, scoped } = await tableInfo(table);
       if (scoped && !req.session) return json({ error: 'unauthorized' }, 401);
+      if (ownAccountOnly(req)) return json({ error: 'unauthorized' }, 401);
       const { fields } = await req.body();
       const data = {};
       for (const [k, v] of Object.entries(fields)) {
         if (names.includes(k) && k !== 'id' && k !== 'user_id') data[k] = v;
       }
+      if (isAuthTable && typeof data.password === 'string') {
+        data.password = await Bun.password.hash(data.password);
+      }
       const keys = Object.keys(data);
       if (!keys.length) return json({ error: 'empty body' }, 400);
       let sql = `UPDATE ${table} SET ${keys.map((k) => `${k} = ?`).join(', ')} WHERE id = ?`;
       const values = [...keys.map((k) => data[k]), req.params.id];
       if (scoped) { sql += ' AND user_id = ?'; values.push(req.session.id); }
       const rows = await db.query(sql + ' RETURNING *', values);
-      return rows[0] ? json(rows[0]) : json({ error: 'not found' }, 404);
+      const row = rows[0];
+      if (isAuthTable && row) delete row.password;
+      return row ? json(row) : json({ error: 'not found' }, 404);
     });
     on('DELETE', `api/${table}/:id`, async (req) => {
       const { scoped } = await tableInfo(table);
       if (scoped && !req.session) return json({ error: 'unauthorized' }, 401);
+      if (ownAccountOnly(req)) return json({ error: 'unauthorized' }, 401);
       let sql = `DELETE FROM ${table} WHERE id = ?`;
       const values = [req.params.id];
       if (scoped) { sql += ' AND user_id = ?'; values.push(req.session.id); }
@@ -345,6 +456,13 @@ export async function serve(options = {}) {
   // a plain readdir walk plus mtime-cached parses — so new pages, new tables,
   // and edited queries appear without restarting the server.
   const tables = new Set();
+  // Configuring auth IS declaring its table: the login endpoint
+  // (POST /api/<table>?auth) and signup exist without any page mentioning
+  // them. Single-account apps can turn signup off in middleware.html.
+  if (config.auth && config.auth.table && db) {
+    tables.add(config.auth.table);
+    registerTable(config.auth.table);
+  }
   function refreshPages() {
     const scanned = scanPages(root);
     pagesDir = scanned.pagesDir;
@@ -500,9 +618,15 @@ export async function serve(options = {}) {
     if (!rel || rel.includes('..')) return null;
     const candidates = [join(root, 'public', rel)];
     const ext = extname(rel);
-    if (ext && ext !== '.html') {
+    // The root fallback exists for co-located assets (pages/x.css, img/…) —
+    // it must never serve project internals: config (may hold secrets),
+    // lockfiles, databases, dotfiles. public/ stays the intentional space.
+    const internal = rel.startsWith('.') || rel.includes('/.')
+      || ['spark.json', 'package.json', 'bun.lock', 'bun.lockb', 'package-lock.json'].includes(rel)
+      || ['.db', '.sqlite', '.sqlite3'].includes(ext);
+    if (!internal && ext && ext !== '.html') {
       candidates.push(join(root, rel), join(pagesDir, rel));
-    } else if (rel.startsWith('components/')) {
+    } else if (!internal && rel.startsWith('components/')) {
       candidates.push(join(root, rel));
     }
     for (const file of candidates) {
@@ -532,19 +656,39 @@ export async function serve(options = {}) {
       && pd.blocks.some((b) => b.table) && !!db;
   }
-  function shell(page, body, { hydrate, mount }) {
+  function shell(page, body, { hydrate, mount, headExtra = '', scripts = '' }) {
     const title = page.key === 'index' ? 'Spark' : page.key.split('/').pop().replace(/\[|\]/g, '');
     const cssRel = page.key + '.css';
     const hasCss = existsSync(join(pagesDir, cssRel));
+    // The importmap must precede EVERY module script in document order (a
+    // later one is ignored), so the whole module story lives in <head>:
+    // importmap → the page's own client scripts → mount. Page scripts are
+    // the app's bootstrap (store()/theme() setup) and modules execute in
+    // document order, so they run before components boot — same contract as
+    // a hand-written main.js that ends with mount().
+    const needModules = mount || scripts.includes('<script');
+    const imports = {};
+    for (const dep of ['spark-html', ...familyDeps]) {
+      const info = moduleEntry(dep);
+      if (info) imports[dep] = `/@modules/${dep}/${info.entry}`;
+    }
+    const importmap = needModules
+      ? `<script type="importmap">${JSON.stringify({ imports })}</script>\n`
+      : '';
+    const mountJs = mount
+      ? `<script type="module">import { mount } from 'spark-html'; mount();</script>\n`
+      : '';
     const head =
       '<meta charset="utf-8">\n' +
       '<meta name="viewport" content="width=device-width, initial-scale=1">\n' +
-      `<title>${title}</title>\n` +
+      (themeInit ? themeInit + '\n' : '') +
+      (/<title\b/i.test(headExtra) ? '' : `<title>${title}</title>\n`) +
+      (headExtra ? headExtra + '\n' : '') +
+      (fontTags ? fontTags + '\n' : '') +
+      importmap +
+      (scripts ? scripts + '\n' : '') +
+      mountJs +
       (hasCss ? `<link rel="stylesheet" href="/${cssRel}">\n` : '');
-    const hydration = mount
-      ? `\n<script type="importmap">{"imports":{"spark-html":"/@modules/spark-html"}}</script>\n` +
-        `<script type="module">import { mount } from 'spark-html'; mount();</script>\n`
-      : '\n';
     // A hydrating page host carries BOTH `import` and `name` — that is the
     // runtime's flash-free hydrate contract (same as spark-prerender's
     // makeHydratable): the pre-rendered content stays visible while the
@@ -555,7 +699,8 @@ export async function serve(options = {}) {
     const host = hydrate
       ? `<div import="/__spark/page/${page.key}" name="${compName}" data-spark-ssr>${body}</div>`
       : `<div data-spark-ssr>${body}</div>`;
-    return `<!doctype html>\n<html>\n<head>\n${head}</head>\n<body>\n${host}${hydration}</body>\n</html>\n`;
+    const reload = live ? RELOAD_CLIENT + '\n' : '';
+    return `<!doctype html>\n<html>\n<head>\n${head}</head>\n<body>\n${host}\n${reload}</body>\n</html>\n`;
   }
   async function buildScope(pd, req) {
@@ -582,7 +727,10 @@ export async function serve(options = {}) {
     // and their own <script> comes alive (counters, demos, …).
     const hasComponents = /\bimport\s*=\s*"/.test(pd.html);
     const body = await renderFragment(pd.html, scope, { loadComponent, keepImports: !hydrate });
-    return new Response(shell(page, body, { hydrate, mount: hydrate || hasComponents }), {
+    const headExtra = pd.head ? renderHead(pd.head, (e) => evalExpr(e, scope)) : '';
+    return new Response(shell(page, body, {
+      hydrate, mount: hydrate || hasComponents, headExtra, scripts: pd.scripts,
+    }), {
       headers: { 'content-type': 'text/html; charset=utf-8' },
     });
   }
@@ -590,22 +738,37 @@ export async function serve(options = {}) {
   function errorPage(status) {
     const file = join(root, `${status}.html`);
     if (existsSync(file)) {
-      return new Response(readFileSync(file, 'utf8'), { status, headers: { 'content-type': 'text/html; charset=utf-8' } });
+      // The reload client rides along so fixing the page un-sticks the browser.
+      const body = readFileSync(file, 'utf8') + (live ? '\n' + RELOAD_CLIENT : '');
+      return new Response(body, { status, headers: { 'content-type': 'text/html; charset=utf-8' } });
     }
     return new Response(status === 404 ? 'Not found' : 'Server error', { status });
   }
-  // spark-html runtime, served for hydration (importmap target).
-  let runtimeJs = null;
-  function runtimeFile() {
-    if (runtimeJs) return runtimeJs;
+  // spark-html + family packages, served as browser modules. The importmap
+  // maps each package name to /@modules/<pkg>/<entry>, and sibling files in
+  // the package resolve as relative imports under the same prefix (theme's
+  // ./init.js, say). Bun's resolver falls back to its GLOBAL install cache
+  // when a dir has no node_modules — that can be a different version than
+  // the app's, so cache hits only count when nothing real resolves.
+  const moduleInfo = new Map(); // pkg → { dir, entry } | null
+  function moduleEntry(pkg) {
+    if (moduleInfo.has(pkg)) return moduleInfo.get(pkg);
+    let lastResort = null;
     for (const dir of [root, dirname(new URL(import.meta.url).pathname)]) {
       try {
-        runtimeJs = readFileSync(Bun.resolveSync('spark-html', dir), 'utf8');
-        return runtimeJs;
+        const file = Bun.resolveSync(pkg, dir);
+        if (file.includes('/install/cache/')) { lastResort = lastResort || file; continue; }
+        const info = { dir: dirname(file), entry: file.slice(file.lastIndexOf('/') + 1) };
+        moduleInfo.set(pkg, info);
+        return info;
       } catch { /* next */ }
     }
-    return null;
+    const info = lastResort
+      ? { dir: dirname(lastResort), entry: lastResort.slice(lastResort.lastIndexOf('/') + 1) }
+      : null;
+    moduleInfo.set(pkg, info);
+    return info;
   }
   // ── the server ──
@@ -616,6 +779,19 @@ export async function serve(options = {}) {
       let pathname;
       try { pathname = decodeURIComponent(url.pathname); } catch { pathname = url.pathname; }
       if (pathname.includes('..')) return errorPage(404);
+      // Dev reload channel — before middleware; it's the harness, not the app.
+      if (live && pathname === '/__spark/reload') {
+        let ctrl;
+        const stream = new ReadableStream({
+          start(c) { ctrl = c; c.enqueue(sseEnc.encode(': connected\n\n')); sseClients.add(c); },
+          cancel() { sseClients.delete(ctrl); },
+        });
+        return new Response(stream, {
+          headers: { 'content-type': 'text/event-stream', 'cache-control': 'no-store' },
+        });
+      }
       const session = readSession(request.headers.get('cookie'), secret);
       const extraHeaders = {};
@@ -641,11 +817,24 @@ export async function serve(options = {}) {
           return res;
         };
-        if (pathname === '/@modules/spark-html') {
-          const js = runtimeFile();
-          return finish(js
-            ? new Response(js, { headers: { 'content-type': 'text/javascript', 'cache-control': 'no-cache' } })
-            : errorPage(404));
+        if (pathname.startsWith('/@modules/')) {
+          const rest = pathname.slice('/@modules/'.length);
+          const slash = rest.indexOf('/');
+          const pkg = slash === -1 ? rest : rest.slice(0, slash);
+          const subpath = slash === -1 ? '' : rest.slice(slash + 1);
+          let mod = null;
+          if (/^spark-html(-[\w-]+)?$/.test(pkg)) {
+            const info = moduleEntry(pkg);
+            if (info) {
+              const file = resolve(info.dir, subpath || info.entry);
+              if (file.startsWith(info.dir + '/') && existsSync(file) && statSync(file).isFile()) {
+                mod = new Response(readFileSync(file, 'utf8'), {
+                  headers: { 'content-type': 'text/javascript', 'cache-control': 'no-cache' },
+                });
+              }
+            }
+          }
+          return finish(mod || errorPage(404));
         }
         if (pathname.startsWith('/__spark/page/')) {
@@ -725,6 +914,12 @@ export async function serve(options = {}) {
     root,
     config,
     db,
-    stop(force) { server.stop(force); return db && db.close(); },
+    stop(force) {
+      if (watchTimer) clearInterval(watchTimer);
+      for (const c of sseClients) { try { c.close(); } catch { /* gone */ } }
+      sseClients.clear();
+      server.stop(force);
+      return db && db.close();
+    },
   };
 }