spark-ssr 0.1.1 → 0.3.0

package/README.md

@@ -20,26 +20,31 @@ The framework reads the HTML template and infers everything:
   </template>
 </template>
 
-<spark-ssr table="todos" />
+<spark-ssr table="todos" live />
 ```
 
 ```bash
 bun spark-ssr
 ```
 
-That's it.
+That's it — the table is **created for you** (the template is the schema),
+the REST API exists, the page is server-rendered and hydrated, and `live`
+keeps every open tab in sync.
 
 | The template says                               | The framework knows                          |
 | ----------------------------------------------- | -------------------------------------------- |
 | `<template each="todo in todos">`               | You need data called `todos`                 |
 | `table="todos"`                                 | It's backed by the `todos` table             |
+| `{todo.title}` interpolation                    | `title` is a TEXT column                     |
+| `bind:checked="todo.done"`                      | `done` is a boolean column                   |
 | `onclick={add}` (outside the loop)              | `POST /api/todos` — insert                   |
-| `bind:checked="todo.done"` + `onchange={patch}` | `PATCH /api/todos/:id` — update `done`       |
+| `bind:checked` + `onchange={patch}` (in loop)   | `PATCH /api/todos/:id` — update `done`       |
 | `onclick={remove}` (inside the loop)            | `DELETE /api/todos/:id` — remove the row     |
 | `bind:value="draft"`                            | Local state variable `draft`                 |
 | `user_id` column in the table                   | Auth — `WHERE user_id = :session.id`         |
+| `required maxlength="120"` on a form input      | The server validates the same rules          |
 
-No `<script>`. No SQL. No ORM. No server file. No build step.
+No `<script>`. No SQL. No ORM. No server file. No setup.js. No build step.
 
 ## Config (spark.json)
 
@@ -47,13 +52,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
 
@@ -61,24 +69,207 @@ The filesystem is the router. `pages/index.html` → `/`,
 `pages/blog/[slug].html` → `/blog/:slug` (`:slug` binds into queries).
 Without a `pages/` folder, `*.html` at the project root serve the same way.
 
-## Explicit queries
+## Layouts — folders own their chrome
+
+`pages/_layout.html` wraps every page in the folder (nested folders nest
+their layouts). A layout is a component; `<slot>` is the page:
 
 ```html
-<!-- pages/search.html -->
-<h1>Results for "{q}"</h1>
-<template each="result in results">
-  <p>{result.title}</p>
-</template>
+<!-- pages/_layout.html -->
+<link rel="stylesheet" href="/style.css">
+<script type="module" src="/app.js"></script>
+<div import="/components/nav" blog="{author.name}"></div>
+<slot></slot>
+<footer>© {author.name}</footer>
 
 <spark-ssr>
