spark-ssr 0.2.0 → 0.3.0

package/src/server.js

@@ -1,18 +1,25 @@
 /**
  * spark-ssr server — `bun spark-ssr` and it serves.
  *
- * The filesystem is the router (pages/, api/, public/, 404.html, 500.html,
- * middleware.html), <spark-ssr> blocks declare the data, and everything else
- * is inferred from the template. No route handlers, no controllers, no build.
+ * The filesystem is the router (pages/, _layout.html, api/, public/,
+ * 404.html, 500.html, middleware.html), <spark-ssr> blocks declare the data
+ * (SQL, URLs, file globs, modules — named or inferred), and everything else
+ * is read from the template: auto CRUD, guards, form validation, schema,
+ * seeds, live updates. No route handlers, no controllers, no build.
  */
-import { join, resolve, extname, dirname } from 'node:path';
+import { join, resolve, extname, dirname, relative, sep } from 'node:path';
 import { existsSync, readFileSync, readdirSync, statSync, mkdirSync } from 'node:fs';
 import { createHmac, timingSafeEqual, randomBytes, randomUUID } from 'node:crypto';
 import { loadConfig } from './config.js';
 import { connect } from './db.js';
-import { extractBlocks, analyze, dataPlan, rewriteParams, singleShaped, maskComments } from './parse.js';
+import {
+  extractBlocks, analyze, mergeAnalyses, dataPlan, rewriteParams, singleShaped,
+  maskComments, extractForms, validateFields, sqlTables,
+} from './parse.js';
 import { renderFragment, evalExpr } from './render.js';
 import { clientComponent, initModule } from './hydrate.js';
+import { urlSource, globSource, moduleSource, makeSourceCache } from './sources.js';
+import { inferSchema, diffSchema, pushSchema, seedTables } from './schema.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
@@ -23,18 +30,22 @@ const AsyncFunction = (async () => {}).constructor;
 const json = (data, status = 200, headers = {}) =>
   new Response(JSON.stringify(data), { status, headers: { 'content-type': 'application/json', ...headers } });
 const dig = (obj, path) => String(path).split('.').reduce((o, k) => (o == null ? o : o[k]), obj);
+const escapeHtml = (s) => String(s)
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 
 // ── pages ──────────────────────────────────────────────────────────────
-const RESERVED_ROOT_DIRS = new Set(['components', 'api', 'public', 'pages', 'node_modules', 'dist', 'uploads']);
+const RESERVED_ROOT_DIRS = new Set(['components', 'api', 'public', 'pages', 'node_modules', 'dist', 'uploads', 'seed']);
 const RESERVED_FILES = new Set(['404.html', '500.html', 'middleware.html']);
 
