@webjsdev/cli 0.10.8 → 0.10.10

package/bin/webjs.js

@@ -41,7 +41,8 @@ const USAGE = `webjs commands:
   webjs dev   [--port 8080]                       Start dev server with live reload
   webjs start [--port 8080]                       Start production server (serves source directly, no build step)
   webjs test  [--server|--browser]                 Run server + browser tests
-  webjs check                                     Run correctness checks on the app
+  webjs check [--json]                            Run correctness checks on the app (--json emits structured violations)
+  webjs mcp                                       Start the read-only MCP server (routes / actions / components / check)
   webjs doctor                                    Verify project health (Node, tsconfig, env, vendor pins, @webjsdev versions, git hook)
   webjs types                                     Generate .webjs/routes.d.ts (typed Route union + per-route params)
   webjs typecheck [tsc args...]                   Type-check the app with the project's tsc --noEmit (non-zero on errors)
@@ -266,6 +267,18 @@ async function main() {
 
       const violations = await checkConventions(process.cwd());
 
+      // --json emits the raw structured violations + a summary count as JSON,
+      // so an agent running `webjs check` in a loop consumes structured data
+      // instead of regex-scraping stdout. The shared projector keeps this byte-
+      // identical to the MCP `check` tool. The non-zero exit on violations is
+      // preserved (an agent gates on the exit code AND parses the report).
+      if (rest.includes('--json')) {
+        const { projectCheck } = await import('../lib/check-json.js');
+        console.log(JSON.stringify(projectCheck(violations)));
+        if (violations.length > 0) process.exit(1);
+        break;
+      }
+
       if (violations.length === 0) {
         console.log('webjs check: all checks pass ✓');
       } else {
@@ -631,6 +644,29 @@ Full docs: https://docs.webjs.com`);
         `  --from PROVIDER     CDN to resolve through. One of: ${[...SUPPORTED_PROVIDERS].join(', ')}. Default: jspm.`);
       process.exit(1);
     }
+    case 'mcp': {
+      // Read-only MCP server (#262) over stdio. STDOUT is the JSON-RPC channel,
+      // so nothing here may write to stdout: the data functions are read-only
+      // and `runMcpServer` routes all diagnostics to stderr. The CLI version is
+      // advertised in the initialize handshake's serverInfo.
+      const { readFileSync } = await import('node:fs');
+      let version = '0.0.0';
+      try {
+        const pkg = JSON.parse(
+          readFileSync(join(__dirname, '..', 'package.json'), 'utf8'),
+        );
+        version = pkg.version || version;
+      } catch {}
+      const { runMcpServer } = await import('../lib/mcp.js');
+      await runMcpServer({
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        cwd: process.cwd(),
+        version,
+      });
+      break;
+    }
     case 'help':
     case undefined:
       console.log(USAGE);

package/lib/check-json.js

@@ -0,0 +1,47 @@
+/**
+ * Shared JSON projector for `webjs check` violations (#262).
+ *
+ * `webjs check --json` and the `webjs mcp` server's `check` tool BOTH return
+ * the identical shape, so the projection lives here once. The input is the raw
+ * `Violation[]` from `checkConventions(appDir)` (each `{ rule, file, message,
+ * fix }`); the output adds a `summary` count plus a per-rule breakdown so an
+ * agent consuming the structured output never has to regex-scrape stdout.
+ *
+ * Pure and side-effect-free: it neither reads files nor prints. The caller owns
+ * running `checkConventions` and (for the CLI) the non-zero exit when there are
+ * violations.
+ *
+ * @module check-json
+ */
+
+/**
+ * @typedef {{ rule: string, file: string, message: string, fix: string }} Violation
+ */
+
+/**
+ * @typedef {{
+ *   violations: Violation[],
+ *   summary: { count: number, byRule: Record<string, number> },
+ * }} CheckReport
+ */
+
+/**
+ * Project a raw `Violation[]` into the structured `{ violations, summary }`
+ * report shared by `check --json` and the MCP `check` tool. `violations` is
+ * passed through verbatim (the `{ rule, file, message, fix }` shape), and
+ * `summary.byRule` tallies how many violations each rule produced.
+ *
+ * @param {Violation[]} violations
+ * @returns {CheckReport}
+ */
+export function projectCheck(violations) {
+  /** @type {Record<string, number>} */
+  const byRule = {};
+  for (const v of violations) {
+    byRule[v.rule] = (byRule[v.rule] || 0) + 1;
+  }
+  return {
+    violations,
+    summary: { count: violations.length, byRule },
+  };
+}

package/lib/create.js

@@ -636,6 +636,15 @@ export type ActionResult<T> =
     if (existsSync(tailwindSrc)) {
       await cp(tailwindSrc, join(publicDir, 'tailwind-browser.js'));
     }
+    // Progressive-enhancement service worker (#271): ship the opt-in offline
+    // primitive (the worker + its offline fallback) into the UI scaffolds
+    // (full-stack / saas; this block is api-excluded since api has no UI).
+    // Dormant until the app registers it (see agent-docs/service-worker.md);
+    // it never changes the JS-disabled baseline.
+    for (const swFile of ['sw.js', 'offline.html']) {
+      const swSrc = join(TEMPLATES, 'public', swFile);
+      if (existsSync(swSrc)) await cp(swSrc, join(publicDir, swFile));
+    }
 
     const utilsDir = join(appDir, 'lib', 'utils');
     await mkdir(utilsDir, { recursive: true });

package/lib/mcp.js