-  GET /api/search → SELECT * FROM posts WHERE title LIKE '%' || :q || '%' LIMIT 20
+  author = SELECT id, name, bio FROM users LIMIT 1
+</spark-ssr>
+```
+
+The layout's `<spark-ssr>` vars are in scope for every page it wraps. Head
+tags lift from layout AND page; the page wins on conflicts.
+
+## Named data — the block says what it feeds
+
+```html
+<spark-ssr>
+  posts  = SELECT * FROM posts WHERE published = 1 ORDER BY created_at DESC
+  author = SELECT id, name, bio FROM users LIMIT 1
 </spark-ssr>
 ```
 
+`var = SELECT …` is page data with no endpoint exposed — what most pages
+actually want. Write `GET /api/posts → posts = SELECT …` when you also want
+a public endpoint. Name/singular/fallback matching still works for
+`table="…"` blocks and unnamed routes — nothing breaks.
+
 `:` params inject automatically: path params (`:slug`), query string (`:q`),
-JSON body (`:body.title`), session (`:session.id`), headers
+form/JSON body (`:body.title`), session (`:session.id`), headers
 (`:header.x-forwarded-for`), uploads (`:file.url`).
 
+## Sources beyond SQL — same block, more worlds
+
+```html
+<spark-ssr>
+  repo    = https://api.github.com/repos/wilkinnovo/spark-html
+  posts   = ./content/posts/*.md
+  weather = ./lib/weather.js
+</spark-ssr>
+```
+
+- **URL** — server-side fetch, JSON parsed; `:slug`-style params interpolate.
+- **Glob** — files become rows: front-matter → columns, body → `.body`,
+  filename → `.slug`. A blog with no database at all. (`{post.body}` renders
+  text; markdown rendering is a companion package's job.)
+- **Module** — default export `(req, db) => value`. The escape hatch gets a
+  declarative front door.
+
+## Status, redirect, and guard
+
+```html
+<!-- blog/[slug].html -->
+<template if="post"> … </template>
+<template else status="404"><h1>Not found</h1></template>
+
+<!-- admin/index.html -->
+<spark-ssr guard="session" redirect="/login" />
+```
+
+`status="…"` on a rendered branch sets the response status — crawlers stop
+indexing a 200-that-means-404. `guard="expr"`: when falsy, `redirect="…"`
+answers 303, `status="401"` sets the code, default 403. An `is_admin` (or
+`role`) column on the auth table rides into the session, so
+`guard="session.is_admin"` works — and admins read scoped tables unscoped.
+
+## Forms without JavaScript
+
+The auto-CRUD endpoints answer a browser like a browser:
+
+```html
+<form action="/api/posts" method="post" redirect="/admin">
+  <input name="title" required maxlength="120">
+  <textarea name="body"></textarea>
+  <button>Save draft</button>
+</form>
+```
+
+A plain form post that succeeds 303s back to the referrer (or the form's
+`redirect="…"`); the page re-renders with fresh data. **The app works with
+JavaScript disabled.** Login and logout are forms too:
+
+```html
+<form action="/api/users?auth" method="post">
+  <input type="email" name="email" required>
+  <input type="password" name="password" required>
+  <button>Sign in</button>
+</form>
+<form action="/api/logout" method="post"><button>Sign out</button></form>
+```
+
+### The form is the validator
+
+`required`, `maxlength`, `min`/`max`, `type="email"`, `pattern` — the
+constraint attributes you already wrote for the browser run again on the
+server before the matching auto-CRUD write. Violations answer `422` with
+`{ errors: { title: "…" } }` (JSON) or re-render the page with `{errors.title}`
+and `{values.title}` in scope (form post).
+
+## The template is the schema
+
+```bash
+bun spark-ssr db        # show inferred schema vs live DB (a diff)
+bun spark-ssr db push   # create/alter tables to match the templates
+```
+
+Column inference: `{todo.title}` → TEXT, `bind:checked` → boolean,
+`type="number"` inputs → numeric, `id`/`created_at` always, `user_id` when
+auth is configured and the page reads the session. Seed rows sharpen types:
+
+```html
+<spark-ssr table="todos" seed="./seed/todos.json" live />
+```
+
+Seeds apply once, idempotently (only into an empty table; auth-table
+passwords hash on the way in). `serve` runs the safe half automatically —
+missing tables are created and seeds applied at startup, so a fresh clone
+runs on `bun spark-ssr` alone. Columns are never dropped without
+`db push --force`. Seed files are never served as static assets.
+
+## `live` — HTML that reacts across the wire
+
+```html
+<spark-ssr table="todos" live />
+```
+
+Every write through the server pings `/__spark/live` (SSE) with the table
+name; hydrated pages refetch through their own session — every open tab
+updates, scoping intact. No socket code, no pub/sub. spark-html-websocket
+stays for custom protocols; `live` is the zero-config 90%.
+
+## Lists — `?page`, `?sort`, `?q`
+
+```html
+<spark-ssr table="recipes" limit="20" search="title,ingredients" />
+```
+
+- `?page=2` → `LIMIT/OFFSET`, plus `{recipes.total}` and `{recipes.pages}`.
+- `?sort=created_at:desc` → validated against real columns, then `ORDER BY`.
+- `?q=…` → `LIKE` across the block's `search="…"` columns.
+
+`cache="60"` on any block adds a per-source TTL, invalidated automatically
+when a table it reads from changes.
+
+## Dev tools
+
+- **Error overlay** — a failing query or throwing page script puts the real
+  error (message, stack) on the page instead of a bare 500.
+- **Unresolved-var banner** — "this page reads `{posts}` but no source
+  provides it — nearest source: `published`". The silent-blank bug becomes
+  a sentence.
+- **`/__spark/plan`** — every route, table, endpoint, and each page's
+  var → source bindings. "View source" for the inferred backend.
+- **Live reload** — every edit (pages, layouts, components, queries,
+  middleware, css, markdown) refreshes the browser via SSE.
+
+All dev-only; `start` and compiled builds ship none of it.
+
+## The page owns its \<head\> — and SEO comes free
+
+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
+<title>{post.title} · My Blog</title>
+<meta name="description" content="{post.excerpt}">
+```
+
+`og:title`/`og:description` derive from those unless overridden.
+`/sitemap.xml` is generated from the pages — `[param]` routes enumerate
+their bound query. `/robots.txt` honors `<meta name="robots" content="noindex">`
+and guards. Author your own files in `public/` to override any of it.
+
+## 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:
+
+```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/` — and uploads get a webp variant at write time (`:file.url` points
+at it; `:file.original` keeps the source file).
+
 ## Custom endpoints — api/
 
 `api/stats.html` auto-serves as `GET /api/stats`:
@@ -97,21 +288,31 @@ scope; the return value becomes the JSON response).
 - **Components** — `<div import="/components/card" title="{post.title}">`
   inlines at render time; components are pure UI.
 - **Auth** — built-in email/password sessions (`POST /api/users?auth` logs in,
-  passwords hash on insert), or a plugin (`auth.plugin` in spark.json).
+  passwords hash on insert), or a plugin (`auth.plugin` in spark.json) for
+  OAuth/magic-link flows — the plugin answers "who is this person?", the
+  framework still does sessions and cookies.
 - **Middleware** — `middleware.html` runs on every request (`req`, `res`,
   `rateLimit`, `state` in scope; return `{ status, body }` to short-circuit).
 - **Uploads** — multipart bodies stream to `uploads/`; `:file.url` binds the
   stored URL into your INSERT.
-- **Error pages** — `404.html` / `500.html` at the project root.
+- **Error pages** — `404.html` / `500.html` (any `<status>.html`) at the
+  project root.
 - **Static assets** — `public/` plus co-located page assets, served as-is.
+  Project internals (spark.json, package.json, `*.db`, seeds, 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.
+- **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
+bun spark-ssr build --docker   # …plus a Dockerfile: copy, run
+bun spark-ssr start            # run in production (watch + live reload off)
 ```
 
 MIT

package/bin/cli.js

@@ -4,6 +4,8 @@
  *
  *   bun spark-ssr                serve the current directory (default)
  *   bun spark-ssr --port 3000    pick a port
+ *   bun spark-ssr db             show the inferred schema vs the live DB
+ *   bun spark-ssr db push        create/alter tables to match the templates
  *   bun spark-ssr build          assemble dist/ (+ compiled binary)
  *   bun spark-ssr start          serve dist/ if built, else the project
  *
@@ -11,21 +13,27 @@
  *   --port <n>      Port (default 3000, or PORT env).
  *   --root <dir>    Project root (default cwd).
  *   --no-compile    build: skip the single-binary compile, copy only.
+ *   --docker        build: also emit a Dockerfile next to the binary.
+ *   --force         db push: drop columns the templates no longer name.
  *   -h, --help      Show this help.
  */
 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, projectSchema } from '../src/index.js';