-function scanPages(root) {
+export function scanPages(root) {
   const pagesDir = existsSync(join(root, 'pages')) ? join(root, 'pages') : root;
   const pages = [];
   (function scan(dir, prefix) {
     if (!existsSync(dir)) return;
     for (const f of readdirSync(dir)) {
-      if (f.startsWith('.')) continue;
+      // `_`-prefixed files are structure, not pages: _layout.html wraps the
+      // folder's pages instead of serving as one.
+      if (f.startsWith('.') || f.startsWith('_')) continue;
       const full = join(dir, f);
       const st = statSync(full);
       if (st.isDirectory()) {
@@ -83,25 +94,120 @@ function splitScript(html) {
   return { html: out, code: code.trim() };
 }
 
-// Parsed-page cache, invalidated by mtime.
-function pageData(page, cache) {
-  const mtime = statSync(page.file).mtimeMs;
-  const hit = cache.get(page.file);
-  if (hit && hit.mtime === mtime) return hit;
-  const source = readFileSync(page.file, 'utf8');
+// One page-or-layout file, parsed. Analyze BEFORE lifting the head, so a
+// {var} used only in <title>/<meta> still registers as a data need.
+function parseFile(source) {
   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);
+  const forms = extractForms(markup);
+  const { head, scripts, body } = liftHead(markup);
+  return { blocks, code, analysis, forms, head, scripts, body };
+}
+
+// Layouts: every _layout.html from the pages root down to the page's folder,
+// outermost first. A layout is a component the folder wraps around its pages;
+// <slot> is the page.
+function layoutChain(pageFile, pagesDir) {
+  const rel = relative(pagesDir, dirname(pageFile));
+  const parts = rel === '' || rel === '.' ? [] : rel.split(sep);
+  const chain = [];
+  let dir = pagesDir;
+  const rootLayout = join(dir, '_layout.html');
+  if (existsSync(rootLayout)) chain.push(rootLayout);
+  for (const p of parts) {
+    dir = join(dir, p);
+    const f = join(dir, '_layout.html');
+    if (existsSync(f)) chain.push(f);
+  }
+  return chain;
+}
+
+// Head merge: layout tags first, page tags after — and the page wins on
+// conflicts (<title>, <meta> with the same name/property). <link>s stack.
+function mergeHeads(parts) {
+  const out = new Map();
+  let n = 0;
+  for (const part of parts) {
+    for (const line of String(part || '').split('\n')) {
+      const tag = line.trim();
+      if (!tag) continue;
+      let key = null;
+      if (/^<title\b/i.test(tag)) key = 'title';
+      else {
+        const nm = tag.match(/\b(?:name|property|http-equiv)\s*=\s*["']([^"']+)["']/i);
+        if (/^<meta\b/i.test(tag) && nm) key = 'meta:' + nm[1].toLowerCase();
+      }
+      out.set(key || 'x' + n++, tag);
+    }
+  }
+  return [...out.values()].join('\n');
+}
+
+// Client scripts merge: a layout and a page may both pull the same module —
+// ship it once.
+function mergeScripts(parts) {
+  const seen = new Set();
+  const out = [];
+  for (const part of parts) {
+    for (const tag of String(part || '').split('\n')) {
+      const t = tag.trim();
+      if (!t || seen.has(t)) continue;
+      seen.add(t);
+      out.push(t);
+    }
+  }
+  return out.join('\n');
+}
+
+// Parsed-page cache, invalidated by mtime — the page's AND its layouts'.
+function pageData(page, cache, pagesDir) {
+  const files = [...layoutChain(page.file, pagesDir), page.file];
+  const stamps = files.map((f) => ({ file: f, mtime: statSync(f).mtimeMs }));
+  const hit = cache.get(page.file);
+  if (hit && hit.files.length === stamps.length
+    && hit.files.every((s, i) => s.file === stamps[i].file && s.mtime === stamps[i].mtime)) return hit;
+
+  const parsed = files.map((f) => parseFile(readFileSync(f, 'utf8')));
+  const pageP = parsed[parsed.length - 1];
+
+  // Compose bodies innermost-out: the page replaces each layout's <slot>.
+  let body = pageP.body;
+  for (let i = parsed.length - 2; i >= 0; i--) {
+    const lay = parsed[i].body;
+    const SLOT = /<slot\b[^>]*>(?:\s*<\/slot>)?/i;
+    body = SLOT.test(lay) ? lay.replace(SLOT, () => body) : lay + body;
+  }
+
+  const blocks = parsed.flatMap((p) => p.blocks);
+  const code = parsed.map((p) => p.code).filter(Boolean).join('\n');
+  const analysis = mergeAnalyses(parsed.map((p) => p.analysis));
   analysis.hasScript = !!code;
   const plan = dataPlan(analysis, blocks);
-  const { head, scripts, body } = liftHead(markup);
-  const data = { mtime, source, blocks, html: body, head, scripts, code, analysis, plan };
+  const forms = parsed.flatMap((p) => p.forms);
+  const head = mergeHeads(parsed.map((p) => p.head));
+  const scripts = mergeScripts(parsed.map((p) => p.scripts));
+
+  const data = { files: stamps, blocks, html: body, head, scripts, code, analysis, plan, forms };
   cache.set(page.file, data);
   return data;
 }
 
+// The schema/CLI entry: scan a project the same way serve() does and infer
+// its schema — `bun spark-ssr db` runs on this.
+export async function projectSchema(root) {
+  const config = loadConfig(root);
+  const db = await connect(config.db, root);
+  const { pagesDir, pages } = scanPages(root);
+  const cache = new Map();
+  const pds = [];
+  for (const p of pages) {
+    try { pds.push(pageData(p, cache, pagesDir)); } catch { /* broken page — skip */ }
+  }
+  const schema = inferSchema(pds, config, root);
+  return { config, db, schema };
+}
+
 // ── sessions ───────────────────────────────────────────────────────────
 const b64 = (buf) => Buffer.from(buf).toString('base64url');
 function signSession(payload, secret) {
@@ -128,17 +234,22 @@ function readSession(cookieHeader, secret) {
 const SESSION_COOKIE = (value, clear = false) =>
   `spark_session=${clear ? '' : value}; Path=/; HttpOnly; SameSite=Lax${clear ? '; Max-Age=0' : ''}`;
 
+// Roles in one column: an is_admin (or role) column on the auth table
+// unlocks guard="session.is_admin" and unscoped reads for admins.
+const isAdmin = (s) => !!s && (s.is_admin === 1 || s.is_admin === true || s.role === 'admin');
+
 // ── serve ──────────────────────────────────────────────────────────────
 export async function serve(options = {}) {
   const root = resolve(options.root || process.cwd());
   const config = { ...loadConfig(root), ...(options.config || {}) };
-  const db = await connect(config.db);
+  const db = await connect(config.db, root);
   const secret = (config.auth && config.auth.secret) || randomBytes(32).toString('hex');
   const cache = new Map();
   const pages = [];
   let pagesDir = root;
   const uploadsDir = join(root, config.uploads);
   const quiet = !!options.quiet;
+  const log = quiet ? () => {} : (m) => console.log(`[spark-ssr] ${m}`);
 
   const ctx = { port: 0 };
 
@@ -167,7 +278,7 @@ export async function serve(options = {}) {
           let st;
           try { st = statSync(full); } catch { continue; }
           if (st.isDirectory()) { walk(full); continue; }
-          if (!/\.(html|css|js|json)$/.test(f)) continue;
+          if (!/\.(html|css|js|json|md)$/.test(f)) continue;
           seen.add(full);
           if (mtimes.get(full) !== st.mtimeMs) { mtimes.set(full, st.mtimeMs); changed = true; }
         }
@@ -189,6 +300,22 @@ export async function serve(options = {}) {
   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>';
 
+  // ── live data channel (§9) — a production feature, unlike dev reload ──
+  // Any write through the server pings /__spark/live with the table name;
+  // hydrated pages refetch through their own session (scoping intact) and
+  // the source cache drops entries that read the table.
+  const liveTables = new Set();
+  const liveClients = new Set();
+  const sourceCache = makeSourceCache();
+  function broadcast(table) {
+    sourceCache.invalidate(table);
+    if (!liveTables.has(table)) return;
+    for (const c of liveClients) {
+      try { c.enqueue(sseEnc.encode('data: ' + table + '\n\n')); } catch { liveClients.delete(c); }
+    }
+  }
+  const broadcastSql = (sql) => { for (const t of sqlTables(sql)) broadcast(t); };
+
   // ── 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
@@ -224,6 +351,10 @@ export async function serve(options = {}) {
     }
   }
 
+  // spark-html-image, at write time (Tier 3): uploaded rasters get a webp
+  // sibling, and :file.url points at it (original stays as :file.original).
+  const uploadWebp = familyDeps.includes('spark-html-image');
+
   // ── request wrapper ──
   function wrapReq(request, url, params, session, server) {
     const headers = {};
@@ -267,7 +398,15 @@ export async function serve(options = {}) {
             const name = randomUUID() + ext;
             mkdirSync(uploadsDir, { recursive: true });
             await Bun.write(join(uploadsDir, name), v);
-            file = { url: '/uploads/' + name, name: v.name || name, size: v.size, type: v.type };
+            file = { url: '/uploads/' + name, original: '/uploads/' + name, name: v.name || name, size: v.size, type: v.type };
+            if (uploadWebp && /\.(png|jpe?g)$/i.test(name)) {
+              try {
+                const sharp = (await import('sharp')).default;
+                const webpName = name.replace(/\.\w+$/, '.webp');
+                await sharp(join(uploadsDir, name)).webp({ quality: 82 }).toFile(join(uploadsDir, webpName));
+                file.url = '/uploads/' + webpName;
+              } catch { /* sharp unavailable — original serves fine */ }
+            }
             fields[k] = file.url;
           } else {
             fields[k] = v;
@@ -290,11 +429,17 @@ export async function serve(options = {}) {
     return null;
   }
 
-  async function runSql(sqlText, req) {
+  async function runSql(sqlText, req, ttl = 0) {
     const { sql, tokens } = rewriteParams(sqlText);
     const values = [];
     for (const t of tokens) values.push(await resolveToken(t, req));
-    return db.query(sql, values);
+    if (!ttl) return db.query(sql, values);
+    const key = 'q|' + sql + '|' + JSON.stringify(values);
+    const hit = sourceCache.get(key);
+    if (hit) return hit.value;
+    const rows = await db.query(sql, values);
+    sourceCache.set(key, rows, ttl, sqlTables(sqlText));
+    return rows;
   }
 
   // ── auto-CRUD for <spark-ssr table="…"> ──
@@ -302,6 +447,11 @@ export async function serve(options = {}) {
   const on = (method, path, handler) =>
     apiRoutes.push({ method, segs: path.split('/').filter(Boolean), handler });
 
+  // Block attributes per table (limit, search, live) and the form-derived
+  // validation rules (§6) — both refreshed with the pages.
+  const tableOpts = new Map();
+  let validators = new Map();
+
   async function tableInfo(table) {
     const cols = await db.columns(table);
     const names = cols.map((c) => c.name);
@@ -309,13 +459,39 @@ export async function serve(options = {}) {
     return { cols, names, scoped };
   }
 
-  async function tableRows(table, req) {
-    const { scoped } = await tableInfo(table);
+  // List conventions (§10): ?page → LIMIT/OFFSET (+ .total/.pages on the
+  // array), ?sort=col:dir validated against real columns, ?q across the
+  // block's search="…" columns. Admins read unscoped (Tier 3 roles).
+  async function tableRows(table, req, opts = {}) {
+    const { names, scoped } = await tableInfo(table);
+    const where = [];
+    const values = [];
     if (scoped) {
       if (!req.session) return [];
-      return db.query(`SELECT * FROM ${table} WHERE user_id = ?`, [req.session.id]);
+      if (!isAdmin(req.session)) { where.push('user_id = ?'); values.push(req.session.id); }
+    }
+    if (opts.search && req.query.q) {
+      const cols = opts.search.filter((c) => names.includes(c));
+      if (cols.length) {
+        where.push('(' + cols.map((c) => `${c} LIKE ?`).join(' OR ') + ')');
+        for (const c of cols) { values.push('%' + req.query.q + '%'); void c; }
+      }
     }
-    return db.query(`SELECT * FROM ${table}`);
+    const whereSql = where.length ? ' WHERE ' + where.join(' AND ') : '';
+    let sql = `SELECT * FROM ${table}` + whereSql;
+    const sm = String(req.query.sort || '').match(/^(\w+)(?::(asc|desc))?$/i);
+    if (sm && names.includes(sm[1])) sql += ` ORDER BY ${sm[1]} ${(sm[2] || 'asc').toUpperCase()}`;
+    const paged = req.query.page !== undefined || opts.limit;
+    if (!paged) return db.query(sql, values);
+    const size = opts.limit || 20;
+    const pageN = Math.max(1, Number(req.query.page) || 1);
+    const totalRows = await db.query(`SELECT COUNT(*) AS n FROM ${table}` + whereSql, values);
+    const total = Number(totalRows[0]?.n ?? 0);
+    const rows = [...await db.query(sql + ` LIMIT ${size} OFFSET ${(pageN - 1) * size}`, values)];
+    rows.total = total;
+    rows.pages = Math.max(1, Math.ceil(total / size));
+    rows.page = pageN;
+    return rows;
   }
 
   function registerTable(table) {
@@ -324,7 +500,7 @@ 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);
-      const rows = await tableRows(table, req);
+      const rows = await tableRows(table, req, tableOpts.get(table) || {});
       // 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);
@@ -335,6 +511,12 @@ export async function serve(options = {}) {
       const { names, scoped } = await tableInfo(table);
       if (scoped && !req.session) return json({ error: 'unauthorized' }, 401);
       const { fields } = await req.body();
+      // The markup's constraint attributes are the validation spec (§6).
+      const rules = validators.get(table);
+      if (rules) {
+        const errors = validateFields(rules, fields);
+        if (errors) return json({ errors }, 422);
+      }
       const data = {};
       for (const [k, v] of Object.entries(fields)) {
         if (names.includes(k) && k !== 'id' && k !== 'user_id') data[k] = v;
@@ -350,6 +532,7 @@ export async function serve(options = {}) {
         `INSERT INTO ${table} (${keys.join(', ')}) VALUES (${keys.map(() => '?').join(', ')}) RETURNING *`,
         keys.map((k) => data[k]),
       );
+      broadcast(table);
       const row = rows[0] ?? { ok: true };
       if (isAuthTable && row.password) delete row.password;
       return json(row, 201);
@@ -365,6 +548,11 @@ export async function serve(options = {}) {
       if (scoped && !req.session) return json({ error: 'unauthorized' }, 401);
       if (ownAccountOnly(req)) return json({ error: 'unauthorized' }, 401);
       const { fields } = await req.body();
+      const rules = validators.get(table);
+      if (rules) {
+        const errors = validateFields(rules, fields, { partial: true });
+        if (errors) return json({ errors }, 422);
+      }
       const data = {};
       for (const [k, v] of Object.entries(fields)) {
         if (names.includes(k) && k !== 'id' && k !== 'user_id') data[k] = v;
@@ -376,8 +564,9 @@ export async function serve(options = {}) {
       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); }
+      if (scoped && !isAdmin(req.session)) { sql += ' AND user_id = ?'; values.push(req.session.id); }
       const rows = await db.query(sql + ' RETURNING *', values);
+      broadcast(table);
       const row = rows[0];
       if (isAuthTable && row) delete row.password;
       return row ? json(row) : json({ error: 'not found' }, 404);
@@ -389,8 +578,9 @@ export async function serve(options = {}) {
       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); }
+      if (scoped && !isAdmin(req.session)) { sql += ' AND user_id = ?'; values.push(req.session.id); }
       const rows = await db.query(sql + ' RETURNING *', values);
+      broadcast(table);
       return rows[0] ? json({ ok: true }) : json({ error: 'not found' }, 404);
     });
   }
@@ -409,6 +599,9 @@ export async function serve(options = {}) {
       : stored !== '' && stored === supplied);
     if (!ok) return json({ error: 'invalid credentials' }, 401);
     const session = { id: user.id, [identity]: user[identity] };
+    // Roles ride in the session: is_admin / role columns, when they exist.
+    if ('is_admin' in user) session.is_admin = user.is_admin;
+    if ('role' in user) session.role = user.role;
     const safe = { ...user };
     delete safe.password;
     return json(safe, 200, { 'set-cookie': SESSION_COOKIE(signSession(session, secret)) });
@@ -421,6 +614,8 @@ export async function serve(options = {}) {
       const user = await authPlugin.login(req);
       if (!user) return json({ error: 'invalid credentials' }, 401);
       const session = { id: user.id, email: user.email, name: user.name };
+      if (user.is_admin !== undefined) session.is_admin = user.is_admin;
+      if (user.role !== undefined) session.role = user.role;
       return json(user, 200, { 'set-cookie': SESSION_COOKIE(signSession(session, secret)) });
     });
   }
@@ -435,8 +630,8 @@ export async function serve(options = {}) {
   function registerQuery(route) {
     const key = route.method + ' ' + route.path;
     const existing = queryDefs.get(key);
-    if (existing) { existing.sql = route.sql; return; }
-    const def = { sql: route.sql };
+    if (existing) { existing.sql = route.sql; existing.cache = route.cache || 0; return; }
+    const def = { sql: route.sql, cache: route.cache || 0 };
     queryDefs.set(key, def);
     const segs = route.path.split('/').filter(Boolean)
       .map((s) => s.replace(/^\[(\w+)\]$/, ':$1'));
@@ -444,7 +639,8 @@ export async function serve(options = {}) {
       method: route.method,
       segs,
       handler: async (req) => {
-        const rows = await runSql(def.sql, req);
+        const rows = await runSql(def.sql, req, route.method === 'GET' ? def.cache : 0);
+        if (route.method !== 'GET') broadcastSql(def.sql);
         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 });
@@ -456,6 +652,8 @@ 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();
+  const seedFiles = new Set(); // never served as static assets
+  let schemaDirty = false;
   // 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.
@@ -467,18 +665,59 @@ export async function serve(options = {}) {
     const scanned = scanPages(root);
     pagesDir = scanned.pagesDir;
     pages.splice(0, pages.length, ...scanned.pages);
+    const nextValidators = new Map();
     for (const page of pages) {
       let pd;
-      try { pd = pageData(page, cache); } catch { continue; }
+      try { pd = pageData(page, cache, pagesDir); } catch { continue; }
       for (const b of pd.blocks) {
-        if (b.table && !tables.has(b.table)) { tables.add(b.table); registerTable(b.table); }
+        if (b.table) {
+          if (!tables.has(b.table)) { tables.add(b.table); registerTable(b.table); schemaDirty = true; }
+          if (b.live) liveTables.add(b.table);
+          if (b.seed) {
+            seedFiles.add(resolve(root, b.seed.replace(/^\.\//, '')));
+            schemaDirty = schemaDirty || !seededOnce.has(b.table);
+          }
+          const opts = tableOpts.get(b.table) || {};
+          if (b.limit) opts.limit = b.limit;
+          if (b.search) opts.search = b.search;
+          if (b.cache) opts.cache = b.cache;
+          tableOpts.set(b.table, opts);
+        }
         for (const r of b.routes) {
-          if (r.path) registerQuery(r);
+          if (r.path) registerQuery({ ...r, cache: b.cache });
         }
       }
+      for (const form of pd.forms) {
+        if (!form.table) continue;
+        const rules = nextValidators.get(form.table) || {};
+        Object.assign(rules, form.fields);
+        nextValidators.set(form.table, rules);
+      }
+    }
+    validators = nextValidators;
+  }
+  // The template is the schema (§7): at startup (and whenever a new table
+  // appears in dev) missing tables are created and seeds applied — a fresh
+  // clone runs on `bun spark-ssr` alone. Alters stay explicit: `db push`.
+  const seededOnce = new Set();
+  async function ensureSchema() {
+    if (!db) { schemaDirty = false; return; }
+    const pds = [];
+    for (const p of pages) {
+      try { pds.push(pageData(p, cache, pagesDir)); } catch { /* skip */ }
+    }
+    const schema = inferSchema(pds, config, root);
+    try {
+      await pushSchema(db, schema, { createOnly: true, log: (m) => log(`db: ${m}`) });
+      await seedTables(db, schema, config, root, (m) => log(`db: ${m}`));
+      for (const t of Object.keys(schema)) seededOnce.add(t);
+    } catch (e) {
+      if (!quiet) console.warn(`[spark-ssr] schema: ${e.message}`);
     }
+    schemaDirty = false;
   }
   refreshPages();
+  await ensureSchema();
 
   // ── api/ folder — custom endpoints ──
   function makeAppFetch(req) {
@@ -522,7 +761,7 @@ export async function serve(options = {}) {
         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 });
+          for (const r of b.routes) registerQuery({ ...r, path: r.path || route, cache: b.cache });
         }
         def.fn = null;
         if (code) {
@@ -620,8 +859,9 @@ export async function serve(options = {}) {
     const ext = extname(rel);
     // 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.
+    // lockfiles, databases, dotfiles, seed data. public/ stays intentional.
     const internal = rel.startsWith('.') || rel.includes('/.')
+      || rel.startsWith('seed/')
       || ['spark.json', 'package.json', 'bun.lock', 'bun.lockb', 'package-lock.json'].includes(rel)
       || ['.db', '.sqlite', '.sqlite3'].includes(ext);
     if (!internal && ext && ext !== '.html') {
@@ -632,6 +872,7 @@ export async function serve(options = {}) {
     for (const file of candidates) {
       const abs = resolve(file);
       if (!abs.startsWith(root)) continue;
+      if (seedFiles.has(abs)) continue;
       if (existsSync(abs) && statSync(abs).isFile()) return Bun.file(abs);
     }
     return null;
@@ -647,6 +888,7 @@ export async function serve(options = {}) {
     try { return await fn(req, db, makeAppFetch(req)); }
     catch (e) {
       if (!quiet) console.warn(`[spark-ssr] page <script> threw: ${e.message}`);
+      if (live) e.__sparkPageScript = true;
       return {};
     }
   }
@@ -656,6 +898,22 @@ export async function serve(options = {}) {
       && pd.blocks.some((b) => b.table) && !!db;
   }
 
+  // Open Graph completeness (Tier 3): og:title / og:description derive from
+  // the lifted <title> and description unless the page overrides them.
+  function withOgTags(head) {
+    let out = head;
+    const title = (head.match(/<title[^>]*>([\s\S]*?)<\/title>/i) || [])[1];
+    const desc = (head.match(/<meta\b[^>]*\bname\s*=\s*["']description["'][^>]*\bcontent\s*=\s*["']([^"']*)["']/i) || [])[1]
+      || (head.match(/<meta\b[^>]*\bcontent\s*=\s*["']([^"']*)["'][^>]*\bname\s*=\s*["']description["']/i) || [])[1];
+    if (title && !/property\s*=\s*["']og:title/i.test(head)) {
+      out += `\n<meta property="og:title" content="${title.trim()}">`;
+    }
+    if (desc && !/property\s*=\s*["']og:description/i.test(head)) {
+      out += `\n<meta property="og:description" content="${desc}">`;
+    }
+    return out;
+  }
+
   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';
@@ -703,38 +961,107 @@ export async function serve(options = {}) {
     return `<!doctype html>\n<html>\n<head>\n${head}</head>\n<body>\n${host}\n${reload}</body>\n</html>\n`;
   }
 
+  // Resolve one plan entry — table, query, named SQL, URL, glob, module —
+  // honoring the block's cache="…" TTL.
+  async function resolveSource(p, req) {
+    const src = p.source;
+    const ttl = (src.opts && src.opts.cache) || 0;
+    if (src.kind === 'table') {
+      if (!ttl) return tableRows(src.table, req, src.opts || {});
+      const key = ['t', src.table, req.session?.id ?? '', req.query.q ?? '', req.query.sort ?? '', req.query.page ?? ''].join('|');
+      const hit = sourceCache.get(key);
+      if (hit) return hit.value;
+      const rows = await tableRows(src.table, req, src.opts || {});
+      sourceCache.set(key, rows, ttl, new Set([src.table]));
+      return rows;
+    }
+    if (src.kind === 'query' || src.kind === 'sql') {
+      const sql = src.kind === 'query' ? src.route.sql : src.binding.sql;
+      const rows = await runSql(sql, req, ttl);
+      return p.shape === 'list' ? [...rows] : rows[0] ?? null;
+    }
+    if (src.kind === 'url') {
+      const key = 'u|' + src.binding.value + '|' + JSON.stringify(req.params) + '|' + (req.query.q ?? '');
+      if (ttl) {
+        const hit = sourceCache.get(key);
+        if (hit) return hit.value;
+      }
+      const value = await urlSource(src.binding.value, req);
+      if (ttl) sourceCache.set(key, value, ttl);
+      return value;
+    }
+    if (src.kind === 'glob') {
+      const key = 'g|' + src.binding.value;
+      if (ttl) {
+        const hit = sourceCache.get(key);
+        if (hit) return hit.value;
+      }
+      const value = globSource(src.binding.value, root);
+      if (ttl) sourceCache.set(key, value, ttl);
+      return value;
+    }
+    if (src.kind === 'module') {
+      return moduleSource(src.binding.value, root, req, db, { watch: live });
+    }
+    return null;
+  }
+
   async function buildScope(pd, req) {
     const scope = { ...req.query, ...req.params, session: req.session };
     if (pd.code) Object.assign(scope, await runPageScript(pd.code, req));
     for (const p of pd.plan) {
       if (scope[p.var] !== undefined) continue; // the page <script> won
-      if (p.source.kind === 'table') {
-        scope[p.var] = await tableRows(p.source.table, req);
-      } else {
-        const rows = await runSql(p.source.route.sql, req);
-        scope[p.var] = p.shape === 'list' ? [...rows] : rows[0] ?? null;
-      }
+      scope[p.var] = await resolveSource(p, req);
     }
     return scope;
   }
 
-  async function servePage(page, req) {
-    const pd = pageData(page, cache);
+  // The dev banner for the silent-blank class of bug: "this page reads
+  // {posts} but no source provides it — nearest source: published".
+  function unresolvedBanner(unresolved) {
+    const items = unresolved.map((u) =>
+      `<code>{${escapeHtml(u.name)}}</code>${u.nearest ? ` — nearest source: <code>${escapeHtml(u.nearest)}</code>` : ''}`).join('; ');
+    return '<div style="position:fixed;bottom:0;left:0;right:0;background:#7c2d12;color:#fed7aa;'
+      + 'font:13px/1.6 monospace;padding:8px 14px;z-index:99999">'
+      + `spark-ssr: this page reads ${items} but no source provides it</div>`;
+  }
+
+  async function servePage(page, req, extra = null) {
+    const pd = pageData(page, cache, pagesDir);
     const scope = await buildScope(pd, req);
+    if (extra) Object.assign(scope, extra.scope || {});
+
+    // Declarative guard (§3): <spark-ssr guard="session" redirect="/login" />
+    for (const b of pd.blocks) {
+      if (!b.guard) continue;
+      if (!evalExpr(b.guard, scope)) {
+        if (b.redirect) return new Response(null, { status: 303, headers: { location: b.redirect } });
+        return errorPage(b.status || 403);
+      }
+    }
+
     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, {
+    const rctx = { loadComponent, keepImports: !hydrate };
+    const body = await renderFragment(pd.html, scope, rctx);
+    let headExtra = pd.head ? renderHead(pd.head, (e) => evalExpr(e, scope)) : '';
+    if (headExtra) headExtra = withOgTags(headExtra);
+    let html = shell(page, body, {
       hydrate, mount: hydrate || hasComponents, headExtra, scripts: pd.scripts,
-    }), {
+    });
+    if (live && pd.plan.unresolved && pd.plan.unresolved.length) {
+      html = html.replace('</body>', unresolvedBanner(pd.plan.unresolved) + '\n</body>');
+    }
+    return new Response(html, {
+      status: (extra && extra.status) || rctx.status || 200,
       headers: { 'content-type': 'text/html; charset=utf-8' },
     });
   }
 
+  const STATUS_TEXT = { 401: 'Unauthorized', 403: 'Forbidden', 404: 'Not found' };
   function errorPage(status) {
     const file = join(root, `${status}.html`);
     if (existsSync(file)) {
@@ -742,7 +1069,122 @@ export async function serve(options = {}) {
       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 });
+    return new Response(STATUS_TEXT[status] || 'Server error', { status });
+  }
+
+  // Dev-only error overlay (§4): the real error — SQL, file, line — on the
+  // page instead of a bare 500. The reload client rides along, so fixing the
+  // file un-sticks the browser.
+  function devErrorPage(e, pathname) {
+    const body = '<!doctype html><html><head><title>spark-ssr error</title></head>'
+      + '<body style="background:#1c1917;color:#fafaf9;font:15px/1.6 system-ui;padding:2rem">'
+      + `<h1 style="color:#fca5a5">500 — ${escapeHtml(e.message || String(e))}</h1>`
+      + `<p style="color:#a8a29e">while serving <code>${escapeHtml(pathname)}</code></p>`
+      + `<pre style="background:#292524;padding:1rem;border-radius:8px;overflow:auto;color:#fdba74">${escapeHtml(e.stack || '')}</pre>`
+      + RELOAD_CLIENT + '</body></html>';
+    return new Response(body, { status: 500, headers: { 'content-type': 'text/html; charset=utf-8' } });
+  }
+
+  // /__spark/plan (§4): "view source" for the inferred backend — every route,
+  // its var → source bindings, tables, endpoints. Dev only.
+  function planPage() {
+    const esc = escapeHtml;
+    const srcLabel = (s) =>
+      s.kind === 'table' ? `table ${s.table}`
+      : s.kind === 'query' ? `${s.route.method} ${s.route.path} — ${s.route.sql.replace(/\s+/g, ' ')}`
+      : s.kind === 'sql' ? `SQL — ${s.binding.sql.replace(/\s+/g, ' ')}`
+      : `${s.kind} — ${s.binding.value}`;
+    let rows = '';
+    for (const page of pages) {
+      let pd;
+      try { pd = pageData(page, cache, pagesDir); } catch { continue; }
+      const vars = pd.plan.map((p) => `<code>${esc(p.var)}</code> ← ${esc(srcLabel(p.source))} <em>(${p.shape})</em>`).join('<br>');
+      const un = (pd.plan.unresolved || []).map((u) => `<code>{${esc(u.name)}}</code> unresolved`).join('<br>');
+      const guards = pd.blocks.filter((b) => b.guard)
+        .map((b) => `guard <code>${esc(b.guard)}</code>${b.redirect ? ` → ${esc(b.redirect)}` : ''}`).join('<br>');
+      rows += `<tr><td><code>${esc(page.route)}</code></td><td>${esc(relative(root, page.file))}</td>`
+        + `<td>${vars}${un ? '<br><span style="color:#f87171">' + un + '</span>' : ''}${guards ? '<br>' + guards : ''}</td></tr>\n`;
+    }
+    const endpoints = apiRoutes.map((r) => `<li><code>${esc(r.method)} /${esc(r.segs.join('/'))}</code></li>`).join('\n');
+    const tbls = [...tables].map((t) => `<code>${esc(t)}${liveTables.has(t) ? ' (live)' : ''}</code>`).join(', ');
+    const body = `<!doctype html><html><head><title>spark-ssr plan</title>
+<style>body{font:15px/1.6 system-ui;max-width:70rem;margin:2rem auto;padding:0 1rem;background:#1c1917;color:#fafaf9}
+table{border-collapse:collapse;width:100%}td,th{border:1px solid #44403c;padding:.5rem;text-align:left;vertical-align:top}
+code{color:#fdba74}em{color:#a8a29e}</style></head><body>
+<h1>⚡ The inferred backend</h1>
+<p>Tables: ${tbls || '<em>none</em>'}</p>
+<table><tr><th>Route</th><th>File</th><th>Data plan</th></tr>${rows}</table>
+<h2>Endpoints</h2><ul>${endpoints}</ul>
+</body></html>`;
+    return new Response(body, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+  }
+
+  // ── SEO (Tier 3): sitemap.xml + robots.txt, generated when not authored ──
+  function indexablePages() {
+    const out = [];
+    for (const page of pages) {
+      let pd;
+      try { pd = pageData(page, cache, pagesDir); } catch { continue; }
+      const noindex = /<meta\b[^>]*\bname\s*=\s*["']robots["'][^>]*\bcontent\s*=\s*["'][^"']*noindex/i.test(pd.head)
+        || /<meta\b[^>]*\bcontent\s*=\s*["'][^"']*noindex[^"']*["'][^>]*\bname\s*=\s*["']robots["']/i.test(pd.head);
+      const guarded = pd.blocks.some((b) => b.guard);
+      out.push({ page, pd, noindex, guarded });
+    }
+    return out;
+  }
+
+  // Enumerate a [param] route's values by re-running its bound query with the
+  // param comparison neutralized (`slug = :slug` → `slug = slug`) and every
+  // other token null — spark-prerender's route-enumeration idea, DB-backed.
+  async function enumerateParam(sql, param) {
+    const cmp = new RegExp(`([a-zA-Z_]\\w*)\\s*=\\s*:${param}\\b`);
+    const cm = String(sql).match(cmp);
+    if (!cm) return [];
+    const col = cm[1];
+    const neutral = String(sql).replace(cmp, '$1 = $1').replace(/\blimit\s+\d+\b/i, '');
+    const { sql: rewritten, tokens } = rewriteParams(neutral);
+    const rows = await db.query(rewritten, tokens.map(() => null));
+    return [...new Set([...rows].map((r) => r[col]).filter((v) => v != null))];
+  }
+
+  async function sitemapXml(origin) {
+    const urls = [];
+    for (const { page, pd, noindex, guarded } of indexablePages()) {
+      if (noindex || guarded) continue;
+      const params = page.segs.filter((s) => s.startsWith('['));
+      if (!params.length) { urls.push(page.route); continue; }
+      if (params.length > 1) continue;
+      const param = params[0].slice(1, -1);
+      let vals = [];
+      const bound = pd.plan.find((p) =>
+        (p.source.kind === 'query' && p.source.route.sql.includes(':' + param))
+        || (p.source.kind === 'sql' && p.source.binding.sql.includes(':' + param)));
+      if (bound && db) {
+        const sql = bound.source.kind === 'query' ? bound.source.route.sql : bound.source.binding.sql;
+        try { vals = await enumerateParam(sql, param); } catch { /* dynamic route stays out */ }
+      } else {
+        const glob = pd.plan.find((p) => p.source.kind === 'glob');
+        if (glob) vals = globSource(glob.source.binding.value, root).map((r) => r.slug);
+      }
+      for (const v of vals) urls.push(page.route.replace(`[${param}]`, encodeURIComponent(String(v))));
+    }
+    const xml = '<?xml version="1.0" encoding="UTF-8"?>\n'
+      + '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n'
+      + urls.map((u) => `  <url><loc>${origin}${escapeHtml(u)}</loc></url>`).join('\n')
+      + '\n</urlset>\n';
+    return new Response(xml, { headers: { 'content-type': 'application/xml' } });
+  }
+
+  function robotsTxt(origin) {
+    const lines = ['User-agent: *'];
+    for (const { page, noindex, guarded } of indexablePages()) {
+      if ((noindex || guarded) && !page.segs.some((s) => s.startsWith('['))) {
+        lines.push(`Disallow: ${page.route}`);
+      }
+    }
+    if (lines.length === 1) lines.push('Disallow:');
+    lines.push(`Sitemap: ${origin}/sitemap.xml`);
+    return new Response(lines.join('\n') + '\n', { headers: { 'content-type': 'text/plain' } });
   }
 
   // spark-html + family packages, served as browser modules. The importmap
@@ -792,13 +1234,30 @@ export async function serve(options = {}) {
         });
       }
 
+      // The live data channel (§9) ships in production too — it's the app.
+      if (pathname === '/__spark/live') {
+        let ctrl;
+        const stream = new ReadableStream({
+          start(c) { ctrl = c; c.enqueue(sseEnc.encode(': connected\n\n')); liveClients.add(c); },
+          cancel() { liveClients.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(); }
+        if (options.watch !== false) {
+          refreshPages(); refreshApi(); refreshMiddleware();
+          if (schemaDirty) await ensureSchema();
+        }
+
+        if (live && pathname === '/__spark/plan') return planPage();
 
         // middleware.html runs first, on every request.
         if (middleware) {
@@ -841,10 +1300,14 @@ export async function serve(options = {}) {
           const key = pathname.slice('/__spark/page/'.length).replace(/\.html$/, '');
           const page = pages.find((p) => p.key === key);
           if (!page) return finish(errorPage(404));
-          const pd = pageData(page, cache);
-          const table = (pd.blocks.find((b) => b.table) || {}).table || null;
+          const pd = pageData(page, cache, pagesDir);
+          const tableBlock = pd.blocks.find((b) => b.table) || {};
+          const table = tableBlock.table || null;
           const cols = table ? await db.columns(table) : [];
-          const html = clientComponent({ html: pd.html, analysis: pd.analysis, plan: pd.plan, table, cols, key });
+          const html = clientComponent({
+            html: pd.html, analysis: pd.analysis, plan: pd.plan, table, cols, key,
+            live: !!(table && liveTables.has(table)),
+          });
           return finish(new Response(html, { headers: { 'content-type': 'text/html', 'cache-control': 'no-cache' } }));
         }
 
@@ -852,16 +1315,10 @@ export async function serve(options = {}) {
           const key = pathname.slice('/__spark/data/'.length).replace(/\.js$/, '');
           const page = pages.find((p) => p.key === key);
           if (!page) return finish(errorPage(404));
-          const pd = pageData(page, cache);
+          const pd = pageData(page, cache, pagesDir);
           const req = wrapReq(request, url, {}, session, srv);
           const data = {};
-          for (const p of pd.plan) {
-            if (p.source.kind === 'table') data[p.var] = await tableRows(p.source.table, req);
-            else {
-              const rows = await runSql(p.source.route.sql, req);
-              data[p.var] = p.shape === 'list' ? [...rows] : rows[0] ?? null;
-            }
-          }
+          for (const p of pd.plan) data[p.var] = await resolveSource(p, req);
           return finish(new Response(initModule(data), {
             headers: { 'content-type': 'text/javascript', 'cache-control': 'no-store' },
           }));
@@ -884,6 +1341,46 @@ export async function serve(options = {}) {
           if (!hit) return finish(json({ error: 'not found' }, 404, cors || {}));
           const req = wrapReq(request, url, hit.params, session, srv);
           const res = await hit.route.handler(req, { headers: {} });
+
+          // Answer a browser like a browser (§5): a plain form post that
+          // succeeded 303s back (the _redirect field or the referrer) — the
+          // app works with JavaScript disabled. A failed one re-renders the
+          // referring page with {errors} (and {values}) in scope.
+          const ct = request.headers.get('content-type') || '';
+          const isForm = request.method !== 'GET'
+            && (ct.includes('application/x-www-form-urlencoded') || ct.includes('multipart/form-data'));
+          const wantsHtml = (request.headers.get('accept') || '').includes('text/html');
+          if (isForm && wantsHtml) {
+            const { fields } = await req.body();
+            const referer = request.headers.get('referer');
+            let back = '/';
+            try { if (referer) { const r = new URL(referer); back = r.pathname + r.search; } } catch { /* keep / */ }
+            if (typeof fields._redirect === 'string' && fields._redirect.startsWith('/')) back = fields._redirect;
+            if (res.status < 400) {
+              const headers = new Headers({ location: back });
+              const sc = res.headers.get('set-cookie');
+              if (sc) headers.set('set-cookie', sc);
+              return finish(new Response(null, { status: 303, headers }));
+            }
+            let errors = null;
+            try {
+              const j = await res.clone().json();
+              errors = j.errors || (j.error ? { _: j.error } : null);
+            } catch { /* non-JSON error */ }
+            if (errors && referer) {
+              try {
+                const r = new URL(referer);
+                const rp = matchPage(pages, decodeURIComponent(r.pathname));
+                if (rp) {
+                  const rreq = wrapReq(request, r, rp.params, session, srv);
+                  return finish(await servePage(rp.page, rreq, {
+                    scope: { errors, values: fields }, status: res.status,
+                  }));
+                }
+              } catch { /* fall through to the raw response */ }
+            }
+          }
+
           if (cors) for (const [k, v] of Object.entries(cors)) res.headers.set(k, v);
           return finish(res);
         }
@@ -891,6 +1388,9 @@ export async function serve(options = {}) {
         const file = staticFile(pathname);
         if (file) return finish(new Response(file));
 
+        if (pathname === '/sitemap.xml') return finish(await sitemapXml(url.origin));
+        if (pathname === '/robots.txt') return finish(robotsTxt(url.origin));
+
         const hit = matchPage(pages, pathname);
         if (hit) {
           const req = wrapReq(request, url, hit.params, session, srv);
@@ -900,7 +1400,8 @@ export async function serve(options = {}) {
         return finish(errorPage(404));
       } catch (e) {
         if (!quiet) console.error(`[spark-ssr] ${request.method} ${pathname} — ${e.stack || e.message}`);
-        const res = errorPage(500);
+        const wantsHtml = (request.headers.get('accept') || '').includes('text/html');
+        const res = live && wantsHtml ? devErrorPage(e, pathname) : errorPage(500);
         for (const [k, v] of Object.entries(extraHeaders)) res.headers.set(k, v);
         return res;
       }
@@ -918,6 +1419,8 @@ export async function serve(options = {}) {
       if (watchTimer) clearInterval(watchTimer);
       for (const c of sseClients) { try { c.close(); } catch { /* gone */ } }
       sseClients.clear();
+      for (const c of liveClients) { try { c.close(); } catch { /* gone */ } }
+      liveClients.clear();
       server.stop(force);
       return db && db.close();
     },