@@ -0,0 +1,408 @@
+/**
+ * `webjs mcp`: a minimal, READ-ONLY Model Context Protocol server (#262).
+ *
+ * Exposes the live introspection surface an AI agent needs while editing a
+ * webjs app (the route table, registered server actions with their RPC
+ * endpoints, registered custom-element tags, and the structured `webjs check`
+ * violations) over MCP's stdio transport. Every tool REUSES an existing
+ * `@webjsdev/server` data function and MUTATES NOTHING. The prior art is
+ * Next.js's `next-devtools-mcp` (get_routes / get_server_action_by_id /
+ * get_errors); this is deliberately tiny.
+ *
+ * Transport: MCP stdio is newline-delimited JSON-RPC 2.0. One JSON object per
+ * line arrives on stdin; exactly one JSON response line per request is written
+ * to stdout. STDOUT IS THE PROTOCOL CHANNEL, so this module writes ONLY
+ * JSON-RPC frames there and routes every diagnostic to stderr. A malformed
+ * input line is answered with a JSON-RPC parse error and never crashes the
+ * loop. Hand-rolled with zero new dependency (webjs is buildless +
+ * minimal-deps).
+ *
+ * @module mcp
+ */
+
+import { createInterface } from 'node:readline';
+import { relative } from 'node:path';
+
+const PROTOCOL_VERSION = '2024-11-05';
+
+/**
+ * The four read-only tools. Each takes an optional `{ appDir }` (default the
+ * server's cwd) and projects an EXISTING `@webjsdev/server` function's output
+ * into an agent-friendly shape. Descriptions are crisp so a model picks the
+ * right tool without reading source.
+ */
+const TOOL_DEFS = [
+  {
+    name: 'list_routes',
+    description:
+      'List the app route table: SSR pages (path, file, dynamic flag, param names) and route.{js,ts} API handlers (path, file, HTTP methods). Read-only.',
+  },
+  {
+    name: 'list_actions',
+    description:
+      'List registered server actions (the .server.{js,ts} files with "use server"): file, exported function name, and the /__webjs/action/<hash>/<fn> RPC endpoint. Read-only.',
+  },
+  {
+    name: 'list_components',
+    description:
+      'List registered custom-element tags: tag name, defining file, and class name. Read-only.',
+  },
+  {
+    name: 'check',
+    description:
+      'Run webjs check (correctness rules) and return the structured violations { rule, file, message, fix } plus a summary count and per-rule breakdown. Read-only.',
+  },
+];
+
+/** The shared input schema: every tool takes an optional appDir override. */
+const TOOL_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    appDir: {
+      type: 'string',
+      description: 'App directory to introspect. Defaults to the server cwd.',
+    },
+  },
+  required: [],
+};
+
+/**
+ * Lexically extract the names exported from a module source. Recognises the
+ * common forms a server-action / route file uses without LOADING the module
+ * (loading would run its top-level side effects: Prisma init, DB connects).
+ *
+ *   export async function foo() {}   export function foo() {}
+ *   export const foo = ...           export let/var foo = ...
+ *   export default ...               (recorded as 'default')
+ *   export { a, b as c }             (the EXPORTED name, so `c`)
+ *
+ * @param {string} src
+ * @returns {string[]} unique export names, in source order
+ */
+export function extractExportNames(src) {
+  /** @type {string[]} */
+  const names = [];
+  const add = (n) => { if (n && !names.includes(n)) names.push(n); };
+
+  // export [async] function NAME / export const|let|var NAME / export class NAME
+  const declRe =
+    /\bexport\s+(?:async\s+)?(?:function\*?|const|let|var|class)\s+([A-Za-z_$][\w$]*)/g;
+  let m;
+  while ((m = declRe.exec(src)) !== null) add(m[1]);
+
+  // export default ...
+  if (/\bexport\s+default\b/.test(src)) add('default');
+
+  // export { a, b as c, default as d }
+  const namedRe = /\bexport\s*\{([^}]*)\}/g;
+  while ((m = namedRe.exec(src)) !== null) {
+    for (const part of m[1].split(',')) {
+      const seg = part.trim();
+      if (!seg) continue;
+      // `local as exported` -> the exported name is what callers import.
+      const asMatch = /\bas\s+([A-Za-z_$][\w$]*)\s*$/.exec(seg);
+      if (asMatch) add(asMatch[1]);
+      else {
+        const idMatch = /^([A-Za-z_$][\w$]*)$/.exec(seg);
+        if (idMatch) add(idMatch[1]);
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * Lexically extract the HTTP method exports of a route.{js,ts} file. The webjs
+ * API router (`api.js`) dispatches the five standard verbs, plus `WS` for a
+ * WebSocket upgrade. We report exactly those that are exported, NOT `HEAD` /
+ * `OPTIONS` (the router does not dispatch a named handler for them, so listing
+ * them would imply a route the framework ignores). Read-only: no module load.
+ *
+ * @param {string} src
+ * @returns {string[]}
+ */
+export function extractRouteMethods(src) {
+  const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'WS'];
+  const exported = new Set(extractExportNames(src));
+  return METHODS.filter((m) => exported.has(m));
+}
+
+/**
+ * The literal URL path for a page/api directory: `blog/[slug]` -> `/blog/[slug]`,
+ * the root `.` -> `/`. Route groups `(group)` and `_private` segments drop, the
+ * same normalization `buildRouteTable` uses for matching.
+ *
+ * @param {string} routeDir  POSIX-style, `.` for the app root.
+ * @returns {string}
+ */
+function routePathFromDir(routeDir) {
+  if (!routeDir || routeDir === '.') return '/';
+  const segs = routeDir
+    .split('/')
+    .filter((s) => !(s.startsWith('(') && s.endsWith(')')) && !s.startsWith('_'));
+  return segs.length ? '/' + segs.join('/') : '/';
+}
+
+/**
+ * The tool runners. Each is async, takes `(appDir)`, and returns a plain
+ * JSON-serialisable projection of an existing server data function. All are
+ * read-only.
+ *
+ * @param {{ buildRouteTable: Function, buildActionIndex: Function, hashFile: Function, scanComponents: Function, checkConventions: Function, projectCheck: Function, readFile: Function }} deps
+ */
+export function makeToolRunners(deps) {
+  const {
+    buildRouteTable,
+    buildActionIndex,
+    hashFile,
+    scanComponents,
+    checkConventions,
+    projectCheck,
+    readFile,
+  } = deps;
+
+  return {
+    async list_routes(appDir) {
+      const table = await buildRouteTable(appDir);
+      const pages = await Promise.all(
+        table.pages.map(async (r) => {
+          /** @type {{ path: string, file: string, dynamic?: boolean, params?: string[] }} */
+          const out = {
+            path: routePathFromDir(r.routeDir),
+            file: relative(appDir, r.file),
+          };
+          if (r.paramNames && r.paramNames.length) {
+            out.dynamic = true;
+            out.params = r.paramNames;
+          }
+          return out;
+        }),
+      );
+      const apis = await Promise.all(
+        table.apis.map(async (r) => {
+          let methods = [];
+          try {
+            methods = extractRouteMethods(await readFile(r.file, 'utf8'));
+          } catch {}
+          return {
+            path: routePathFromDir(r.routeDir),
+            file: relative(appDir, r.file),
+            methods,
+          };
+        }),
+      );
+      return { pages, apis };
+    },
+
+    async list_actions(appDir) {
+      // `skipExposeLoad` builds the file -> hash maps WITHOUT importing any
+      // `expose()` module, so this stays truly read-only (no Prisma/DB init, and
+      // no stray stdout from a loaded module corrupting the JSON-RPC channel).
+      // The RPC hash is over the file path only, so no module load is needed.
+      const idx = await buildActionIndex(appDir, false, { skipExposeLoad: true });
+      /** @type {Array<{ file: string, fn: string, endpoint: string }>} */
+      const actions = [];
+      for (const [file, hash] of idx.fileToHash) {
+        let names = [];
+        try {
+          names = extractExportNames(await readFile(file, 'utf8'));
+        } catch {}
+        for (const fn of names) {
+          actions.push({
+            file: relative(appDir, file),
+            fn,
+            endpoint: `/__webjs/action/${hash}/${fn}`,
+          });
+        }
+      }
+      // Stable order for deterministic output.
+      actions.sort((a, b) =>
+        a.file === b.file ? a.fn.localeCompare(b.fn) : a.file.localeCompare(b.file),
+      );
+      return actions;
+    },
+
+    async list_components(appDir) {
+      const comps = await scanComponents(appDir);
+      return comps
+        .map((c) => ({
+          tag: c.tag,
+          file: relative(appDir, c.file),
+          className: c.className,
+        }))
+        .sort((a, b) => a.tag.localeCompare(b.tag));
+    },
+
+    async check(appDir) {
+      const violations = await checkConventions(appDir);
+      return projectCheck(violations);
+    },
+  };
+}
+
+/**
+ * A JSON-RPC 2.0 result frame.
+ * @param {string|number|null} id
+ * @param {any} result
+ */
+function rpcResult(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+
+/**
+ * A JSON-RPC 2.0 error frame.
+ * @param {string|number|null} id
+ * @param {number} code
+ * @param {string} message
+ */
+function rpcError(id, code, message) {
+  return { jsonrpc: '2.0', id, error: { code, message } };
+}
+
+/**
+ * Run the read-only webjs MCP server over the given streams. Reads
+ * newline-delimited JSON-RPC from `stdin`, writes one response line per request
+ * to `stdout`, and logs diagnostics to `stderr` ONLY (stdout is the protocol
+ * channel). Resolves when stdin ends (clean shutdown).
+ *
+ * Injectable streams + `cwd` keep it testable in-process with PassThrough
+ * streams; the bin passes the real `process.std*` + `process.cwd()`.
+ *
+ * @param {{
+ *   stdin: NodeJS.ReadableStream,
+ *   stdout: NodeJS.WritableStream,
+ *   stderr: NodeJS.WritableStream,
+ *   cwd: string,
+ *   version?: string,
+ *   deps?: object,
+ * }} opts
+ * @returns {Promise<void>}
+ */
+export async function runMcpServer(opts) {
+  const { stdin, stdout, stderr, cwd } = opts;
+  const version = opts.version || '0.0.0';
+
+  // Resolve the data functions from @webjsdev/server (reading them is
+  // read-only). Injectable for tests so they need not boot the real server.
+  let deps = opts.deps;
+  if (!deps) {
+    const server = await import('@webjsdev/server');
+    const check = await import('@webjsdev/server/check');
+    const { readFile } = await import('node:fs/promises');
+    const { projectCheck } = await import('./check-json.js');
+    deps = {
+      buildRouteTable: server.buildRouteTable,
+      buildActionIndex: server.buildActionIndex,
+      hashFile: server.hashFile,
+      scanComponents: server.scanComponents,
+      checkConventions: check.checkConventions,
+      projectCheck,
+      readFile,
+    };
+  }
+  const runners = makeToolRunners(deps);
+
+  /** Write one JSON-RPC frame as a single line to stdout. */
+  const send = (frame) => {
+    stdout.write(JSON.stringify(frame) + '\n');
+  };
+  /** Diagnostics go to stderr only, never stdout. */
+  const logErr = (msg) => {
+    try { stderr.write(`[webjs mcp] ${msg}\n`); } catch {}
+  };
+
+  /**
+   * Dispatch one parsed JSON-RPC message. Returns a frame to send, or null
+   * for a notification (no `id`) which gets no response.
+   */
+  const dispatch = async (msg) => {
+    const id = msg && Object.prototype.hasOwnProperty.call(msg, 'id') ? msg.id : null;
+    const isNotification = id === null || id === undefined;
+    const method = msg && msg.method;
+
+    if (method === 'initialize') {
+      return rpcResult(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: 'webjs', version },
+      });
+    }
+
+    // `notifications/initialized` (and any other notification) gets no reply.
+    if (isNotification) return null;
+
+    if (method === 'tools/list') {
+      return rpcResult(id, {
+        tools: TOOL_DEFS.map((t) => ({
+          name: t.name,
+          description: t.description,
+          inputSchema: TOOL_INPUT_SCHEMA,
+        })),
+      });
+    }
+
+    if (method === 'tools/call') {
+      const params = (msg && msg.params) || {};
+      const name = params.name;
+      const args = params.arguments || {};
+      const runner = runners[name];
+      if (!runner) {
+        return rpcError(id, -32602, `Unknown tool: ${String(name)}`);
+      }
+      const appDir = typeof args.appDir === 'string' && args.appDir ? args.appDir : cwd;
+      try {
+        const result = await runner(appDir);
+        return rpcResult(id, {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        });
+      } catch (e) {
+        // A tool failure is an MCP tool-result error (isError), not a transport
+        // error, so the agent sees the message in the content channel.
+        logErr(`tool ${name} failed: ${e && e.message ? e.message : e}`);
+        return rpcResult(id, {
+          isError: true,
+          content: [
+            { type: 'text', text: `Error running ${name}: ${e && e.message ? e.message : String(e)}` },
+          ],
+        });
+      }
+    }
+
+    return rpcError(id, -32601, `Method not found: ${String(method)}`);
+  };
+
+  const rl = createInterface({ input: stdin, crlfDelay: Infinity });
+
+  await new Promise((resolveRun) => {
+    // Serialise line handling so responses preserve request order even though
+    // dispatch is async.
+    let chain = Promise.resolve();
+    rl.on('line', (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) return;
+      chain = chain.then(async () => {
+        let msg;
+        try {
+          msg = JSON.parse(trimmed);
+        } catch {
+          // Malformed line: a JSON-RPC parse error, never a crash.
+          send(rpcError(null, -32700, 'Parse error'));
+          return;
+        }
+        try {
+          const frame = await dispatch(msg);
+          if (frame) send(frame);
+        } catch (e) {
+          logErr(`dispatch error: ${e && e.message ? e.message : e}`);
+          const id =
+            msg && Object.prototype.hasOwnProperty.call(msg, 'id') ? msg.id : null;
+          send(rpcError(id, -32603, 'Internal error'));
+        }
+      });
+    });
+    rl.on('close', () => {
+      // Drain the in-flight chain, then resolve (clean shutdown on stdin end).
+      chain.then(() => resolveRun()).catch(() => resolveRun());
+    });
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.8",
+  "version": "0.10.10",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/.agents/rules/workflow.md

@@ -114,6 +114,20 @@ self-review loop.
   `static styles = css\`...\``) or third-party-embed isolation. `<slot>`
   projection works identically in both modes (named slots, fallback content,
   `assignedNodes` / `slotchange`, first-wins resolution).
+- **Tailwind-first styling.** Tailwind utilities are the strong default for
+  pages AND light-DOM components: layout, spacing, color (via `@theme`
+  tokens), typography, borders, radius, shadows, interaction states. Light
+  DOM does not scope, so utilities apply directly. The lit reflex to scope
+  CSS (`static styles = css\`...\``) or write an inline `<style>` with
+  semantic class names (`.hero`, `.card`) in a light-DOM component is wrong:
+  the scoped block needs `static shadow = true`, and inline class names leak
+  globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper
+  returning an `` html`...` `` fragment, not a CSS class. Reserve raw CSS for
+  the allowlist (design tokens / `@theme`, `@property` + `@keyframes`,
+  `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` /
+  gradients); when unavoidable in a light-DOM component, prefix every class
+  selector with the component tag. Shadow-DOM components legitimately use
+  `static styles = css\`...\`` for scoped CSS.
 - Custom-element tag names are passed to `.register('tag-name')`. They are NOT
   a static field on the class.
 - One function per server action file (`*.server.ts`).

package/templates/.claude/hooks/require-tests-with-src.sh

@@ -1,24 +1,32 @@
 #!/usr/bin/env bash
 #
-# PreToolUse hook (scaffolded by `webjs create`): block a `git commit`
+# PreToolUse hook (scaffolded by `webjs create`): WARN on a `git commit`
 # that adds or changes application code without any accompanying test.
 #
-# webjs is AI-first: most apps are built with an AI agent, and the
-# easiest corner to cut is shipping a feature with no test. This gate
-# makes "every change ships with a test" a hard floor, not a suggestion.
+# webjs is AI-first, and "every change ships with a test" is the right
+# default. But it is a CONVENTION, not a correctness check: a sensible
+# app can legitimately want a test-less commit (a spike, a vendored
+# file, a pure refactor). The convention-vs-check principle in this
+# app's AGENTS.md and CONVENTIONS.md says guidance like this WARNS, it
+# does not hard-block by default. So this hook surfaces a loud reminder
+# and lets the commit proceed.
 #
 # What a hook CANNOT do: judge WHICH test layer a change needs (a unit
-# test vs a browser/e2e test is a judgement call). So it enforces the
-# floor (some real test must accompany app code) and reminds you to add
-# browser/e2e coverage for interactive surfaces. `webjs test` runs the
-# actual suite in the commit hook.
+# test vs a browser/e2e test is a judgement call). So it nudges toward
+# the floor (some real test should accompany app code) and reminds you
+# to add browser/e2e coverage for interactive surfaces. The actual test
+# suite runs in CI (.github/workflows/ci.yml), which is the real gate.
 #
 # Scope: fires only on `git commit`. Inspects the STAGED diff.
 #
-# Blocks (exit 2) when the staged diff changes app code (app/, modules/,
-# components/, lib/) but stages no test (test/** or *.test.* / *.spec.*).
-# Allowed: commits with no app-code change, commits that stage a test
-# alongside, and WEBJS_NO_TEST_GATE=1 for a genuine non-code commit.
+# Behavior when the staged diff changes app code (app/, modules/,
+# components/, lib/) but stages no test (test/** or *.test.* / *.spec.*):
+#   - Default: WARN via additionalContext, then allow the commit (exit 0).
+#   - WEBJS_TEST_GATE=block: restore the old hard floor (print BLOCKED,
+#     exit 2), for a project that wants the strict gate. Set it in
+#     .claude/settings.json env, your shell, or CI.
+#   - WEBJS_NO_TEST_GATE=1: skip entirely (no warn, no block), for a
+#     genuine non-code commit (docs, config).
 #
 # Bypass (humans, emergencies): git commit --no-verify.
 
@@ -52,7 +60,9 @@ test_staged=$(printf '%s\n' "$staged" \
   | grep -E '(^|/)test/|\.test\.[mc]?[jt]sx?$|\.spec\.[mc]?[jt]sx?$' || true)
 
 if [ -z "$test_staged" ]; then
-  cat >&2 <<'EOF'
+  # Hard-mode opt-in: restore the old block when the project asks for it.
+  if [ "${WEBJS_TEST_GATE:-}" = "block" ] || [ "${WEBJS_TEST_GATE:-}" = "hard" ]; then
+    cat >&2 <<'EOF'
 BLOCKED: this commit changes app code but stages no test.
 
 You staged application code (app/, modules/, components/, lib/) with no
@@ -66,11 +76,21 @@ Pick the layer the change needs (a unit test is not always enough):
     real behaviour in a browser, not just the function in isolation.
 
 See `webjs test` and the testing guide. Genuine non-code commit (docs,
-config) that needs no test? Re-run with WEBJS_NO_TEST_GATE=1.
+config) that needs no test? Re-run with WEBJS_NO_TEST_GATE=1. Hard mode is
+on because WEBJS_TEST_GATE=block is set; unset it to fall back to a warning.
 
 Hook: .claude/hooks/require-tests-with-src.sh
 EOF
-  exit 2
+    exit 2
+  fi
+
+  # Default: warn loudly via additionalContext, then allow the commit.
+  # A missing test for app code subsumes the interactive-component
+  # reminder, so emit this warning alone and skip that reminder below.
+  jq -n --arg ctx "Heads up: this commit stages app code (app/, modules/, components/, lib/) with no test. Every change should ship with a test (it is a convention, not a hard gate). Pick the layer the change needs: a unit test for logic/actions/queries/utils, and a browser or e2e test for a component, hydration, the client router, or a server action called from the client. The suite runs in CI regardless. To enforce a hard block locally, set WEBJS_TEST_GATE=block. To silence this for a genuine non-code commit, set WEBJS_NO_TEST_GATE=1." '{
+    hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: $ctx }
+  }'
+  exit 0
 fi
 
 # Reminder for interactive surfaces: a unit test alone rarely covers them.