+import { diffSchema, pushSchema, seedTables } from '../src/schema.js';
 
 function parseArgs(argv) {
-  const opts = { cmd: 'serve', compile: true };
+  const opts = { cmd: 'serve', compile: true, force: false, docker: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '-h' || a === '--help') opts.help = true;
     else if (a === '--port') opts.port = Number(argv[++i]);
     else if (a === '--root') opts.root = argv[++i];
     else if (a === '--no-compile') opts.compile = false;
-    else if (a === 'build' || a === 'start' || a === 'serve') opts.cmd = a;
+    else if (a === '--docker') opts.docker = true;
+    else if (a === '--force') opts.force = true;
+    else if (a === 'build' || a === 'start' || a === 'serve' || a === 'db') opts.cmd = a;
+    else if (a === 'push' && opts.cmd === 'db') opts.push = true;
     else if (a.startsWith('--')) { console.error(`Unknown option: ${a}`); process.exit(2); }
   }
   return opts;
@@ -35,22 +43,32 @@ const HELP = `spark-ssr — zero-config SSR for spark-html on Bun
 
 Usage:
   bun spark-ssr [serve] [--port <n>] [--root <dir>]
-  bun spark-ssr build [--no-compile]
+  bun spark-ssr db [push] [--force]
+  bun spark-ssr build [--no-compile] [--docker]
   bun spark-ssr start
 `;
 
