@webjsdev/cli 0.10.9 → 0.10.11

package/bin/webjs.js

@@ -255,10 +255,12 @@ async function main() {
 
       if (rest.includes('--rules')) {
         console.log('webjs check, correctness rules:');
-        console.log('  Every rule catches objectively broken code (a crash, a');
-        console.log('  security leak, or a build/type-strip failure) and always');
-        console.log('  runs. Project conventions (layout, style, process) are');
-        console.log('  guidance in CONVENTIONS.md, not rules here.\n');
+        console.log('  Every rule catches code that is wrong to ship: a crash, a');
+        console.log('  security leak, a build/type-strip failure, or (the one');
+        console.log('  sentinel-based rule, no-scaffold-placeholder) unreplaced');
+        console.log('  scaffold example content. They always run. Project');
+        console.log('  conventions (layout, style, process) are guidance in');
+        console.log('  CONVENTIONS.md, not rules here.\n');
         for (const r of RULES) {
           console.log(`  ${r.name.padEnd(30)} ${r.description}`);
         }

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 });
@@ -676,7 +685,8 @@ export type ActionResult<T> =
       .replace(/`/g, '\\`')
       .replace(/\$\{/g, '\\${');
 
-  await writeFile(join(appDir, 'app', 'layout.ts'), `import { html, cspNonce } from '@webjsdev/core';
+  await writeFile(join(appDir, 'app', 'layout.ts'), `// webjs-scaffold-placeholder. This is the example app chrome (brand, nav, content-width container). Adapt it to your app, then delete this line. webjs check fails while the marker remains.
+import { html, cspNonce } from '@webjsdev/core';
 import '@webjsdev/core/client-router';
 import '../components/theme-toggle.ts';
 // Webjs UI components are tiered:
@@ -837,11 +847,19 @@ ${SHADCN_THEME}
         <span>${name}</span>
       </a>
       <nav class="flex gap-4 items-center">
+        <!-- Example nav. Replace with the real navigation for your app. -->
         \${navLink('/', 'Home')}
         <theme-toggle></theme-toggle>
       </nav>
     </header>
 
+    <!--
+      Content shell. The max-w-[760px] cap is a comfortable READING width,
+      right for prose, forms, and marketing. For a full-bleed app, dashboard,
+      or board, REPLACE it: widen the cap (for example max-w-[1400px]) or
+      drop the cap and mx-auto for an edge-to-edge layout. A wide layout left
+      inside the 760px reading column overflows into a horizontal scrollbar.
+    -->
     <main class="block max-w-[760px] mx-auto px-4 sm:px-6 pt-[72px] pb-12 min-h-screen">
       \${children}
     </main>
@@ -849,7 +867,8 @@ ${SHADCN_THEME}
 }
 `);
 
-  await writeFile(join(appDir, 'app', 'page.ts'), `import { html } from '@webjsdev/core';
+  await writeFile(join(appDir, 'app', 'page.ts'), `// webjs-scaffold-placeholder. This is the example homepage. Replace it with your app's real page, then delete this line. webjs check fails while the marker remains.
+import { html } from '@webjsdev/core';
 import { rubric, displayH1, accentLink } from '../lib/utils/ui.ts';
 import { buttonClass } from '../components/ui/button.ts';
 import { badgeClass } from '../components/ui/badge.ts';
@@ -1067,6 +1086,10 @@ For AI agents, read this before editing scaffolded files:
     Replace them with the app the user actually asked for. Don't ship
     the scaffold's example User model or "Hello from …" page as the
     final product.
+  • This fresh app intentionally FAILS \`webjs check\` with two
+    no-scaffold-placeholder violations (app/page.ts, app/layout.ts).
+    That is the signal to replace the example content. Delete each
+    marker comment line as you do, and the check goes green.
   • Use Prisma + SQLite for app data. It's already wired up. Define
     real models in prisma/schema.prisma and run \`webjs db migrate\`.
     NEVER store app data in JSON files, in-memory arrays, or

package/package.json

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

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/.dockerignore

@@ -6,10 +6,12 @@ node_modules
 # `.webjs/` is ignored EXCEPT for `.webjs/vendor/`, which holds the committed
 # importmap manifest (and optionally downloaded bundle bytes) the server needs
 # at boot without reaching api.jspm.io. DO NOT collapse to `**/.webjs`: parent
-# exclusion blocks child negations and the vendor files would never ship.
-.webjs/*
-!.webjs/vendor/
-!.webjs/vendor/**
+# exclusion blocks child negations and the vendor files would never ship. The
+# `**/` prefix matches `.webjs/` at any depth so a nested build context does
+# not ship the per-machine cache, mirroring the `.gitignore` pattern.
+**/.webjs/*
+!**/.webjs/vendor/
+!**/.webjs/vendor/**
 
 dist
 build

package/templates/AGENTS.md

@@ -14,7 +14,19 @@ now (`app/page.ts` printing "Hello from {{APP_NAME}}", the example `User`
 model in `prisma/schema.prisma`, the `theme-toggle` component, the
 example users module in api/saas templates) are **starting-point
 references, not the final product**. Your job is to replace them with
-the app the user actually asked for.
+the app the user actually asked for. That includes adapting
+`app/layout.ts`, not just the page. Set the real brand, replace the
+example `Home` nav, and pick a content-width container that fits. The
+default `<main class="max-w-[760px]">` is a reading column for prose and
+forms, so for a full-bleed app, dashboard, or board, widen the cap or
+remove it (keep the theme tokens). A wide layout left in the 760px
+reading column overflows into a horizontal scrollbar. This is ENFORCED:
+the example `app/page.ts` and `app/layout.ts` carry a
+`webjs-scaffold-placeholder` marker comment, and `webjs check` fails
+while any marker remains, so this freshly scaffolded app fails the check
+until you replace the example content (or deliberately keep it) and
+delete the marker line. The delivered app must contain only what the
+user asked for, never leftover scaffold code.
 
 **Non-negotiables for every webjs app:**
 
@@ -449,15 +461,18 @@ URLs or transitive deps drift. Pin is a deliberate developer action,
 like `npm install` itself.
 
 **Do NOT modify the `.webjs/` lines in `.gitignore` / `.dockerignore`.**
-The scaffolded pattern is three lines (`.webjs/*` + `!.webjs/vendor/`
-+ `!.webjs/vendor/**`) and is structurally load-bearing. Collapsing it
-to a single `.webjs/` excludes the parent directory; once the parent
-is excluded, git cannot re-include `.webjs/vendor/` via a child
-negation (gitignore semantics: parent exclusion blocks child
-negations). The breakage is invisible: `webjs vendor pin` runs, writes
-files, and git silently ignores them. Production then has no
-importmap.json and the server falls back to calling api.jspm.io on
-every cold start. The `gitignore-vendor-not-ignored` lint rule
+The scaffolded `.gitignore` pattern is three lines (`**/.webjs/*` +
+`!**/.webjs/vendor/` + `!**/.webjs/vendor/**`) and is structurally
+load-bearing. Collapsing it to a single `.webjs/` excludes the parent
+directory; once the parent is excluded, git cannot re-include
+`.webjs/vendor/` via a child negation (gitignore semantics: parent
+exclusion blocks child negations). The breakage is invisible: `webjs
+vendor pin` runs, writes files, and git silently ignores them.
+Production then has no importmap.json and the server falls back to
+calling api.jspm.io on every cold start. The `**/` prefix matters too:
+it ignores `.webjs/` at any depth, so an app nested below its repo root
+(a monorepo package) does not leak its generated `.webjs/routes.d.ts`
+into `git status`. The `gitignore-vendor-not-ignored` lint rule
 (`webjs check`) verifies the pattern with `git check-ignore` and will
 fail CI if it regresses.
 
@@ -765,12 +780,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
 
@@ -800,6 +919,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;
@@ -963,13 +1108,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

@@ -308,11 +308,28 @@ When the user asks the agent to build their actual app:
    need a theme picker.
 4. **Delete the example users module** (api/saas templates) if the app
    doesn't use it.
-5. **Keep:** the Prisma setup, the test config, the agent config files
+5. **Adapt `app/layout.ts` to the app, not just the page.** Set the real
+   brand, replace the example `Home` nav with the app's navigation, and
+   pick a content-width container that fits. The default
+   `<main class="max-w-[760px]">` is a reading column for prose, forms,
+   and marketing. Widen it or drop the cap for a full-bleed app,
+   dashboard, or board, or a wide layout overflows into an unnecessary
+   horizontal scrollbar. Keep the design tokens and theme setup, those
+   are infrastructure.
+6. **Keep:** the Prisma setup, the test config, the agent config files
    (`AGENTS.md`, `CONVENTIONS.md`, `CLAUDE.md`, `.cursorrules`, etc.),
    `lib/prisma.server.ts`, the directory conventions, the design tokens in
    `app/layout.ts`. These are the infrastructure, not the example app.
 
+This is enforced, not just advised. The example `app/page.ts` and
+`app/layout.ts` carry a `webjs-scaffold-placeholder` marker comment, and
+the `no-scaffold-placeholder` check fails while any marker remains, so a
+freshly scaffolded app fails `webjs check` until you address each
+placeholder. The marker is acknowledge-and-remove: replace the example
+content, or deliberately keep it, and in either case delete the marker
+line. So the delivered app contains only what the user asked for, never
+leftover scaffold code.
+
 The scaffold exists so the agent doesn't reinvent the directory layout,
 the Prisma wiring, the test runner config, or the convention files. It
 does NOT exist so the agent ships the example homepage.
@@ -494,14 +511,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
 

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;
+    })());
+  }
+});