package/templates/.claude.json

@@ -4,6 +4,11 @@
       "type": "stdio",
       "command": "npx",
       "args": ["@playwright/mcp@latest"]
+    },
+    "webjs": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@webjsdev/cli", "mcp"]
     }
   }
 }

package/templates/.cursorrules

@@ -103,7 +103,8 @@ self-review loop.
 
 - No build step: source files are served as ES modules
 - **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
-- Web components with shadow DOM: use `static styles = css` not inline styles
+- **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css`) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag.
+- Shadow-DOM components opt in with `static shadow = true` and use `static styles = css` for scoped CSS, not inline styles. That is the right home for scoped CSS.
 - One function per server action file (*.server.ts)
 - Components must call customElements.define('tag', Class)
 - Server-only code (@prisma/client, node:*, anything that needs Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap the access in a .server.{js,ts} file; the framework rewrites that import into an RPC stub for the browser. lib/ holds both server-only infra (lib/prisma.server.ts) and browser-safe utilities (lib/utils/cn.ts with cn); follow the same rule per file: if a lib/ file needs Node APIs, only import it from server-only files.

package/templates/.github/copilot-instructions.md

@@ -100,7 +100,7 @@ each change must include.
   build tools or bundlers in the critical path.
 - **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - Tagged template: html`<div>${value}</div>` with css`...` for styles.
-  Don't use inline `style="..."` on components (use `static styles = css\`...\``).
+- **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css\`...\``) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag. Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`...\`` for scoped CSS; don't use inline `style="..."` there.
 - Components: extend WebComponent, declare `static properties` (and `static styles` for shadow-DOM components), call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field.
 - Server actions: *.server.ts files with one exported async function each.
 - Server-only code (@prisma/client, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. lib/ holds both server-only infra (lib/prisma.server.ts) and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.

package/templates/AGENTS.md

@@ -618,7 +618,7 @@ Practical consequences for agents writing webjs code.
 | Top-level `import` of a browser-only library | SSR crash | Dynamic `import()` inside `connectedCallback` |
 | Class-field initializer for a reactive property (`student: Student = {...}`) | Silently breaks reactivity (overwrites the framework accessor) | `declare student: Student` plus constructor default |
 | `@property()` decorator | Banned by invariant 10 (erasable TS) | `static properties = { ... }` plus `declare` |
-| `static styles = css` block without `static shadow = true` | Styles leak globally; the framework warns at runtime | Add `static shadow = true`, or use Tailwind utilities |
+| Scoped `static styles = css` or an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component | Scoped block does nothing without `static shadow = true`; inline `<style>` class names leak globally | Tailwind utilities (the light-DOM default); or `static shadow = true` for genuinely scoped CSS |
 | `willUpdate` computing SSR-visible derived state | Works (runs at SSR), but overriding it opts the component out of elision | Fine for interactive components; for display-only, derive inline in `render()` |
 | `this.hasAttribute` / `getAttribute` in `render()` | Works (server attribute shim backs the attribute methods at SSR) | Read attributes directly, or via a `static properties` + `declare` reactive prop |
 | `ContextProvider` for server-known data | Default value during SSR, content shift on hydration | Pass via props from the page function |
@@ -627,6 +627,30 @@ The full annotated catalog with code examples lives in the framework
 repo at
 [`agent-docs/lit-muscle-memory-gotchas.md`](https://github.com/webjsdev/webjs/blob/main/agent-docs/lit-muscle-memory-gotchas.md).
 
+### Styling: Tailwind-first (the most common lit reflex to unlearn)
+
+**Tailwind utilities are the strong default for pages AND light-DOM
+components (the default DOM mode).** Use them for layout, spacing, color
+(via the `@theme` tokens), typography, borders, radius, shadows, and
+interaction states (hover/focus/active/disabled, dark mode). Light DOM
+does not scope styles, so utilities apply directly.
+
+The lit habit is to scope CSS in a shadow root (`static styles =
+css\`\``) or write an inline `<style>` with semantic class names
+(`.hero`, `.card`). In a light-DOM webjs component the scoped block does
+nothing without `static shadow = true`, and the inline class names leak
+globally. Prefer Tailwind. When a utility bundle repeats, extract it into
+a `lib/utils/ui.ts` helper returning an `` html`...` `` fragment, not a
+CSS class.
+
+Reserve raw CSS for what utilities cannot express: design-token `:root` /
+`@theme` definitions, `@property` + `@keyframes` animations,
+`::-webkit-scrollbar`, `prefers-reduced-motion` blocks, and complex
+`color-mix()` / gradient effects. When custom CSS is unavoidable in a
+light-DOM component, prefix every class selector with the component tag
+(invariant below). Shadow-DOM components (`static shadow = true`)
+legitimately use `static styles = css\`\`` for scoped CSS.
+
 ## Server action pattern
 
 ```ts
@@ -741,12 +765,116 @@ return html`
 
 The router's `closest('webjs-frame')` detection takes precedence over
 layout markers. Only the frame's content swaps. Use this sparingly,
-folder-based layouts handle 99% of cases. When a frame nav's response
-lacks the matching `<webjs-frame id>` (e.g. an auth redirect), the router
-fires a cancelable, bubbling `webjs:frame-missing` event (detail
-`{ frameId, url, document }`) and leaves the frame unchanged rather than
-silently swapping the whole page; call `preventDefault()` to take over
-the outcome (e.g. `location.assign(e.detail.url)`).
+folder-based layouts handle 99% of cases.
+
+**External targeting + `_top` (Turbo-style).** A trigger does not have to be
+nested in the frame it drives. An `<a>` or `<form>` (or any ancestor)
+carrying `data-webjs-frame="<id>"` drives the frame with that id from
+anywhere (an external sidebar/nav link, a filter form), resolved via
+`getElementById`. The reserved token `data-webjs-frame="_top"` on a trigger
+INSIDE a frame breaks OUT to a full-page navigation. An id that does not
+resolve to a live `<webjs-frame>` warns once and falls back to a normal nav
+(never throws). With JS disabled a `data-webjs-frame` link is an inert
+attribute on a plain `<a href>`, so the click is a normal full navigation.
+
+**Busy state.** While a frame nav is in flight the router sets the native
+`aria-busy="true"` on the frame (cleared to `"false"` on any exit: success,
+error, abort, or a missing frame), so AT announces it and CSS can style
+`webjs-frame[aria-busy="true"]`. It also dispatches a bubbling
+`webjs:frame-busy` event on the frame at start and finish (detail
+`{ frameId, busy }`).
+
+**Self-loading (`src` + `loading`).** A frame can fetch its OWN content:
+`<webjs-frame id="comments" src="/posts/42/comments" loading="lazy">` self-fetches
+that URL as a frame nav and applies the matching `<webjs-frame id>` subtree into
+itself, through the same frame-swap path (so the busy lifecycle + navigation-error
+recovery + frame-missing fallback all apply). `loading="eager"` (or absent)
+fetches on connect; `loading="lazy"` fetches on viewport entry. The request sends
+the `x-webjs-frame` header, so the SERVER returns ONLY the matched subtree (not
+the full page), falling back to the full page when the frame is absent. A `src` is
+JS-DEPENDENT (the browser does not natively fetch a `<webjs-frame src>`), so with
+JS off the frame shows only the children rendered into it; use it for DEFERRED
+content (comments, a recommendations rail) where a no-JS placeholder is fine, and
+render content server-side into the frame when it must exist without JS.
+
+**View Transitions + persistent elements (opt-in).** Add
+`<meta name="view-transition" content="same-origin">` to the page head and the
+router wraps every swap (the layout-marker swap, the `<webjs-frame>` swap, and
+the full-body fallback) in `document.startViewTransition` for an animated
+crossfade. OFF by default (no animation surprise); a browser without the API
+falls back to the identical synchronous swap. To keep a live element running
+across a navigation (a playing `<audio>` / `<video>`, a map, a stateful
+widget), mark it `data-webjs-permanent` AND give it an `id`: the router keeps
+the SAME DOM node by identity across the swap instead of recreating it (Turbo's
+permanent-element behaviour). Inert with JS off.
+
+When a frame nav's response lacks the matching `<webjs-frame id>` (e.g. an
+auth redirect), the router fires a cancelable, bubbling `webjs:frame-missing`
+event (detail `{ frameId, url, document }`) and leaves the frame unchanged
+rather than silently swapping the whole page; call `preventDefault()` to take
+over the outcome (e.g. `location.assign(e.detail.url)`).
+
+### 5. Stream actions for surgical element-level updates
+
+When a region swap is too coarse (append ONE comment, remove ONE row, bump a
+count, insert a toast), a server response can declare per-element actions as
+plain HTML, a `<webjs-stream action target>` wrapping one `<template>`:
+
+```html
+<webjs-stream action="append" target="comments">
+  <template><li>Nice post!</li></template>
+</webjs-stream>
+```
+
+Actions (Turbo's set): `append` / `prepend` (last / first child of the target
+id), `before` / `after` (sibling), `replace` (the target element), `update`
+(its children), `remove` (delete it). The `<webjs-stream>` element self-applies
+on connect and removes itself. ONE applier serves two paths:
+
+- **A content-negotiated `<form>`.** The router adds `Accept:
+  text/vnd.webjs-stream.html` on a JS-driven submission, so the server returns a
+  stream only then (apply it surgically) and a JS-OFF form gets a normal
+  render/redirect. Additive and progressive-enhancement-safe.
+- **A live channel.** `renderStream(message)` from a `connectWS` handler applies
+  a `broadcast()`ed payload, so chat / notifications reuse the same applier.
+
+Build the payload server-side and apply it client-side:
+
+```ts
+// app/posts/[id]/route.ts
+import { stream, streamResponse, acceptsStream, broadcast } from '@webjsdev/server';
+export async function POST(req: Request, { params }) {
+  const c = await addComment(params.id, await req.formData());
+  const html = stream.append('comments', `<li>${escapeHtml(c.text)}</li>`);
+  broadcast(`post:${params.id}`, html);              // fan out to other viewers
+  if (acceptsStream(req)) return streamResponse(html); // JS client: surgical
+  return Response.redirect(`/posts/${params.id}`, 303); // no-JS: normal render
+}
+```
+
+```ts
+// a component, for the live channel
+import { connectWS, renderStream } from '@webjsdev/core';
+connectWS(`/posts/${id}/feed`, { onMessage: (m) => renderStream(m) });
+```
+
+`stream.*` escapes the target id but NOT the content (server-authored HTML, like
+an `html` hole, so escape any user substring yourself). `renderStream` is
+auto-registered by the client router.
+
+**Failed navigations recover in place, never a destructive full reload.** A
+successful swap and an HTML error body of any status (e.g. a `422` re-rendered
+form) both apply in place. For the remaining failure cases (a non-HTML error
+response like a `500` with a JSON body, or a transport/parse failure) the
+router fires a cancelable, bubbling `webjs:navigation-error` event on
+`document` (detail `{ url, status, error }`, where `status` is the HTTP status
+or `null`, and `error` is the `Error` or `null`). `preventDefault()` hands
+recovery to you and leaves the page exactly as it is (shell, scroll, focus,
+client state preserved); otherwise the router renders a minimal in-place
+`<div role="alert">` into the deepest layout children slot (outer chrome
+preserved), only hard-loading as a last resort when there is no shared layout
+marker. An AbortError (a superseding nav) is a normal supersede and never fires
+the event.
 
 ### 5. `loading.ts` for per-segment skeletons
 
@@ -776,6 +904,32 @@ default export, scoped to that boundary (outer layouts stay alive).
 
 Full reference: see the [Client Router docs](https://docs.webjs.dev/docs/client-router) and the framework AGENTS.md "Client navigation" section.
 
+## Offline support (opt-in service worker)
+
+The UI scaffolds (full-stack and saas) ship a progressive-enhancement service
+worker at `public/sw.js` plus a `public/offline.html` fallback (the api template
+has no UI, so it omits them). They are **dormant until you register them**, so
+the JS-disabled baseline is unchanged. To enable offline support, add the opt-in
+registration snippet to the root layout `<head>`:
+
+```html
+<script>
+  if ('serviceWorker' in navigator) {
+    addEventListener('load', () => {
+      const tag = document.querySelector('script[type="importmap"]');
+      const build = (tag && tag.dataset.webjsBuild) || '';
+      navigator.serviceWorker.register('/sw.js' + (build ? '?v=' + build : ''));
+    });
+  }
+</script>
+```
+
+Navigations become network-first (fresh server HTML, with an offline fallback to
+a cached page or `/offline.html`); same-origin assets are stale-while-revalidate.
+The cache version ties to the deploy via the `?v=<build>` id, so a new deploy
+evicts the old cache automatically. `sw.js` is YOUR file, so edit the strategy as
+needed. Full reference: `agent-docs/service-worker.md`.
+
 ## Metadata (per-page)
 
 The `metadata` export is Next.js-compatible. Common fields shown below;
@@ -939,13 +1093,16 @@ composition, so a nested shell ends up dropped by the HTML parser.
    feature surface changed, `webjs check` passing. A unit test is not
    always enough: a component, hydration, the client router, or a server
    action called from the client needs a browser test
-   (`webjs test --browser`) asserting the behaviour in a real browser. A
-   commit that stages app code (`app/`, `modules/`, `components/`, `lib/`)
-   with no test is blocked for Claude Code by
-   `.claude/hooks/require-tests-with-src.sh`. The test suite itself runs in
-   CI (`.github/workflows/ci.yml`), not in the pre-commit hook, so `git
-   commit` stays fast and the gate cannot be skipped with a local
-   `--no-verify`.
+   (`webjs test --browser`) asserting the behaviour in a real browser. For
+   Claude Code, a commit that stages app code (`app/`, `modules/`,
+   `components/`, `lib/`) with no test WARNS via
+   `.claude/hooks/require-tests-with-src.sh` (every change should still ship
+   with a test, but that is a convention, not a hard gate). A project that
+   wants the strict floor opts into a hard block by setting
+   `WEBJS_TEST_GATE=block` (in `.claude/settings.json` env, your shell, or
+   CI). The real enforcement is CI: the test suite runs in
+   `.github/workflows/ci.yml`, not in the pre-commit hook, so `git commit`
+   stays fast and the gate cannot be skipped with a local `--no-verify`.
 3. Commit and push **per logical unit**, not at the end. A logical unit is one
    feature, one fix, one rename, one doc rewrite. If you have 5+ unstaged files
    spanning different concerns, commit the current group before continuing.

package/templates/CONVENTIONS.md

@@ -494,14 +494,19 @@ This is also why the auth test lives at `test/auth/auth.test.ts` (the
 feature-folder convention), NOT `test/unit/auth.test.ts`. Test KIND is a
 subfolder inside a feature, never the top level.
 
-**Every change ships with a test.** For Claude Code, a commit that
-stages app code (`app/`, `modules/`, `components/`, `lib/`) without
-staging a test is blocked by `.claude/hooks/require-tests-with-src.sh`.
-A unit test alone is not enough for interactive or component code: add
-the browser test that asserts the rendered/hydrated behaviour. The test
-suite itself runs in CI (`.github/workflows/ci.yml`) on every PR and
-push to main, not in the local pre-commit hook, so `git commit` stays
-fast and the gate cannot be skipped with a local `--no-verify`.
+**Every change ships with a test.** This is a convention, not a hard
+gate, consistent with the convention-vs-check principle this file
+states (a sensible app can legitimately want a test-less commit for a
+spike, a vendored file, or a pure refactor). For Claude Code, a commit
+that stages app code (`app/`, `modules/`, `components/`, `lib/`) without
+staging a test WARNS via `.claude/hooks/require-tests-with-src.sh`, then
+lets the commit through. A project that wants the strict floor opts into
+a hard block by setting `WEBJS_TEST_GATE=block` (in
+`.claude/settings.json` env, your shell, or CI). A unit test alone is
+not enough for interactive or component code: add the browser test that
+asserts the rendered/hydrated behaviour. The real enforcement is CI: the
+test suite runs in `.github/workflows/ci.yml` on every PR and push to
+main, so the gate cannot be skipped with a local `--no-verify`.
 
 ### Choosing a feature folder
 
@@ -687,7 +692,7 @@ Both hydrate without flash on the client.
 
 ---
 
-## Styling: Tailwind + JS helpers
+## Styling: Tailwind-first + JS helpers
 
 <!-- OVERRIDE -->
 
@@ -697,6 +702,31 @@ fluid type scale value, and motion duration is declared once in `@theme`
 and available everywhere via utility classes (`text-fg`, `bg-bg-elev`,
 `font-serif`, `duration-fast`, `text-display`).
 
+**Tailwind-first is the strong default for pages AND light-DOM
+components (the default DOM mode).** Use utilities for layout, spacing,
+color (via the `@theme` tokens), typography, borders, radius, shadows,
+and interaction states (hover/focus/active/disabled, dark mode). Light
+DOM does not scope styles, so utilities apply directly.
+
+**The lit muscle-memory trap.** If you have written lit, the habit is to
+scope CSS in a shadow root (`static styles = css\`\``) or write an inline
+`<style>` with semantic class names (`.hero`, `.feature`, `.card`) for
+every component. In a webjs light-DOM component the scoped block does
+nothing without `static shadow = true`, and the inline class names leak
+into the global namespace. Prefer Tailwind utilities. When the same
+bundle repeats, extract a `lib/utils/ui.ts` helper (below), not a CSS
+class.
+
+**Custom-CSS allowlist (the only things raw CSS is for).** Reserve raw
+CSS for what utilities cannot express: design-token `:root` / `@theme`
+definitions, `@property` animated custom properties with `@keyframes`,
+`::-webkit-scrollbar` / `scrollbar-color`, `prefers-reduced-motion`
+blocks, and complex `color-mix()` or gradient effects. When custom CSS is
+unavoidable in a light-DOM component, the class-prefix rule (see the
+Components section above) still applies. Shadow-DOM components
+(`static shadow = true`) legitimately author `static styles = css\`\``;
+that is the right home for scoped CSS.
+
 **Dedup repeated Tailwind class bundles with JS helpers, not `@apply`.**
 When the same string of classes appears in 2+ places, extract it into a
 small function in `lib/utils/ui.ts`:

package/templates/public/offline.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Offline</title>
+  <style>
+    :root { color-scheme: light dark; }
+    body {
+      margin: 0; min-height: 100vh; display: grid; place-items: center;
+      font: 16px/1.6 system-ui, sans-serif; background: #fafafa; color: #1a1a1a;
+    }
+    @media (prefers-color-scheme: dark) { body { background: #0d0d10; color: #e6e6e6; } }
+    main { max-width: 28rem; padding: 2rem; text-align: center; }
+    h1 { font-size: 1.5rem; margin: 0 0 0.5rem; }
+    p { margin: 0 0 1.5rem; opacity: 0.8; }
+    .retry {
+      display: inline-block; font: inherit; padding: 0.6rem 1.2rem;
+      border-radius: 0.5rem; background: #1a1a1a; color: #fff;
+      text-decoration: none; cursor: pointer;
+    }
+    @media (prefers-color-scheme: dark) { .retry { background: #e6e6e6; color: #0d0d10; } }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>You are offline</h1>
+    <p>This page is not available without a network connection. Pages you have already visited still work offline.</p>
+    <!-- An empty href reloads the current URL (the page the user tried to
+         reach), so retry works with NO inline JS, staying CSP-compatible. -->
+    <a class="retry" href="">Try again</a>
+  </main>
+</body>
+</html>

package/templates/public/sw.js

@@ -0,0 +1,106 @@
+/*
+ * webjs progressive-enhancement service worker (OPT-IN, #271).
+ *
+ * This adds an offline fallback and an asset cache WITHOUT changing the
+ * JavaScript-disabled baseline: with JS off no service worker registers, so
+ * pages, links, and forms behave exactly as they do today. It is registered
+ * explicitly (see the opt-in snippet in agent-docs/service-worker.md), never
+ * automatically.
+ *
+ * Strategy:
+ *   - Navigations are NETWORK-FIRST: always try the network so the user sees
+ *     fresh server-rendered HTML, caching each successful page (the SSR shell)
+ *     so a later OFFLINE visit to a page you have seen still renders. When the
+ *     network fails and nothing is cached, serve /offline.html.
+ *   - Same-origin static assets (the per-file ESM modules, the framework
+ *     runtime under /__webjs/core/, vendor bundles, public assets) are
+ *     stale-while-revalidate, so a repeat visit works offline. In production
+ *     these URLs carry a ?v=<hash> content fingerprint, so a changed file gets
+ *     a new URL and the cache can never serve stale bytes.
+ *
+ * Versioning ties to the deploy. The page registers this worker as
+ * `/sw.js?v=<data-webjs-build>` (the importmap build id), so a new deploy
+ * changes the worker's own URL, the browser fetches the new worker, and its
+ * `activate` deletes every cache that is not the current version. The cache
+ * name is derived from that `?v=` below.
+ *
+ * NEVER cached: non-GET requests, cross-origin requests, the action RPC
+ * endpoint (/__webjs/action/), the dev live-reload SSE (/__webjs/events) and
+ * dev reload client (/__webjs/reload.js).
+ */
+
+const BUILD = new URL(self.location.href).searchParams.get('v') || 'dev';
+const CACHE = 'webjs-' + BUILD;
+const OFFLINE_URL = '/offline.html';
+
+self.addEventListener('install', (event) => {
+  event.waitUntil((async () => {
+    const cache = await caches.open(CACHE);
+    // Precache the offline fallback. `reload` bypasses the HTTP cache so the
+    // freshly-deployed offline page is stored, not a stale one.
+    await cache.add(new Request(OFFLINE_URL, { cache: 'reload' }));
+    await self.skipWaiting();
+  })());
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil((async () => {
+    const keys = await caches.keys();
+    await Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k)));
+    await self.clients.claim();
+  })());
+});
+
+/** Decide whether a GET request to a same-origin path is a cacheable asset. */
+function isCacheableAsset(pathname) {
+  if (pathname.startsWith('/__webjs/action/')) return false; // RPC, never cache
+  if (pathname === '/__webjs/events' || pathname === '/__webjs/reload.js') return false; // dev
+  if (pathname.startsWith('/__webjs/core/') || pathname.startsWith('/__webjs/vendor/')) return true;
+  return /\.(?:js|mjs|ts|css|woff2?|png|jpe?g|svg|webp|gif|ico|json|map)$/.test(pathname);
+}
+
+self.addEventListener('fetch', (event) => {
+  const req = event.request;
+  if (req.method !== 'GET') return; // never cache writes
+  const url = new URL(req.url);
+  if (url.origin !== self.location.origin) return; // only same-origin
+
+  // Network-first for page navigations: fresh server HTML, cache it for offline,
+  // fall back to the cached page then the offline page.
+  if (req.mode === 'navigate') {
+    event.respondWith((async () => {
+      try {
+        const fresh = await fetch(req);
+        // Cache ONLY a successful page (never a 404/500 error page, or an
+        // offline visit would serve the cached error instead of the fallback).
+        // waitUntil keeps the worker alive until the write lands (a worker can
+        // be terminated the moment respondWith settles).
+        if (fresh && fresh.ok) {
+          const copy = fresh.clone();
+          event.waitUntil(caches.open(CACHE).then((cache) => cache.put(req, copy)));
+        }
+        return fresh;
+      } catch (_err) {
+        const cache = await caches.open(CACHE);
+        const cached = await cache.match(req);
+        return cached || (await cache.match(OFFLINE_URL)) || Response.error();
+      }
+    })());
+    return;
+  }
+
+  // Stale-while-revalidate for static assets.
+  if (isCacheableAsset(url.pathname)) {
+    event.respondWith((async () => {
+      const cache = await caches.open(CACHE);
+      const cached = await cache.match(req);
+      const network = fetch(req)
+        .then((res) => { if (res && res.ok) cache.put(req, res.clone()); return res; })
+        .catch(() => cached);
+      // Keep the worker alive for the background revalidation + write, which
+      // would otherwise be a floating promise lost on worker termination.
+      event.waitUntil(network.catch(() => {}));
+      return cached || network;
+    })());
+  }
+});