-// 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'];
+// The project files a deployment needs — pages, components, api, seeds,
+// content, modules, public, error pages, middleware, config.
+// node_modules/dist/uploads stay behind. 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', 'seed', 'content', 'lib'];
 const SHIP_FILES = ['404.html', '500.html', 'middleware.html', 'spark.json', 'package.json'];
 
-async function build(root, compile) {
+async function build(root, { compile, docker }) {
   const dist = join(root, 'dist');
   rmSync(dist, { recursive: true, force: true });
   mkdirSync(dist, { recursive: true });
   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));
   }
@@ -59,7 +77,7 @@ async function build(root, compile) {
     for (const f of readdirSync(root)) {
       if (f === 'dist' || f === 'node_modules' || f.startsWith('.')) continue;
       const full = join(root, f);
-      if (statSync(full).isFile() && /\.(html|css|js|json|png|jpg|svg|ico|webp)$/.test(f)
+      if (statSync(full).isFile() && /\.(html|css|js|json|png|jpg|svg|ico|webp|md)$/.test(f)
         && !SHIP_FILES.includes(f)) {
         cpSync(full, join(dist, f));
       }
@@ -67,8 +85,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')],
@@ -77,6 +103,52 @@ async function build(root, compile) {
     if (r.exitCode !== 0) process.exit(r.exitCode);
     console.log('✓ compiled dist/app — run it from dist/ (reads pages/ next to it)');
   }
+  if (docker) {
+    // The deploy story: copy, run. The compiled binary needs only libc.
+    writeFileSync(join(dist, 'Dockerfile'), compile
+      ? 'FROM debian:stable-slim\nCOPY . /app\nWORKDIR /app\nEXPOSE 3000\nCMD ["/app/app"]\n'
+      : 'FROM oven/bun:1\nCOPY . /app\nWORKDIR /app\nRUN bun install --production\nEXPOSE 3000\nCMD ["bun", "__server.js"]\n');
+    console.log('✓ wrote dist/Dockerfile');
+  }
+}
+
+// The template is the schema (§7): show the diff, or make it so.
+async function dbCmd(root, { push, force }) {
+  const { db, config, schema } = await projectSchema(root);
+  if (!db) {
+    console.error('No "db" configured in spark.json.');
+    process.exit(1);
+  }
+  const names = Object.keys(schema);
+  if (!names.length) {
+    console.log('No tables declared — add <spark-ssr table="…"> to a page.');
+    await db.close();
+    return;
+  }
+  if (push) {
+    await pushSchema(db, schema, { force, log: (m) => console.log(`✓ ${m}`) });
+    await seedTables(db, schema, config, root, (m) => console.log(`✓ ${m}`));
+    console.log('✓ database matches the templates');
+  } else {
+    const diff = await diffSchema(db, schema);
+    for (const t of names) {
+      const spec = schema[t];
+      const cols = ['id', ...(spec.scoped ? ['user_id'] : []), ...Object.keys(spec.columns), 'created_at'];
+      console.log(`${t}: ${cols.join(', ')}${spec.seed ? `  (seed: ${spec.seed})` : ''}`);
+    }
+    if (!diff.length) {
+      console.log('\n✓ live database already matches');
+    } else {
+      console.log('');
+      for (const d of diff) {
+        if (d.create) console.log(`will create ${d.table}`);
+        for (const c of d.add) console.log(`will add ${d.table}.${c.name} ${c.type}`);
+        for (const c of d.extra) console.log(`extra column ${d.table}.${c} (kept; --force drops)`);
+      }
+      console.log('\nrun `bun spark-ssr db push` to apply');
+    }
+  }
+  await db.close();
 }
 
 const opts = parseArgs(process.argv.slice(2));
@@ -86,10 +158,12 @@ const root = resolve(opts.root || process.cwd());
 const port = opts.port ?? (Number(process.env.PORT) || 3000);
 
 if (opts.cmd === 'build') {
-  await build(root, opts.compile);
+  await build(root, opts);
+} else if (opts.cmd === 'db') {
+  await dbCmd(root, opts);
 } 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

@@ -1,7 +1,7 @@
 {
   "name": "spark-ssr",
-  "version": "0.1.1",
-  "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.",
+  "version": "0.3.0",
+  "description": "Zero-config SSR for spark-html on Bun. The HTML template infers everything: filesystem routing, layouts, <spark-ssr> declarative data (SQL, URLs, globs, modules), auto CRUD with validation, guards, no-JS forms, schema + seeds, live updates, SEO. No build step.",
   "homepage": "https://wilkinnovo.github.io/spark-html",
   "type": "module",
   "main": "./src/index.js",
@@ -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

@@ -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/db.js

@@ -18,13 +18,16 @@ const bindable = (v) =>
   : typeof v === 'boolean' ? (v ? 1 : 0)
   : JSON.stringify(v);
 
-export async function connect(url) {
+export async function connect(url, root) {
   if (!url) return null;
 
   if (url.startsWith('sqlite:')) {
     const { Database } = await import('bun:sqlite');
+    const { isAbsolute, join } = await import('node:path');
     let path = url.slice('sqlite:'.length).replace(/^\/\//, '');
     if (path === '' || path === ':memory:') path = ':memory:';
+    // A relative file lives in the PROJECT, not wherever the process started.
+    else if (root && !isAbsolute(path)) path = join(root, path);
     const db = new Database(path, { create: true });
     return {
       kind: 'sqlite',

package/src/hydrate.js

@@ -41,7 +41,7 @@ export function primaryColumn(cols) {
  *  - loop handlers get their row argument.
  *  - the synthesized <script> is appended.
  */
-export function clientComponent({ html, analysis, plan, table, cols, key }) {
+export function clientComponent({ html, analysis, plan, table, cols, key, live }) {
   const { document } = parseHTML('<!doctype html><html><body>' + html + '</body></html>');
 
   const kids = templateKids;
@@ -96,12 +96,12 @@ export function clientComponent({ html, analysis, plan, table, cols, key }) {
     for (const c of [...node.childNodes]) transform(c, loopVar);
   })(document.body, null);
 
-  return document.body.innerHTML + '\n<script>\n' + clientScript({ analysis, plan, table, cols, key }) + '</script>\n';
+  return document.body.innerHTML + '\n<script>\n' + clientScript({ analysis, plan, table, cols, key, live }) + '</script>\n';
 }
 
 // The synthesized component script. Plain functions, no template literals,
 // no code-shaped strings (the runtime's script rewriter is not string-aware).
-export function clientScript({ analysis, plan, table, cols, key }) {
+export function clientScript({ analysis, plan, table, cols, key, live }) {
   const L = [];
   L.push(`import __init from '/__spark/data/${key}.js';`);
   for (const p of plan) {
@@ -152,6 +152,13 @@ export function clientScript({ analysis, plan, table, cols, key }) {
     if (listVar) L.push('  await __refresh();');
     L.push('}');
   }
+  // live (§9): every write the server sees on this table pings the channel;
+  // every open tab refetches through its own session. Realtime as one
+  // attribute — no socket code, no pub/sub setup.
+  if (live && listVar) {
+    L.push(`const __live = new EventSource('/__spark/live');`);
+    L.push(`__live.onmessage = (e) => { if (e.data === '${table}') __refresh(); };`);
+  }
   return L.join('\n') + '\n';
 }
 

package/src/index.js

@@ -3,12 +3,19 @@
  *
  * The HTML template infers everything: <template each="todo in todos"> means
  * you need `todos`; <spark-ssr table="todos"> backs it with a table and the
- * REST endpoints the handlers imply; a user_id column means auth scoping.
- * Filesystem routing, sessions, uploads, middleware — no build step.
+ * REST endpoints the handlers imply; a user_id column means auth scoping;
+ * the form constraints are the validation; the template is the schema.
+ * Filesystem routing, layouts, sessions, uploads, middleware, live updates —
+ * no build step.
  */
-export { serve } from './server.js';
+export { serve, scanPages, projectSchema } from './server.js';
 export { loadConfig } from './config.js';
 export { connect } from './db.js';
-export { extractBlocks, rewriteParams, analyze, dataPlan, singleShaped } from './parse.js';
+export {
+  extractBlocks, rewriteParams, analyze, mergeAnalyses, dataPlan, singleShaped,
+  extractForms, validateFields, sqlTables,
+} from './parse.js';
 export { renderFragment, evalExpr } from './render.js';
 export { clientComponent, clientScript, initModule, handlerRoles, primaryColumn } from './hydrate.js';
+export { urlSource, globSource, moduleSource, parseFrontMatter, makeSourceCache } from './sources.js';
+export { inferSchema, diffSchema, pushSchema, seedTables } from './schema.js';

package/src/render.js

@@ -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) {
@@ -61,7 +62,9 @@ const interpolate = (text, scope) =>
  */
 export async function renderFragment(html, scope, ctx = {}, depth = 0) {
   const { document } = parseHTML('<!doctype html><html><body>' + html + '</body></html>');
-  await walkChildren(document.body, scope, { maxDepth: 20, ...ctx, document }, depth);
+  const inner = { maxDepth: 20, ...ctx, document };
+  await walkChildren(document.body, scope, inner, depth);
+  if (inner.status) ctx.status = inner.status; // a rendered branch set it (§3)
   return document.body.innerHTML;
 }
 
@@ -91,6 +94,21 @@ async function walkNode(node, scope, ctx, depth) {
 
   if (node.hasAttribute('import')) return renderImport(node, scope, ctx, depth);
 
+  // No-JS forms (§5): a redirect="…" attribute on a form posting to /api/*
+  // becomes a hidden _redirect field, so the plain-browser 303 knows where
+  // to land. The attribute itself never reaches the browser.
+  if (tag === 'form' && node.hasAttribute('redirect')) {
+    const to = node.getAttribute('redirect');
+    node.removeAttribute('redirect');
+    if ((node.getAttribute('action') || '').startsWith('/api/')) {
+      const hidden = ctx.document.createElement('input');
+      hidden.setAttribute('type', 'hidden');
+      hidden.setAttribute('name', '_redirect');
+      hidden.setAttribute('value', to);
+      node.appendChild(hidden);
+    }
+  }
+
   renderAttrs(node, scope);
   await walkChildren(node, scope, ctx, depth);
 }
@@ -192,6 +210,10 @@ async function renderIfChain(node, scope, ctx, depth) {
     if (link.expr === null || evalExpr(link.expr, scope)) { winner = link; break; }
   }
   if (winner) {
+    // Declarative status (§3): the rendered branch sets the response status —
+    // <template else status="404"> stops being a 200-that-means-404.
+    const st = Number(winner.node.getAttribute('status'));
+    if (st) ctx.status = st;
     await insertRendered(kids(winner.node), winner.node, scope, ctx, depth);
   }
   for (const link of chain) link.node.remove();
@@ -260,10 +282,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);