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

spark-ssr 0.1.0 → 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 (8) 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.0",
+  "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.0"
+    "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/hydrate.js CHANGED Viewed

@@ -15,6 +15,7 @@
  * becomes onclick={remove(todo)} — the runtime runs it as an inline statement.
  */
 import { parseHTML } from 'linkedom';
+import { templateKids } from './render.js';
 // Structural roles from the analysis (names are the author's own).
 export function handlerRoles(analysis) {
@@ -43,12 +44,7 @@ export function primaryColumn(cols) {
 export function clientComponent({ html, analysis, plan, table, cols, key }) {
   const { document } = parseHTML('<!doctype html><html><body>' + html + '</body></html>');
-  // Nested templates may keep their children in .childNodes rather than
-  // .content depending on how linkedom parsed them — read both.
-  const kids = (node) => [
-    ...(node.content ? node.content.childNodes : []),
-    ...node.childNodes,
-  ];
+  const kids = templateKids;
   (function transform(node, loopVar) {
     if (node.nodeType !== 1) return;
@@ -74,7 +70,16 @@ export function clientComponent({ html, analysis, plan, table, cols, key }) {
         const em = each.match(/^\s*([\w$]+)/);
         if (em) inner = em[1];
       }
-      for (const c of kids(node)) transform(c, inner);
+      // Attribute rewrites must reach BOTH of linkedom's template stores —
+      // it may hold duplicate copies in .content and .childNodes, and which
+      // one the serializer emits varies. (Moves, like the await unwrap above,
+      // take just the canonical side since the template is removed after.)
+      const seen = new Set();
+      for (const c of [...(node.content ? node.content.childNodes : []), ...node.childNodes]) {
+        if (seen.has(c)) continue;
+        seen.add(c);
+        transform(c, inner);
+      }
       return;
     }
     if (loopVar && node.attributes) {

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) {
@@ -37,12 +38,21 @@ export function evalExpr(expr, scope) {
 const str = (v) => (v == null ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v));
-// Template children may live in .content or .childNodes depending on how
-// linkedom parsed the (possibly nested) template — read both.
-const kids = (node) => [
-  ...(node.content ? node.content.childNodes : []),
-  ...node.childNodes,
-];
+// linkedom's template parsing is inconsistent: children can land in .content,
+// in .childNodes, split between the two (whitespace one side, elements the
+// other), or fully DUPLICATED into both. Never merge — pick the side that
+// actually holds elements; on a tie (duplicates) .content is canonical.
+export function templateKids(node) {
+  const c = node.content ? [...node.content.childNodes] : [];
+  const d = [...node.childNodes];
+  if (!c.length) return d;
+  if (!d.length) return c;
+  const hasEl = (a) => a.some((n) => n.nodeType === 1);
+  if (hasEl(c)) return c;
+  if (hasEl(d)) return d;
+  return c;
+}
+const kids = templateKids;
 const interpolate = (text, scope) =>
   String(text).replace(/\{([^{}]+)\}/g, (_, e) => str(evalExpr(e, scope)));
@@ -188,11 +198,45 @@ async function renderIfChain(node, scope, ctx, depth) {
   for (const link of chain) link.node.remove();
 }
+// Round-trip an evaluated prop back to an attribute string the runtime's
+// coerce() understands ('' = true, JSON for objects, …) — same contract as
+// spark-prerender's serializeProp.
+function serializeProp(v) {
+  if (v === true) return '';
+  if (v === false) return 'false';
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number') return String(v);
+  return JSON.stringify(v);
+}
+// Literal top-level defaults from a component <script> (let count = 0;
+// let greeting = 'hi') so the SSR output shows initial values instead of
+// blanks. Anything non-literal is skipped — the client boot computes it.
+export function scriptLiterals(code) {
+  const out = {};
+  for (const m of String(code).matchAll(/^\s*(?:let|var|const)\s+([a-zA-Z_$][\w$]*)\s*=\s*(.+?);?\s*$/gm)) {
+    const raw = m[2].trim();
+    try {
+      out[m[1]] = JSON.parse(raw.replace(/^'([^'\\]*)'$/, '"$1"'));
+    } catch { /* not a literal — client-side only */ }
+  }
+  return out;
+}
 async function renderImport(node, scope, ctx, depth) {
   const spec = node.getAttribute('import');
-  node.removeAttribute('import');
   if (depth >= (ctx.maxDepth || 20)) { node.innerHTML = ''; return; }
+  // A top-level host on a page that will client-mount keeps its import (plus
+  // a `name` and its evaluated props) so the runtime's flash-free hydrate
+  // path re-resolves it and the component comes alive — exactly the contract
+  // spark-prerender's makeHydratable establishes. Nested hosts are inlined;
+  // their parent rebuilds them on the client.
+  const keepHost = !!ctx.keepImports && depth === 0;
+  if (!keepHost) node.removeAttribute('import');
+  else node.setAttribute('name', String(spec).split(/[?#]/)[0].replace(/\/+$/, '').replace(/.*\//, '').replace(/\.html$/, ''));
   // Slot content renders in the CALLER's scope, before the component swaps in.
   await walkChildren(node, scope, ctx, depth);
   const slotHtml = node.innerHTML;
@@ -203,25 +247,43 @@ async function renderImport(node, scope, ctx, depth) {
   for (const attr of [...node.attributes]) {
     const n = attr.name;
     const v = String(attr.value || '');
+    if (n === 'import' || n === 'name' || n.startsWith('data-spark')) continue;
     if (n === 'class' || n === 'id') { if (v.includes('{')) attr.value = interpolate(v, scope); continue; }
     const exact = v.trim().match(/^\{([\s\S]+)\}$/);
     props[n] = exact ? evalExpr(exact[1], scope) : v.includes('{') ? interpolate(v, scope) : v;
-    node.removeAttribute(n);
+    // Kept hosts re-serialize the evaluated value so the client re-resolve
+    // receives the same props; inlined hosts drop them.
+    if (keepHost) attr.value = serializeProp(props[n]);
+    else node.removeAttribute(n);
   }
   const source = ctx.loadComponent ? await ctx.loadComponent(spec) : null;
   if (source == null) { node.innerHTML = ''; return; }
-  // Components are pure UI: strip their <spark-ssr>/<script>, keep markup+style.
-  const clean = String(source)
+  // 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 { 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, '');
+    .replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gi, (m, body) => { script += body + '\n'; return ''; }));
   node.innerHTML = clean;
-  await walkChildren(node, props, ctx, depth + 1);
+  const compScope = Object.assign(Object.create(null), scriptLiterals(script), props);
+  await walkChildren(node, compScope, ctx, depth + 1);
   // Default slot: replace <slot> with the caller's rendered content.
   for (const slot of [...node.querySelectorAll('slot')]) {
-    const holder = ctx.document.createElement('template');
+    const holder = ctx.document.createElement('div');
     holder.innerHTML = slotHtml;
-    slot.replaceWith(...(holder.content || holder).childNodes);
+    slot.replaceWith(...holder.childNodes);
+  }
+  // Stash the rendered slot content for the client's hydrate path
+  // (<template data-spark-slots>, read by the runtime on re-resolve).
+  if (keepHost && slotHtml.trim()) {
+    const stash = ctx.document.createElement('template');
+    stash.setAttribute('data-spark-slots', '');
+    stash.innerHTML = slotHtml;
+    node.appendChild(stash);
   }
 }

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;
 }
@@ -120,12 +134,95 @@ export async function serve(options = {}) {
   const config = { ...loadConfig(root), ...(options.config || {}) };
   const db = await connect(config.db);
   const secret = (config.auth && config.auth.secret) || randomBytes(32).toString('hex');
-  const { pagesDir, pages } = scanPages(root);
   const cache = new Map();
+  const pages = [];
+  let pagesDir = root;
   const uploadsDir = join(root, config.uploads);
   const quiet = !!options.quiet;
-  const ctx = { root, config, db, secret, pagesDir, pages, cache, uploadsDir, port: 0 };
+  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) {
@@ -227,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) => {
@@ -255,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); }
@@ -317,36 +429,56 @@ export async function serve(options = {}) {
   }
   // ── explicit <spark-ssr> query endpoints ──
-  const registered = new Set();
+  // Defs are mutable so an edited page's SQL takes effect without a restart —
+  // the registered handler reads def.sql at call time.
+  const queryDefs = new Map();
   function registerQuery(route) {
     const key = route.method + ' ' + route.path;
-    if (registered.has(key)) return;
-    registered.add(key);
+    const existing = queryDefs.get(key);
+    if (existing) { existing.sql = route.sql; return; }
+    const def = { sql: route.sql };
+    queryDefs.set(key, def);
     const segs = route.path.split('/').filter(Boolean)
       .map((s) => s.replace(/^\[(\w+)\]$/, ':$1'));
     apiRoutes.push({
       method: route.method,
       segs,
       handler: async (req) => {
-        const rows = await runSql(route.sql, req);
-        if (route.method === 'GET') return json(singleShaped(route.sql) ? rows[0] ?? null : [...rows]);
+        const rows = await runSql(def.sql, req);
+        if (route.method === 'GET') return json(singleShaped(def.sql) ? rows[0] ?? null : [...rows]);
         if (Array.isArray(rows) && rows.length) return json(rows.length === 1 ? rows[0] : [...rows]);
         return json({ ok: true, changes: rows.changes ?? 0 });
       },
     });
   }
-  // Register everything the pages declare.
+  // (Re)scan pages/ and register everything they declare. Runs per request —
+  // 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();
-  for (const page of pages) {
-    const pd = pageData(page, cache);
-    for (const b of pd.blocks) {
-      if (b.table && !tables.has(b.table)) { tables.add(b.table); registerTable(b.table); }
-      for (const r of b.routes) {
-        if (r.path) registerQuery(r);
+  // 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;
+    pages.splice(0, pages.length, ...scanned.pages);
+    for (const page of pages) {
+      let pd;
+      try { pd = pageData(page, cache); } catch { continue; }
+      for (const b of pd.blocks) {
+        if (b.table && !tables.has(b.table)) { tables.add(b.table); registerTable(b.table); }
+        for (const r of b.routes) {
+          if (r.path) registerQuery(r);
+        }
       }
     }
   }
+  refreshPages();
   // ── api/ folder — custom endpoints ──
   function makeAppFetch(req) {
@@ -368,8 +500,12 @@ export async function serve(options = {}) {
     };
   }
-  const apiDir = join(root, 'api');
-  if (existsSync(apiDir)) {
+  // api/ files re-scan per request too; script handlers hold a mutable def so
+  // edits take effect, and registration itself happens once per route.
+  const apiDefs = new Map(); // route path → { mtime, fn }
+  function refreshApi() {
+    const apiDir = join(root, 'api');
+    if (!existsSync(apiDir)) return;
     (function scanApi(dir, prefix) {
       for (const f of readdirSync(dir)) {
         if (f.startsWith('.')) continue;
@@ -377,21 +513,32 @@ export async function serve(options = {}) {
         if (statSync(full).isDirectory()) { scanApi(full, prefix + f + '/'); continue; }
         if (!f.endsWith('.html')) continue;
         const route = '/api/' + prefix + f.slice(0, -5);
+        const mtime = statSync(full).mtimeMs;
+        let def = apiDefs.get(route);
+        if (def && def.mtime === mtime) continue;
+        if (!def) { def = { mtime: 0, fn: null, registered: false }; apiDefs.set(route, def); }
+        def.mtime = mtime;
         const source = readFileSync(full, 'utf8');
         const { blocks, html } = extractBlocks(source);
         const { code } = splitScript(html);
         for (const b of blocks) {
           for (const r of b.routes) registerQuery({ ...r, path: r.path || route });
         }
+        def.fn = null;
         if (code) {
-          const fn = new AsyncFunction('req', 'res', 'db', 'fetch', code);
+          try { def.fn = new AsyncFunction('req', 'res', 'db', 'fetch', code); }
+          catch (e) { if (!quiet) console.warn(`[spark-ssr] ${route} <script> — ${e.message}`); }
+        }
+        if (def.fn && !def.registered) {
+          def.registered = true;
           const segs = route.split('/').filter(Boolean);
           for (const method of ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']) {
             apiRoutes.push({
               method,
               segs,
               handler: async (req, res) => {
-                const out = await fn(req, res, db, makeAppFetch(req));
+                if (!def.fn) return json({ error: 'not found' }, 404);
+                const out = await def.fn(req, res, db, makeAppFetch(req));
                 if (out instanceof Response) return out;
                 if (out && typeof out === 'object' && 'status' in out && 'body' in out) {
                   return new Response(typeof out.body === 'string' ? out.body : JSON.stringify(out.body), { status: out.status });
@@ -404,6 +551,7 @@ export async function serve(options = {}) {
       }
     })(apiDir, '');
   }
+  refreshApi();
   function matchApi(method, pathname) {
     const parts = pathname.split('/').filter(Boolean);
@@ -419,14 +567,24 @@ export async function serve(options = {}) {
     return null;
   }
-  // ── middleware.html ──
+  // ── middleware.html (reloaded when the file changes) ──
   let middleware = null;
+  let mwMtime = -1;
   const mwState = { rateLimit: new Map(), state: {} };
-  const mwFile = join(root, 'middleware.html');
-  if (existsSync(mwFile)) {
+  function refreshMiddleware() {
+    const mwFile = join(root, 'middleware.html');
+    if (!existsSync(mwFile)) { middleware = null; mwMtime = -1; return; }
+    const mtime = statSync(mwFile).mtimeMs;
+    if (mtime === mwMtime) return;
+    mwMtime = mtime;
+    middleware = null;
     const { code } = splitScript(readFileSync(mwFile, 'utf8'));
-    if (code) middleware = new AsyncFunction('req', 'res', 'rateLimit', 'state', 'fetch', code);
+    if (code) {
+      try { middleware = new AsyncFunction('req', 'res', 'rateLimit', 'state', 'fetch', code); }
+      catch (e) { if (!quiet) console.warn(`[spark-ssr] middleware.html — ${e.message}`); }
+    }
   }
+  refreshMiddleware();
   // ── CORS ──
   function corsHeaders(origin) {
@@ -460,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) {
@@ -492,23 +656,51 @@ export async function serve(options = {}) {
       && pd.blocks.some((b) => b.table) && !!db;
   }
-  function shell(page, body, { hydrate }) {
+  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 = hydrate
-      ? `\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
+    // component is fetched and booted detached, then swaps in atomically.
+    // `name` missing would make the runtime treat the rendered HTML as SLOT
+    // content and project it next to the fresh render — duplicated live UI.
+    const compName = page.key.replace(/.*\//, '');
     const host = hydrate
-      ? `<div import="/__spark/page/${page.key}" data-spark-ssr>${body}</div>`
+      ? `<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) {
@@ -529,8 +721,16 @@ export async function serve(options = {}) {
   async function servePage(page, req) {
     const pd = pageData(page, cache);
     const scope = await buildScope(pd, req);
-    const body = await renderFragment(pd.html, scope, { loadComponent });
-    return new Response(shell(page, body, { hydrate: shouldHydrate(pd) }), {
+    const hydrate = shouldHydrate(pd);
+    // Component imports keep their host (import + name + props) on pages the
+    // page host won't rebuild wholesale, so a client mount re-resolves them
+    // 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 });
+    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' },
     });
   }
@@ -538,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 ──
@@ -564,10 +779,27 @@ 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 = {};
       try {
+        // Pick up new/edited pages, api files, and middleware without a
+        // restart (readdir walk + mtime-cached parses — cheap).
+        if (options.watch !== false) { refreshPages(); refreshApi(); refreshMiddleware(); }
         // middleware.html runs first, on every request.
         if (middleware) {
           const req = wrapReq(request, url, {}, session, srv);
@@ -585,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/')) {
@@ -669,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();
+    },
   };
 }