@webjsdev/cli 0.10.9 → 0.10.10

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.9",
+  "version": "0.10.10",
   "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/AGENTS.md

@@ -765,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
 
@@ -800,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;
@@ -963,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
 

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