@webjsdev/cli 0.10.48 → 0.10.50

package/README.md

@@ -50,7 +50,7 @@ webjs vendor pin [--download]  # pin client deps to a committable importmap (off
 webjs db <generate|migrate|push|studio|seed>   # drizzle-kit passthrough (+ seed)
 
 webjs ui init                  # initialise @webjsdev/ui in this project
-webjs ui add <names...>        # copy components from the registry (https://ui.webjs.dev/registry/<name>.json)
+webjs ui add <names...>        # copy components from the registry (https://webjs.dev/ui/registry/<name>.json)
 webjs ui list                  # list every component available in the registry
 ```
 
@@ -60,7 +60,7 @@ helpers (`buttonClass`, `cardClass`, …) for the visual primitives and a small
 of stateful custom elements (`<ui-dialog>`, `<ui-tabs>`, `<ui-popover>`) where
 state matters. The package is a hard dependency of `@webjsdev/cli`, so installing
 the CLI gives you `webjs ui` automatically. See
-[https://ui.webjs.dev](https://ui.webjs.dev) for the catalogue.
+[https://webjs.dev/ui](https://webjs.dev/ui) for the catalogue.
 
 ## Scaffolded templates
 

package/bin/webjs.js

@@ -875,7 +875,7 @@ components/schema with the actual app the user requested. Use Drizzle +
 SQLite for persistence (already wired up). Never store app data in JSON
 files.
 
-Full docs: https://docs.webjs.dev`);
+Full docs: https://webjs.dev/docs`);
         process.exit(1);
       }
       const noInstall = rest.includes('--no-install');

package/lib/create.js

@@ -947,10 +947,13 @@ export default cors({
 
 // A GET server action (#488): a read declares its HTTP semantics via reserved
 // sibling exports the framework reads statically. 'method' makes the call ride
-// the URL (cacheable, ETag/304-aware, SSR-seeded on first paint); 'cache' is the
-// max-age in seconds (private by default, do NOT add { public: true } unless the
-// data is identical for EVERY visitor); 'tags' label the cached entry so a
-// mutation can evict it. One function per file.
+// the URL and be ETag/304-aware; 'cache' is what makes the response cacheable at
+// all (the max-age in seconds, private by default, do NOT add { public: true }
+// unless the data is identical for EVERY visitor); 'tags' label the cached entry so a
+// mutation can evict it. All three shape the RPC endpoint a browser import hits,
+// so they do nothing for the in-process call in app/api/users/route.ts; they are
+// here as the idiom to carry into a client that imports the action. One function
+// per file.
 export const method = 'GET';
 export const cache = 30;
 export const tags = () => ['users'];
@@ -966,8 +969,12 @@ export async function listUsers() {
 
 // A mutation server action (#488). With no 'method' export it defaults to POST
 // (CSRF-protected, rich request body). 'invalidates' lists the cache tags to
-// evict on success, so the next listUsers() read refetches fresh instead of
-// serving a stale browser-cached value. One function per file.
+// evict once the action completes without throwing, so a client that read
+// listUsers() refetches fresh instead of serving a stale browser-cached value.
+// (A returned { success: false } envelope still evicts, since the action ran.)
+// It applies on the RPC endpoint a browser import hits. The route.ts in this
+// template calls the function directly, which is in-process, so the config
+// exports do not fire there. One function per file.
 export const invalidates = () => ['users'];
 export async function createUser(input: { name: string; email: string }) {
   // TODO: validate input, persist to database
@@ -977,6 +984,13 @@ export async function createUser(input: { name: string; email: string }) {
     await writeFile(join(appDir, 'app', 'api', 'users', 'route.ts'), `/**
  * /api/users: thin route wrapper over typed server actions.
  * Business logic lives in modules/users/, not here.
+ *
+ * These calls are in-process, so the actions' config exports do NOT apply here.
+ * method / cache / tags / invalidates shape the RPC endpoint a browser import
+ * hits, and nothing else applies them, so this endpoint sets its own headers if
+ * it wants caching. The namespace form of the route() adapter from
+ * \@webjsdev/server (import * as q; export const GET = route(q)) picks up the
+ * declared validate and middleware, which are the two an endpoint can reuse.
  */
 import { listUsers } from '#modules/users/queries/list-users.server.ts';
 import { createUser } from '#modules/users/actions/create-user.server.ts';
@@ -1134,7 +1148,7 @@ ${uiThemeRaw}
     // or shed the whole gallery at once with `gallery:clear`.
     await copyGallery(appDir);
 
-  await writeFile(join(appDir, 'app', 'layout.ts'), `import { html, cspNonce } from '@webjsdev/core';
+  await writeFile(join(appDir, 'app', 'layout.ts'), `import { html, cspNonce, asset } from '@webjsdev/core';
 import '#components/theme-toggle.ts';
 
 /**
@@ -1212,9 +1226,16 @@ export default function RootLayout({ children }: { children: unknown }) {
          public/tailwind.css by css:build (run automatically by the dev and start
          tasks; in dev it is also recompiled on request when a source changes, so
          it never goes stale). A real stylesheet, so the app is fully styled with
-         JavaScript DISABLED (no in-browser compile). -->
+         JavaScript DISABLED (no in-browser compile).
+
+         asset() adds a content hash in production (/public/tailwind.css?v=...)
+         and the framework then serves it immutable for a year, so a deploy that
+         changes the CSS changes the url and no browser or CDN can serve the old
+         bytes. Mark the thing that FETCHES: do not wrap a <link rel="preload">
+         whose asset is really fetched by an @font-face url() in the CSS, or the
+         preload can never match the request and the file downloads twice. -->
 
-    <link rel="stylesheet" href="/public/tailwind.css">
+    <link rel="stylesheet" href=\${asset('/public/tailwind.css')}>
     <style>
       /* Design tokens: ONE definition per colour via light-dark(LIGHT, DARK), so
          a palette change lands in a single place (DRY). The token NAMES are
@@ -1292,7 +1313,7 @@ export default function RootLayout({ children }: { children: unknown }) {
         WebJs Gallery
       </a>
       <nav class="flex items-center gap-4 text-sm" aria-label="Primary">
-        <a href="https://docs.webjs.dev" target="_blank" rel="noopener" class="hidden sm:inline text-muted-foreground hover:text-foreground no-underline transition-colors">Docs</a>
+        <a href="https://webjs.dev/docs" target="_blank" rel="noopener" class="hidden sm:inline text-muted-foreground hover:text-foreground no-underline transition-colors">Docs</a>
         <a href="https://github.com/webjsdev/webjs" target="_blank" rel="noopener" class="hidden sm:inline text-muted-foreground hover:text-foreground no-underline transition-colors">GitHub</a>
         <theme-toggle></theme-toggle>
       </nav>
@@ -1363,7 +1384,7 @@ export default function Home() {
       <!-- Footer: docs + source -->
       <footer class="flex flex-col items-center gap-3">
         <nav class="flex items-center gap-6 text-sm text-muted-foreground" aria-label="WebJs links">
-          <a href="https://docs.webjs.dev" target="_blank" rel="noopener" class="inline-flex items-center gap-2 hover:text-foreground transition-colors no-underline">\${iconBook()}<span>Docs</span></a>
+          <a href="https://webjs.dev/docs" target="_blank" rel="noopener" class="inline-flex items-center gap-2 hover:text-foreground transition-colors no-underline">\${iconBook()}<span>Docs</span></a>
           <a href="https://github.com/webjsdev/webjs" target="_blank" rel="noopener" class="inline-flex items-center gap-2 hover:text-foreground transition-colors no-underline">\${iconGithub()}<span>GitHub</span></a>
         </nav>
         <p class="text-[0.7rem] uppercase tracking-[0.15em] text-muted-foreground m-0 text-center">
@@ -1497,7 +1518,7 @@ ThemeToggle.register('theme-toggle');
   • Use the wired-up database (Drizzle): define real models in
     db/schema.server.ts, then run 'npm run db:generate' and 'npm run db:migrate'.
     Never store app data in JSON files, in-memory arrays, or localStorage.
-  • Full hosted docs are at https://docs.webjs.dev.
+  • Full hosted docs are at https://webjs.dev/docs.
 `);
 
   // Auto-install (default). Detect the package manager from the env so

package/lib/dev-supervisor.js

@@ -51,7 +51,11 @@ export function planDevSupervisor({ isBun, argv, noHot, exists }) {
   for (const dir of ['app', 'components', 'modules', 'lib', 'actions']) {
     if (exists(dir)) watchPaths.push('--watch-path', dir);
   }
-  for (const f of ['middleware.ts', 'middleware.js']) {
+  // Every extension the server's root-middleware lookup accepts, in the same
+  // order. If these two lists diverge, an app gets a middleware that loads but
+  // never restarts the dev server when edited, which is the quiet half of the
+  // bug where a `middleware.ts` was loaded by neither.
+  for (const f of ['middleware.ts', 'middleware.js', 'middleware.mts', 'middleware.mjs']) {
     if (exists(f)) watchPaths.push('--watch-path', f);
   }
   return {

package/package.json

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

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

@@ -4,7 +4,7 @@ You are working on a WebJs app (AI-first, no-build, web-components-first). This
 file is the WORKFLOW contract (git, tests, review). For HOW to build (routing,
 components, actions, styling, the framework API), read
 `.agents/skills/webjs/SKILL.md`, which routes to focused references on demand.
-Read `AGENTS.md` first. Full hosted docs are at https://docs.webjs.dev.
+Read `AGENTS.md` first. Full hosted docs are at https://webjs.dev/docs.
 
 ## Grow the app in place (non-negotiable)
 

package/templates/.agents/skills/webjs/SKILL.md

@@ -9,7 +9,7 @@ Use this skill for end-to-end WebJs app work. It helps you choose the right laye
 
 ## Full Documentation
 
-This skill is the quick guide. When you need the full API reference for a surface, load the matching file in `references/` (listed below). For even deeper framework detail, WebJs ships buildless, so the source you run IS the source you read: look in `node_modules/@webjsdev/{core,server,cli}/` (each package ships its own `AGENTS.md`). The complete hosted docs live at https://docs.webjs.dev.
+This skill is the quick guide. When you need the full API reference for a surface, load the matching file in `references/` (listed below). For even deeper framework detail, WebJs ships buildless, so the source you run IS the source you read: look in `node_modules/@webjsdev/{core,server,cli}/` (each package ships its own `AGENTS.md`). The complete hosted docs live at https://webjs.dev/docs.
 
 ## What WebJs Is
 
@@ -116,6 +116,7 @@ Find the right export fast. Load the linked reference for full examples.
 - `notFound()` / `redirect(url[, status])` control-flow throws (page/layout/action only, NOT `route.ts`). `forbidden()` / `unauthorized()` render the nearest boundary.
 - `Suspense({fallback, children})` page-level streaming; `<webjs-suspense>` component-level streaming.
 - `optimistic()` optimistic UI; `navigate(url)` / `revalidate(url?)` client-router control; `connectWS` / `richFetch`.
+- `asset(path)` content-hashes a `public/` url so a deploy cannot serve stale bytes (`href=${asset('/public/app.css')}`), served `immutable` for a year. Page / layout / metadata route only, inside the render function. See `references/built-ins.md`.
 - Types: `Metadata`, `PageProps<R>`, `LayoutProps<R>`, `RouteHandlerContext<R>`, `WebjsConfig`.
 - `@webjsdev/core/server`: `renderToString` / `renderToStream` (Node side).
 - `@webjsdev/core/directives`: `repeat`, `unsafeHTML` (trusted only), `live`, `keyed`, `guard`, `cache`, `until`, `watch(signal)`, `ref` / `createRef`, `asyncAppend` / `asyncReplace`, `templateContent`. `Task` / `TaskStatus` live at `@webjsdev/core/task`, context (`createContext` / `ContextProvider` / `ContextConsumer`) at `/context`. See `references/components.md` for the directive table + Task + context.

package/templates/.agents/skills/webjs/references/built-ins.md

@@ -82,7 +82,20 @@ export const revalidate = 60;   // cache this page's HTML for 60s
 
 ### Content-hash asset URLs and conditional GET
 
-Both are automatic, prod-focused, and need no config. In production every served module and `public/` asset gets a per-file `?v=<hash>` and `Cache-Control: public, max-age=31536000, immutable`, so a returning client fetches a changed file only when its bytes change. Every cacheable response also carries a weak `ETag`, and a repeat request with a matching `If-None-Match` gets a `304 Not Modified` with no body. Private (`no-store` / `private`) and streamed responses are excluded from the ETag path (no cross-session 304). Dev is byte-faithful (no hashing).
+Both are automatic, prod-focused, and need no config. In production every served MODULE gets a per-file `?v=<hash>`, and a `?v=`-carrying request is answered `Cache-Control: public, max-age=31536000, immutable`, so a returning client fetches a changed file only when its bytes change.
+
+A `public/` asset you reference yourself is opt-in, via `asset()` (#1194):
+
+```ts
+import { html, asset } from '@webjsdev/core';
+html`<link rel="stylesheet" href=${asset('/public/app.css')}>`
+```
+
+That emits `/public/app.css?v=<hash>` in production and gets the immutable year; the same url un-marked gets a ~1h cap and can serve stale bytes from a CDN after a deploy until something purges it. `asset()` resolves on the server; the browser has no resolver and returns the path unchanged. Call it from a PAGE, LAYOUT, or metadata route, which render only on the server. Inside a component that ships to the browser it silently costs you the caching: hydration is a full client re-render, so the bare path overwrites the hashed one and the asset downloads twice. The url stays valid either way, which is why this is a convention rather than a check rule. Under `webjs.basePath`, include the prefix yourself (`asset('/app/public/x.css')`): the framework base-path-prefixes only the urls it emits, so an author-written url is already yours to prefix. Two more constraints: call it INSIDE the render function, because a module-scope call is a side effect the elision analyser reads as client work and it ships the whole module; and mark only files that change with a DEPLOY, because the hash is memoized for the process lifetime, so a `public/` file rewritten in place at runtime would keep its old url while being served `immutable` for a year. Off in dev, so dev output is byte-identical. Only `public/` paths resolve; anything else (and a path that fails to resolve) is returned untouched.
+
+It is opt-in rather than automatic because only the author knows which urls are the REQUEST. Do NOT mark a `rel="preload"` hint whose asset is actually fetched by CSS `url()`: the preload cache is keyed on the full url, so a versioned hint can never satisfy the unversioned request the stylesheet makes, and the file is fetched twice. Mark the thing that fetches, not the hint. Every cacheable response also carries a weak `ETag`, and a repeat request with a matching `If-None-Match` gets a `304 Not Modified` with no body. Unstorable (`no-store`) and streamed responses are excluded from the ETag path. A `private` response IS validated: `private` forbids SHARED storage, not validation, and the ETag hashes that response's own body, so two users with different bodies get different ETags and neither can match the other's, while two users with identical bodies are asking about identical bytes, where a 304 discloses nothing (#1140). That is what keeps the client router's partial responses cheap on a page that opted into caching; a default `no-store` page has nothing to validate either way. Dev is byte-faithful (no hashing).
+
+**A page's ETag is only useful if the page renders the same bytes twice.** The ETag is a hash of the response body, so any per-render-varying value anywhere in the document defeats it: a `Date.now()`, a `Math.random()`, an id from a module-scope counter (which never resets in a long-lived server), or a CSP nonce. The failure is silent and total. The page renders correctly, every content assertion still passes, the header is still present, and the only symptom is that no `If-None-Match` ever matches, so every revalidation ships the whole document instead of an empty 304. A page under CSP is excluded from the server HTML cache for exactly this reason (the nonce must differ per response). If a page opts into a public `Cache-Control`, guard it with a test that renders the page twice, through its layout, and asserts the two outputs are byte-identical.
 
 ## Rate limiting
 

package/templates/.agents/skills/webjs/references/client-router-and-streaming.md

@@ -65,11 +65,20 @@ document.addEventListener('webjs:navigation-error', (e) => {
 });
 ```
 
+**Observing a degradation.** Some conditions make a soft nav impossible, and the router then degrades to a full page load rather than risk a corrupt DOM (the #1015 integrity model). Every such path dispatches `webjs:navigation-fallback` on `document`, in ALL environments including production, with `detail { cause, href, willReload }`. Causes: `no-shared-boundary`, `live-boundaries-malformed`, `incoming-boundaries-malformed`, `readyState-loading`, `deploy-mismatch`, `deploy-mismatch-reload-suppressed`, `navigation-error-unrecoverable`, `revalidation-discarded`. `willReload` is false for a degradation that does NOT reload (a dropped background revalidation), so a listener can tell "this click became a document load" from "a background op was skipped". Not cancelable: by the time it fires the degradation is the only safe option. In dev a deduped console warning also prints.
+
+```ts
+document.addEventListener('webjs:navigation-fallback', (e) => {
+  // A full document load on a click is a UX regression worth knowing about in prod.
+  if (e.detail.willReload) analytics.track('router_full_load', e.detail);
+});
+```
+
 **Form state.** A form submitting through the router gets `aria-busy="true"` for the in-flight duration, plus bubbling `webjs:submit-start` and `webjs:submit-end` (detail `{ form, url, ok }`) events. Style `form[aria-busy="true"]` in pure CSS or listen for the events.
 
 ## Link Prefetch
 
-Same-origin in-app links prefetch speculatively so a click resolves from a warm cache. On by default, no per-link opt-in needed. The default strategy is DEVICE-ADAPTIVE, because one strategy cannot serve both input modalities. On a hover-capable fine pointer the default is `intent` (warm on hover/focus after a ~100ms dwell). On touch the default is `viewport` (warm as links settle on-screen), because touch has no hover. Modality is detected with `matchMedia('(hover: hover) and (pointer: fine)')`, never a UA sniff.
+Same-origin in-app links prefetch speculatively so a click resolves from a warm cache. A reduced fragment is served `private`, so no shared cache can store it even if the CDN ignores `Vary` (Cloudflare honours only `Accept-Encoding`); the `Vary: X-Webjs-Have` marking stays as belt-and-braces rather than as the guarantee (#1140). A full document keeps whatever `metadata.cacheControl` declared, so page-level edge caching is unaffected. Router fetches (navigation and prefetch alike) are sent with `cache: 'no-cache'`, so a page cached in the browser with a `max-age` is revalidated rather than replayed: the deploy check reads `x-webjs-build` / `x-webjs-src` off these responses, and a cached response would hand it pre-deploy ids and hide a deploy for the whole freshness window (#1131). The revalidation is answered with a cheap 304, so the cost is a conditional round-trip rather than a re-download: on a page that opted into caching a fragment is `private` but still carries a validator, since `private` forbids only SHARED storage and has no bearing on whether a response can be validated (#1140); a default `no-store` page has nothing to validate either way. On by default, no per-link opt-in needed. The default strategy is DEVICE-ADAPTIVE, because one strategy cannot serve both input modalities. On a hover-capable fine pointer the default is `intent` (warm on hover/focus after a ~100ms dwell). On touch the default is `viewport` (warm as links settle on-screen), because touch has no hover. Modality is detected with `matchMedia('(hover: hover) and (pointer: fine)')`, never a UA sniff.
 
 Override per link with the `data-prefetch` attribute.
 
@@ -85,6 +94,8 @@ Next-style aliases work (`true` = `render`, `auto` = `viewport`, `false` = `none
 
 A prefetch issues a real GET, so any mutating endpoint MUST be a POST or a `<form>` submission (which the router never prefetches), never a GET link. A `webjs:prefetch` event fires on `document` when a fragment lands in the cache.
 
+**The cache is ANCHOR-VALIDATED, not just URL-keyed (#1114).** A prefetched fragment is a reduced response: the request carries `X-Webjs-Have` (the boundaries the client already holds) and the server returns only the divergent part from the deepest boundary it short-circuited on. That boundary is the fragment's ANCHOR, and the fragment applies to any live DOM that still offers it with the same route-key. So on consume the router checks the anchor, not the whole `have` string: a root-anchored fragment survives an unrelated navigation and stays a cache hit, while one anchored at `/docs` is discarded once you leave /docs, because applying it would hand the swap a tree sharing no boundary with the live DOM, which correctly degrades to a full page load. A discard costs one round-trip. The router also never prefetches the page it is already on (#1106), since that request cannot serve any later navigation and only occupies a capped cache slot; a hover's intent timer routinely fires after the click it belongs to has already swapped, which is when that happens. Both behaviours are internal; nothing to configure.
+
 ## `<webjs-frame>` Partial-Swap Regions
 
 `<webjs-frame>` is WebJs's take on Turbo Frames, so most `<turbo-frame>` muscle memory transfers. It is a lazy, URL-addressable region that swaps on its own, driven by a link or form targeting its id, and it ships zero component JS. Use it for a region that loads or refreshes INDEPENDENTLY of a full-page navigation (a marketing widget, tabbed UI, a filtered results panel), which a page or layout cannot express.

package/templates/.agents/skills/webjs/references/components.md

@@ -120,6 +120,12 @@ class Panel extends WebComponent({ label: String }) {
 
 The full `<slot>` surface works in light DOM with shadow-DOM parity; migrating modes never requires a template rewrite. A forwarded slot projects its content everywhere (client, SSR, hydration).
 
+**A tag name inside an HTML comment is not instantiated.** `<!-- <my-card> is the wrapper -->` documents the template and renders no component, the same as in a browser. That holds for component tags, `<slot>`, and `<webjs-suspense>`. It extends to attribute values and to every element whose content the HTML parser reads as text rather than markup: `<script>`, `<style>`, `<iframe>`, `<xmp>`, `<noembed>`, `<noframes>`, `<plaintext>`, `<textarea>`, `<title>`. (Before #1128 a commented tag was constructed as a real element and ate the rest of the comment along with the markup after it, so an ordinary explanatory comment could silently delete part of the page.)
+
+Two elements are deliberately excluded, and the second matters more. `<template>` content IS parsed and legitimately carries components, which is what Declarative Shadow DOM and streamed swaps rely on. `<noscript>` content is also parsed, because a browser with scripting disabled reads it as markup, and that is the case a progressive-enhancement framework exists to serve, so components inside `<noscript>` render normally.
+
+Element nesting respects comments too: a comment holding the open or close tag of the element it sits inside (`<my-card>kid<!-- </my-card> --></my-card>`) rides along as content, and the element still ends at its real close tag. Script bodies follow the parser's double-escape rule, so the legacy `<!-- <script>... -->` wrapper pattern stays text to its true end.
+
 ```ts
 class MyCard extends WebComponent {
   render() {
@@ -169,7 +175,7 @@ Three decoupled concerns, do not conflate them.
 2. **The client re-fetch default is stale-while-revalidate.** When a prop or dependency change re-runs `async render()`, the previous content stays until the new render resolves. No blank, no flash, no user code.
 3. **`renderFallback()` is the OPTIONAL re-fetch loading UI.** Shown ONLY during a client re-fetch, NEVER on first paint, and it does NOT create a server-streaming boundary.
 
-Errors are isolated per component by default (no user code): a thrown `await` renders a component-scoped error state while siblings render, never bubbling to the route `error.ts`. Override `renderError(error)` only to customize it (dev shows the message, prod stays silent).
+Errors are isolated per component by default (no user code): a thrown `await` renders a component-scoped error state while siblings render, never bubbling to the route `error.ts`. Override `renderError(error)` only to customize it (dev shows the message, prod stays silent). The boundary covers the COMMIT as well as the fetch, so a template that throws while being applied (a refused binding, a value whose `toString` throws) reaches `renderError()` too, and `updateComplete` still settles. Those two halves used to disagree: a fetch rejection was contained and a commit throw escaped as an unhandled rejection that also left `updateComplete` pending forever.
 
 Decision rules. Use `async render()` for request-time server data that should be in the first paint (the default). Add `renderFallback()` when a client re-fetch's stale content would mislead. Use `Task` / signals for genuinely client-only data (a click, viewport, live updates). For SLOW data where blocking the first byte hurts, wrap the region in `<webjs-suspense .fallback=${html\`Loading...\`}>` to stream it (the only way to show a first-paint fallback; see `client-router-and-streaming.md`). Do NOT fetch in `connectedCallback` for data knowable server-side, and do NOT prop-drill what a leaf can fetch itself.
 

package/templates/.agents/skills/webjs/references/data-and-actions.md

@@ -96,7 +96,7 @@ const [updated] = await db.update(posts).set({ title }).where(eq(posts.id, id)).
 await db.delete(posts).where(eq(posts.id, id));
 ```
 
-A `.returning()` row is the table's own columns only, never `with` relations. When the caller wants a joined shape, re-read with `db.query.*` or splice the already-known related value in by hand. Full surface at https://docs.webjs.dev.
+A `.returning()` row is the table's own columns only, never `with` relations. When the caller wants a joined shape, re-read with `db.query.*` or splice the already-known related value in by hand. Full surface at https://webjs.dev/docs.
 
 ## Input validation at the boundary
 
@@ -139,7 +139,8 @@ export const middleware = [requireAuth];           // async (ctx, next) => resul
 export async function updateUser(id: number, patch: Partial<User>) { /* ... */ }
 ```
 
-- A **GET** rides args in the URL (POST fallback over a 4KB cap), is CSRF-exempt, and carries `Cache-Control` + a weak `ETag` (304 on `If-None-Match`) + `X-Webjs-Tags`. A **mutation** (POST/PUT/PATCH/DELETE) sends the rich body (DELETE rides the URL), is CSRF-protected, and on success evicts its `invalidates` tags and reports them via `X-Webjs-Invalidate`. A method mismatch is a `405` + `Allow`.
+- A **GET** rides args in the URL (POST fallback over a 4KB cap), is CSRF-exempt, and carries a weak `ETag` (304 on `If-None-Match`); with a `cache` export it also carries `Cache-Control` + `X-Webjs-Tags` (without one it is `no-store`, so caching is opted into by `cache`, not by the verb). A **mutation** (POST/PUT/PATCH/DELETE) sends the rich body (DELETE rides the URL), is CSRF-protected, and once it completes without throwing evicts its `invalidates` tags and reports them via `X-Webjs-Invalidate` (a returned `{ success: false }` envelope still evicts, since the action ran). A method mismatch is a `405` + `Allow`.
+- The `cache` object maps onto the `Cache-Control` header. The number shorthand `cache = 60` means `{ maxAge: 60 }`. `maxAge` is the freshness window in seconds (`max-age=<n>`), `swr` is a stale-while-revalidate grace window in seconds (`stale-while-revalidate=<n>`, an expired response is still served instantly while the browser revalidates in the background, usually a bodyless 304 thanks to the ETag), and `public` flips the scope from the default `private`. So `{ maxAge: 60, swr: 300 }` emits `private, max-age=60, stale-while-revalidate=300`.
 - **SAFETY.** `cache` with `public: true` SHARES one response across ALL users, keyed only by URL + args. Use it ONLY for data identical for every visitor (the same rule as a page's `export const revalidate`), never for a session or per-user read.
 - Per-action `middleware` short-circuits by returning an `ActionResult` instead of calling `next()`, and accumulates context the action reads via `actionContext()` from `@webjsdev/server`. Each middleware is `async (ctx, next) => result` where `ctx` is `{ request, args, signal, context }`. It writes to the shared bag `ctx.context.<key>` (for example `ctx.context.user = user`), which is exactly what `actionContext().user` reads back in the action. A direct server-to-server call skips the RPC boundary (so its middleware does NOT run), so the action must guard rather than assume a middleware-set value is present.
 
@@ -201,4 +202,4 @@ import type { Post } from '#db/schema.server.ts';
 import { posts } from '#db/schema.server.ts';
 ```
 
-Keep the wire shape in a browser-safe `modules/<feature>/types.ts` with NO runtime import from a `.server.ts` file or from `db/`. Define a hand-written DTO, or a type-only derivation (`import type { Post } ...; export type PostFormatted = Omit<Post, 'createdAt'> & { createdAt: string }`). Never `export *` or a value re-export from a `.server.ts` in `types.ts`; that carries the runtime table bindings and breaks any component importing the types. Full reference at https://docs.webjs.dev.
+Keep the wire shape in a browser-safe `modules/<feature>/types.ts` with NO runtime import from a `.server.ts` file or from `db/`. Define a hand-written DTO, or a type-only derivation (`import type { Post } ...; export type PostFormatted = Omit<Post, 'createdAt'> & { createdAt: string }`). Never `export *` or a value re-export from a `.server.ts` in `types.ts`; that carries the runtime table bindings and breaks any component importing the types. Full reference at https://webjs.dev/docs.

package/templates/.agents/skills/webjs/references/muscle-memory-gotchas.md

@@ -43,6 +43,67 @@ const users = await getUsers();
 
 There is no React `cache()`, `use()`, or `unstable_cache`. Caching is the `cache()` query helper, `export const revalidate` on a page, or `export const cache` on a GET action.
 
+### A function in `<form action=${fn}>` is refused, not stringified
+
+Next binds a Server Action with `<form action={createTodo}>` and React serializes the binding into hidden fields. WebJs does not read that shape. A function interpolated into `action=` is a hard render error.
+
+The reason is a source leak. During SSR a `.server.ts` import is the ACTUAL function (the RPC stub exists only in the browser), and `action=` is an ordinary attribute hole, so stringifying it would write the function's body into the HTML every visitor downloads, including any literal inside it. The renderer throws instead, on the server and on the client, for `action=` and `formaction=` alike.
+
+What escapes is the SOURCE the runtime reports, and how much that includes depends on the runtime. The body always goes: your query shapes, your table and column names, your internal paths, and any credential written inline.
+
+Whether an OUTER value goes with it is not something to rely on either way. `Function.prototype.toString` returns source text, so on Node a module-scope `const` the body reads appears as its identifier. Bun transpiles the module before the engine sees it and can fold that literal into the body, so the same action reports the VALUE:
+
+```
+// const VENDOR_API_KEY = 'sk_live_…';  then used as `Bearer ${VENDOR_API_KEY}`
+node 26  Authorization: `Bearer ${VENDOR_API_KEY}`      identifier only
+bun 1.3  Authorization: "Bearer sk_live_…"              the key itself
+```
+
+Do not go looking for the rule that decides when it folds. Export status, read count, declaration position, and whether the module has an import have each been measured as the deciding factor and each produced a counterexample on the same bun version, so whatever the optimizer keys on is finer than any of them. The two rows above are one measurement on two specific versions, not a per-runtime guarantee: read them as proof that the boundary moves, never as a promise that Node keeps an outer binding private.
+
+So treat everything reachable from the action as exposed. That is the assumption the refusal is built on, it is the only one that holds across runtimes, and it is the only one that stays true when the transpiler changes.
+
+The refusal covers the shape, not one spelling of it. Every hole form is refused (`action=${fn}`, `action="${fn}"`, the mixed `action="/x/${fn}"`), and so is a function wrapped in an array (`action=${[fn]}`), since an array stringifies each element through `String()` and leaks identically. Casing does not help either: `formAction=` and `ACTION=` fold to the same rule.
+
+**Commenting the form out does not disable the hole.** A comment is HTML, the interpolation is JavaScript, and the renderer emits a comment's holes raw, so `<!-- <form action=${createTodo}> -->` still ships the whole action body with no throw and no log. Delete the binding instead of commenting around it. This is the one shape in this section that leaks silently, which is exactly why it is worth knowing.
+
+It is not special to comments. `String(fn)` returns source text wherever it runs, so a bare function in a text child (`<div>${fn}</div>`) or any unclaimed attribute (`title=${fn}`) writes the same body out. Only the two form-action attribute names are refused today; treat a function anywhere else in a template as a mistake that ships, and reach for `@event=${fn}` or a custom element's `.prop=${fn}`, neither of which stringifies.
+
+The refused and allowed shapes in full. Every "no" row is a binding that stringifies nothing, so refusing it would break working code rather than close a leak:
+
+| Written as | Refused? | Why |
+|---|---|---|
+| `action=` / `formaction=` | yes | ordinary attribute, stringified into the HTML |
+| `.action=` on a native form | yes | the property reflects, so the source lands in the DOM on the client |
+| `.formAction=` on a button or input | yes | same reason, that is where `formAction` reflects |
+| `.action=` on any other native tag | **no** | a plain expando (`<div .action=${fn}>`, `<button .action=${fn}>`), reflecting nothing, so nothing reaches the markup |
+| `.action=` on a custom element | **no** | an author-defined property, not a reflected IDL attribute; a function is a legitimate value. Holds for a PLAIN prop: one declared `reflect: true` writes `String(value)` to the attribute on a path outside these commit sites, so it still emits the source |
+| `?action=` | yes | never leaked, but it is meaningless, so it is refused rather than silently emitting a bare `action=""` |
+| `@action=` unquoted | **no** | an event listener, and a function is exactly what one takes |
+| `@action="${fn}"` quoted | yes | quoting makes it an ordinary attribute again, so it leaks |
+
+That last row is the one to remember: quoting a binding hole turns it back into a plain attribute, which is why invariant 4 requires `@`, `.` and `?` holes to be unquoted.
+
+`.action=${fn}` on a native form is refused during SSR too, even though the property is dropped there and nothing could leak, so a page cannot render clean on the server and then throw on hydration.
+
+**Inside a component you may never see the error.** Per-component SSR error isolation contains the throw, so development shows an error box in place of the component and production renders it empty with the page still returning 200. A form that has silently vanished in production is this bug wearing a disguise; the message is in the server log. Nothing leaks either way.
+
+Two things that "renders it empty" understates, both worth knowing before you go looking:
+
+- **Anything slotted into the failing component goes with it.** The isolation replaces the element from its opening tag through its matching close, so a shell or layout component whose template holds the bad form takes the page's whole authored body with it. Put `action=${fn}` in a shared header and every page renders a 200 with an empty body, not one missing header.
+- **On a route with a `loading.{js,ts}`, there is no log line either.** That wraps the page in a `Suspense` boundary, so the page body renders AFTER the 200 and the shell have been flushed, and a boundary that throws there is currently swallowed with no server log, no `onError`, and no error boundary. The visitor gets chrome and an empty body; with JS off the skeleton simply stays. That silence is a known framework gap rather than intended behaviour, so do not read the missing log line as evidence the render succeeded.
+
+```ts
+// WRONG: throws at render; it would have leaked the action's body.
+import { submitFeedback } from '#modules/feedback/actions/submit-feedback.server.ts';
+html`<form method="post" action=${submitFeedback}>`;
+// RIGHT: omit action entirely to post to the page's own url, and handle the
+// submission in that page's `action` export.
+html`<form method="post">`;
+```
+
+A string stays a string: `action="/search"` and `action=${'/search'}` are unchanged. Other attributes keep their existing stringify behaviour; only `action` and `formaction` are claimed.
+
 ### `params` and `searchParams` are awaitable AND synchronously readable
 
 Next 15/16 made `params` / `searchParams` Promises. WebJs supports BOTH, so either muscle memory is correct.

package/templates/.agents/skills/webjs/references/routing-and-pages.md

@@ -94,6 +94,8 @@ export async function POST(req: Request) {
 
 Optional root-level plus per-segment. The default export is `async (req, next) => Response`. Return a Response to short-circuit, or call `next()` and post-process. Per-segment middleware applies to its subtree, outermost to innermost.
 
+The root file sits beside `app/`, not inside it, and may be `middleware.ts` / `.js` / `.mts` / `.mjs` (`.ts` wins if more than one exists). A per-segment `app/<segment>/middleware.*` takes any of the same extensions.
+
 ## Metadata and `generateMetadata`
 
 A page exports `metadata` (static) or `generateMetadata(ctx)` (request-scoped, takes precedence). Values flow into `<head>` at SSR and merge across nested layouts (deeper wins). Type both with `Metadata`; `MetadataContext` types the argument. The surface is Next.js-compatible.
@@ -108,7 +110,7 @@ export async function generateMetadata(ctx: MetadataContext): Promise<Metadata>
 }
 ```
 
-Common fields: `title` (string or `{ template, default, absolute }`), `description`, `keywords`, `metadataBase` (resolves relative URLs in `openGraph` / `twitter` / `alternates` / `icons`), `openGraph`, `twitter`, `robots`, `alternates.canonical`, `icons`, `manifest`, and `jsonLd` (schema.org structured data, single object or array, HTML-safe-escaped automatically). `viewport`, `themeColor`, and `colorScheme` may also be set via a split `export const viewport = { ... }`. `cacheControl` is emitted as a response HEADER (not a `<meta>`); pages default to `no-store`, and a `public` value enables conditional GET (a weak `ETag` + `304`). See https://docs.webjs.dev for the full field list.
+Common fields: `title` (string or `{ template, default, absolute }`), `description`, `keywords`, `metadataBase` (resolves relative URLs in `openGraph` / `twitter` / `alternates` / `icons`), `openGraph`, `twitter`, `robots`, `alternates.canonical`, `icons`, `manifest`, and `jsonLd` (schema.org structured data, single object or array, HTML-safe-escaped automatically). `viewport`, `themeColor`, and `colorScheme` may also be set via a split `export const viewport = { ... }`. `cacheControl` is emitted as a response HEADER (not a `<meta>`); pages default to `no-store`, and any other value enables conditional GET (a weak `ETag` + `304`), `private` included. See https://webjs.dev/docs for the full field list.
 
 ## Control-flow throws
 

package/templates/.agents/skills/webjs/references/runtime.md

@@ -35,9 +35,14 @@ Three seams pick a runtime-specific implementation, all inside the framework, no
 | Hot reload | `node --watch` | `bun --hot` |
 | WebSocket | the `ws` library | native `Bun.serve` + a bridge adapter |
 | 103 Early Hints | yes | no (`Bun.serve` has no informational-response API) |
+| Reverse-proxy headers | `X-Forwarded-Proto` / `X-Forwarded-Host` honored | same |
 
 The 103 Early Hints gap costs only a small first-load latency edge where an edge proxy forwards the 103, never correctness. The `modulepreload` hints still ship in the document head on both runtimes.
 
+Behind a TLS-terminating proxy (Railway, Fly, Render, Cloudflare, nginx), both shells rewrite the request URL from `X-Forwarded-Proto` / `X-Forwarded-Host`, so `ctx.url` in a page, `req.url` in a `route.{js,ts}` handler, and every absolute URL you build from either carry the ORIGINAL scheme and host rather than the internal `http://container` hop. A comma-separated chain (a CDN in front of a load balancer) takes the value closest to the client, only `http` and `https` are accepted as a scheme, and a malformed host is ignored rather than failing the request. This was Bun-only broken before #1090, which shipped an `http://` `og:image` on an HTTPS site.
+
+Two limits worth knowing. `WEBJS_NO_TRUST_PROXY=1` stops the URL rewrite (and the HSTS scheme check) from trusting the headers when the container is directly exposed, but it is not a global switch: the CSRF host check still reads `X-Forwarded-Host` regardless. And this rewrite belongs to `startServer`. An app embedded through `createRequestHandler` gets the `Request` its host adapter built, so that adapter owns the correction, the same boundary that already applies to the trusted client IP.
+
 ## Scaffolding a Bun app
 
 `webjs create <name>` defaults to Node. Add `--runtime bun` for a Bun-flavored app (or run `bun create webjs <name>`, which auto-detects Bun from the invoking package manager):

package/templates/.agents/skills/webjs/references/service-worker.md

@@ -40,7 +40,9 @@ With WebJs's CSP enabled (`webjs.csp` in package.json), stamp the nonce on the s
 Registered from `/sw.js`, the worker's scope is the site root (`/`), so it sees every navigation and same-origin asset request. Your worker file lives at `public/sw.js`, and although most `public/*` assets serve at `/public/<name>`, the framework serves this one (and `public/offline.html`) at the SITE ROOT with a `Service-Worker-Allowed: /` header, so `register('/sw.js')` resolves to a 200 and the worker controls the whole origin.
 
 - **Navigations are network-first.** The worker tries the network first, so the user sees fresh server-rendered HTML, and it caches each successful page (the SSR shell). When the network fails, it serves the cached page if you have visited it, otherwise `/offline.html`. Network-first means the cache never makes a page go stale; it is purely an offline safety net.
-- **Static assets are stale-while-revalidate.** Same-origin modules (the per-file ESM the no-build runtime serves), the framework runtime under `/__webjs/core/`, vendor bundles under `/__webjs/vendor/`, and `public/` assets are served from cache when present and refreshed in the background. 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.
+- **Static assets are stale-while-revalidate.** Same-origin modules (the per-file ESM the no-build runtime serves), the framework runtime under `/__webjs/core/`, vendor bundles under `/__webjs/vendor/`, and `public/` assets are served from cache when present and refreshed in the background. In production the framework-emitted URLs (modules, the core runtime, vendor bundles) carry a `?v=<hash>` content fingerprint automatically, so a changed file gets a new URL and the cache cannot serve stale bytes for those.
+
+  A `public/` asset is the exception, and it matters most here. Its URL is fingerprinted only when you mark it with `asset()` (`href=${asset('/public/app.css')}`, see `built-ins.md`). An un-marked `public/` URL is stable across deploys, so the worker keeps serving the CACHED copy and revalidates in the background, which means the first load after a deploy renders the OLD bytes. Do not rely on the worker's cache version to save you: it is derived from the deploy build id, which is a deploy fingerprint rather than a per-file content hash, so a deploy that only changes a `public/` file need not change it. Mark any `public/` asset whose bytes change with `asset()`.
 
 **Never cached:** non-GET requests (writes), cross-origin requests, the action RPC endpoint (`/__webjs/action/`), and the dev-only `/__webjs/events` (SSE) and `/__webjs/reload.js`. Keeping writes and RPC off the cache means the worker can never serve a stale mutation result or replay a POST, so correctness is unaffected whether the worker is active or not.
 

package/templates/.agents/skills/webjs/references/styling.md

@@ -206,3 +206,32 @@ new ResizeObserver(apply).observe(hdr);
 ```
 
 For a dashboard, an alternative is an app-shell scroll container (a non-scrolling `100dvh` flex column with `<main>` as the internal scroller), which needs no offset but changes the scroll model.
+
+### A fixed header and a modal that locks scroll
+
+Anything that locks page scroll (a modal, a drawer, an off-canvas menu) hides the page scrollbar, and a classic scrollbar takes real layout width, so hiding it widens the viewport. The usual compensation is padding the body, which holds in-flow content still. **It does nothing for a fixed header**, because a fixed box lays out against the initial containing block, never against the body's padding box, so the header widens with the viewport and its centred content slides right by half the scrollbar width.
+
+`@webjsdev/ui`'s `<ui-dialog>` / `<ui-alert-dialog>` handle this for you (#1144). Their scroll lock reserves the scrollbar gutter for its duration, so the viewport width never changes and nothing moves. It leaves the gutter alone if your page already declared its own `scrollbar-gutter`, on the assumption that a page which made that choice meant it.
+
+Engines differ, and the lock does not need to know which one it is on. Where the gutter is honoured (measured on Chromium) nothing moves and the lock does nothing else. Where it is ignored (measured on WebKit) the viewport does widen, so the lock measures how much, pads `<html>` by it to hold in-flow content still (added to any padding you already had, and restored on close), and publishes the amount as `--wj-scrollbar-compensation` so a fixed element can opt in with one line:
+
+```css
+header { position: fixed; inset-inline: 0; top: 0; border-right: var(--wj-scrollbar-compensation, 0px) solid transparent; }
+```
+
+A transparent border rather than `padding-right`, for two reasons. It composes with whatever padding the element already has, where a padding form has to restate that base value and restate it again per responsive variant. And a background still paints across a border, so a header that carries its own background stays full bleed instead of ending short of the edge. Declare it after your Tailwind link if you use the `border-*` utilities, since those set `border-right-color` too.
+
+The property is only set while a lock is active AND the viewport actually widened, so the `0px` fallback covers every other moment and the two mechanisms never double-compensate. If you find inline `padding-right` on your `<html>` while a modal is open, that is this, and it comes off on close.
+
+**Put it on the element that is both viewport-width and painting.** Both halves are load-bearing, and getting either wrong fails quietly.
+
+- **Viewport-width**, or a left-aligned child still moves. Insetting a `max-width` container holds its CENTRED children still but not its leading ones, because the container's own box is not what widened. This is easy to miss: measure a left-aligned child, not just a centred one.
+- **Painting**, or the background stops short of the widened edge. Insetting a wrapper that paints nothing insets the child that does, which leaves an unpainted strip.
+
+In this repo `examples/blog` has one element that is both (the fixed header paints its own chrome, so the border goes straight on it), and `website` has a non-painting fixed wrapper around a painting header around a centring bar, where the header is the one that qualifies.
+
+Rolling your own scroll lock? Three things the kit learned the hard way, and the first is that almost every implementation of this (including Next's own dev overlay and Radix) gets the fixed case wrong by design.
+
+1. Reserve the gutter rather than relying on padding alone, or a fixed element will jump however carefully you compensate the body.
+2. When you do pad, pad `<html>`, not `<body>`. A `max-width` body does not widen when the viewport does, so padding it misses the shift entirely, while padding the root holds in-flow content whatever the body's width is.
+3. Measure the root's own border box to decide the amount. `documentElement.clientWidth` can grow while nothing actually moved (Chromium reports exactly that under a reserved gutter), and a `position: fixed` probe reads its pre-lock box on WebKit until the next rendering update, so both mislead.

package/templates/AGENTS.md

@@ -25,7 +25,7 @@ This is what separates a working app from a broken one.
    native ES modules, so the source you run IS the source you read. When you
    need a precise API signature or behavior, open the package source under
    `node_modules/@webjsdev/*` directly (each package ships its own `AGENTS.md`).
-   The full hosted docs are at https://docs.webjs.dev.
+   The full hosted docs are at https://webjs.dev/docs.
 
 {{PLAYBOOK}}
 

package/templates/gallery/app/examples/todo/page.ts

@@ -14,7 +14,8 @@ import '#modules/todo/components/todo-app.ts';
 export const metadata: Metadata = { title: 'Todo (optimistic UI) | examples' };
 
 export default async function TodoExample() {
-  // SSR-fetched and seeded, so <todo-app> paints the real list on first byte.
+  // Fetched here on the server and handed down as a property, so <todo-app>
+  // paints the real list on the first byte with nothing to fetch on hydration.
   const todos = await listTodos();
   return html`
     ${pageHeading('Optimistic todo')}

package/templates/gallery/app/features/caching/page.ts

@@ -3,9 +3,9 @@
 // changes once per window: reload inside 10s and it is identical, reload after
 // and it refreshes. SAFETY: only cache a page that is identical for every
 // visitor (no cookies(), no session, no per-user data), since the key is the URL
-// alone. For per-query reads use cache() + tags with revalidateTag; for assets
-// use HTTP Cache-Control + ETag (conditional GET).
-import { html } from '@webjsdev/core';
+// alone. For per-query reads use cache() + tags with revalidateTag; for a
+// public/ asset use asset(), demonstrated at the bottom of this page.
+import { html, asset } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/caching/components/cache-buster.ts';
@@ -34,7 +34,9 @@ export default function CachingExample() {
       Only for pages identical for every visitor. For per-user or per-query data
       use <code>cache()</code> with <code>tags</code> and
       <code>revalidateTag</code>, or a GET action's
-      <code>export const cache</code>.
+      <code>export const cache</code>, which the
+      <a class="text-primary underline underline-offset-2" href="/features/server-actions">server actions card</a>
+      demonstrates end to end.
     </p>
     <p class="text-muted-foreground text-sm">
       A mutation evicts the cache on demand. Click below (it calls
@@ -44,5 +46,27 @@ export default function CachingExample() {
       copy until the window elapses.
     </p>
     <cache-buster></cache-buster>
+
+    <h2 class="mt-8 mb-2 font-semibold">Caching a public/ asset</h2>
+    <p class="mb-2">
+      A file in <code>public/</code> sits at a stable url, so after a deploy a
+      browser or CDN can keep serving the PREVIOUS bytes until its cache
+      expires. Wrap the url in <code>asset()</code> and it gains a content hash,
+      which the framework then serves <code>immutable</code> for a year:
+    </p>
+    <pre class="mb-2 overflow-x-auto rounded-md bg-muted p-3 text-sm"><code>&lt;link rel="stylesheet" href=\${asset('/public/tailwind.css')}&gt;</code></pre>
+    <p class="mb-2">
+      This app's stylesheet resolves to
+      <code class="font-mono text-primary">${asset('/public/tailwind.css')}</code>
+      (the hash appears in production only, so dev output stays byte-identical).
+      New bytes mean a new url, so a stale copy can never be served.
+    </p>
+    <p class="text-muted-foreground text-sm">
+      Mark the thing that FETCHES, not a hint. Wrapping a
+      <code>&lt;link rel="preload"&gt;</code> whose asset is really fetched by an
+      <code>@font-face url()</code> in your CSS would version the hint but not
+      the request, so the preload could never match and the file would download
+      twice.
+    </p>
   `;
 }

package/templates/gallery/app/features/server-actions/page.ts

@@ -2,6 +2,7 @@ import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/server-actions/components/greeter.ts';
+import '#modules/server-actions/components/clock-reader.ts';
 
 export const metadata: Metadata = { title: 'Server actions (.server vs use server) | features' };
 
@@ -20,5 +21,47 @@ export default function ServerActionsExample() {
     </p>
     <p class="text-muted-foreground mb-4 text-sm">Signed out, the greeter returns a real 401. <a class="text-primary underline underline-offset-2" href="/features/auth/login">Sign in</a> first to see it succeed. (This card depends on the auth card; prune both together.)</p>
     <server-greeter></server-greeter>
+
+    <h2 class="text-xl font-semibold mt-10 mb-3">HTTP verbs and caching</h2>
+    <p class="text-muted-foreground mb-4">
+      An action declares its HTTP semantics through reserved sibling exports the
+      framework reads statically, the same way a page declares
+      <code class="font-mono">export const revalidate</code>. The read below sets
+      <code class="font-mono">method = 'GET'</code>, so its args ride the URL, it is
+      CSRF-exempt, and it carries a weak ETag, so a revalidated read whose result has
+      not changed answers 304. Caching itself is opted into by the
+      <code class="font-mono">cache</code> export below, not by the verb: a GET without
+      one is <code class="font-mono">no-store</code>. An action with no
+      <code class="font-mono">method</code> export is a POST mutation. Seeding is a
+      separate mechanism and needs no verb: an action invoked during a fully
+      buffered SSR render has its result serialized into the page, so the first
+      client call reads that seed instead of making a hydration round-trip. A page
+      that streams (a <code class="font-mono">Suspense</code> or
+      <code class="font-mono">&lt;webjs-suspense&gt;</code> boundary) emits no seed
+      block, so its actions do call out on hydration.
+    </p>
+    <p class="text-muted-foreground mb-4">
+      <code class="font-mono">cache = 10</code> is the max-age in seconds, and it is
+      <strong class="text-foreground">private</strong> by default. Reach for
+      <code class="font-mono">{ public: true }</code> only when the data is identical
+      for every visitor, because a shared cache keys the entry on the URL and args
+      alone. That is the same safety rule as a page's
+      <code class="font-mono">export const revalidate</code>. The number is shorthand
+      for the object form, so
+      <code class="font-mono">cache = { maxAge: 10, swr: 30 }</code> keeps serving an
+      expired entry for another thirty seconds while the browser revalidates it in
+      the background. There is no separate <code class="font-mono">swr</code> export.
+    </p>
+    <p class="text-muted-foreground mb-4">
+      <code class="font-mono">tags</code> labels the cached entry and
+      <code class="font-mono">invalidates</code> on the mutation evicts it by name.
+      The read reports how many times it actually ran on the server, so press Read twice
+      inside ten seconds and that count does not move: the second answer came from the
+      browser cache without reaching the server. Then bump the counter and read again.
+      The count moves and the value is fresh, because the mutation reported its
+      invalidated tag and the next read bypassed the stale entry instead of waiting out
+      the window.
+    </p>
+    <clock-reader></clock-reader>
   `;
 }

package/templates/gallery/modules/auth/queries/current-user.server.ts

@@ -2,11 +2,13 @@
 
 import { getCurrentUser } from '../auth.server.ts';
 
-// This read deliberately stays POST-default (no 'method' export). A GET server
-// action (a cacheable, SSR-seeded read) is wrong for a per-session lookup: the
-// result differs per user and changes on sign-in / sign-out, so it must never be
-// browser-cached or shared. Reserve GET + cache + tags for data identical for
-// every visitor.
+// This read deliberately stays POST-default (no 'method' export). A per-session
+// result differs per user and changes on sign-in / sign-out, so it must never
+// end up in a cache, and GET is the verb a `cache` window would later be added
+// to. Keeping it POST keeps that door shut. Reach for GET + cache + tags on a
+// read stable enough to serve twice, and for `{ public: true }` only when the
+// data is identical for every visitor. (Staying POST costs nothing on the first
+// paint, since SSR seeding applies to an action of any verb.)
 export async function currentUser() {
   return getCurrentUser();
 }

package/templates/gallery/modules/gallery/nav.ts

@@ -27,7 +27,7 @@ export const FEATURE_GROUPS: NavGroup[] = [
   {
     label: 'Data & actions',
     items: [
-      { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, and why the boundary matters.' },
+      { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, plus the HTTP-verb config exports that make a read a cached GET.' },
       { href: '/features/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the WebJs equivalent of a Next route handler.' },
       { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form posting to the page action, with server-side validation errors.' },
       { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'The imperative optimistic(signal, value, action) flip: instant update, automatic rollback on failure.' },

package/templates/gallery/modules/server-actions/actions/bump-clock.server.ts

@@ -0,0 +1,20 @@
+'use server';
+// A mutation paired with the cached GET in ../queries/read-clock.server.ts. With
+// no `method` export it defaults to POST (CSRF-protected, rich request body).
+//
+// `invalidates` lists the cache tags to evict when the action completes. The
+// server drops those tags from its own cache() entries and reports them on the
+// response, so the client coordinator marks them stale and the NEXT readClock()
+// bypasses its browser-cached copy instead of serving a value the mutation just
+// made wrong. Without this export the read would keep answering from cache until
+// its max-age elapsed.
+import type { ActionResult } from '@webjsdev/server';
+import { bumpReading } from '../utils/clock.server.ts';
+
+export const invalidates = () => ['clock'];
+
+export async function bumpClock(): Promise<ActionResult<{ reading: number }>> {
+  // Mutations return the ActionResult envelope, so a caller narrows one shape
+  // whether the write succeeded or failed.
+  return { success: true, data: { reading: bumpReading() } };
+}

package/templates/gallery/modules/server-actions/components/clock-reader.ts

@@ -0,0 +1,98 @@
+// Drives the GET-versus-mutation pair. Both are imported normally (the client
+// import is rewritten to a typed RPC stub); the verbs are declared on the action
+// files, so nothing here changes between a GET and a POST call site.
+//
+// The reads are click-driven on purpose. A read issued during SSR would resolve
+// from the action seed on its first client call, so "watch it hit the network"
+// would be wrong for the first paint.
+import { WebComponent, signal, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { buttonClass } from '#components/ui/button.ts';
+import { readClock } from '../queries/read-clock.server.ts';
+import { bumpClock } from '../actions/bump-clock.server.ts';
+
+interface Row {
+  reading: number;
+  serving: number;
+  at: string;
+  clickedAt: string;
+}
+
+export class ClockReader extends WebComponent {
+  private rows = signal<Row[]>([]);
+  private busy = signal(false);
+  private error = signal('');
+
+  // Both timestamps are formatted here, in the visitor's timezone, so the server
+  // instant and the click time are directly comparable wherever this is deployed.
+  private clock(value: Date | string): string {
+    return new Date(value).toLocaleTimeString('en-US', { hour12: false });
+  }
+
+  async read() {
+    // `?disabled` only lands on the next render commit, so a second click in the
+    // same task would fire a second request. The signal is the real guard.
+    if (this.busy.get()) return;
+    this.busy.set(true);
+    this.error.set('');
+    const clickedAt = this.clock(new Date());
+    try {
+      // A GET action returns its value directly. The stub THROWS on a transport
+      // failure, so the call is guarded the same way the envelope is narrowed.
+      const r = await readClock();
+      this.rows.set([{ ...r, clickedAt }, ...this.rows.get()].slice(0, 6));
+    } catch {
+      this.error.set('The read failed. Is the server still running?');
+    } finally {
+      this.busy.set(false);
+    }
+  }
+
+  async bump() {
+    if (this.busy.get()) return;
+    this.busy.set(true);
+    this.error.set('');
+    try {
+      // A mutation returns the ActionResult envelope, so narrow on success.
+      const r = await bumpClock();
+      if (!r.success) this.error.set(r.error ?? 'The bump failed.');
+    } catch {
+      this.error.set('The bump failed. Is the server still running?');
+    } finally {
+      this.busy.set(false);
+    }
+  }
+
+  render() {
+    const rows = this.rows.get();
+    return html`
+      <div class="${cardClass()} grid gap-4 p-5 max-w-[520px]">
+        <div class="flex flex-wrap gap-2">
+          <button type="button" @click=${() => this.read()} ?disabled=${this.busy.get()}
+            aria-busy=${this.busy.get() ? 'true' : 'false'}
+            class=${buttonClass()}>Read</button>
+          <button type="button" @click=${() => this.bump()} ?disabled=${this.busy.get()}
+            aria-busy=${this.busy.get() ? 'true' : 'false'}
+            class=${buttonClass({ variant: 'secondary' })}>Bump the counter</button>
+        </div>
+        <!-- The results are swapped in after a click, so they are announced. -->
+        <div role="status" aria-live="polite">
+          ${rows.length
+            ? html`
+                <ul class="m-0 grid gap-1 list-none p-0 font-mono text-sm">
+                  ${rows.map((r) => html`
+                    <li class="flex justify-between gap-4">
+                      <span class="text-foreground">reading #${r.reading}, served ${r.serving} at ${this.clock(r.at)}</span>
+                      <span class="text-muted-foreground">clicked ${r.clickedAt}</span>
+                    </li>
+                  `)}
+                </ul>
+              `
+            : html`<p class="m-0 text-sm text-muted-foreground">Press Read twice in a row, then bump and read again.</p>`}
+        </div>
+        ${this.error.get() ? html`<p role="alert" class="m-0 text-sm text-destructive">${this.error.get()}</p>` : ''}
+      </div>
+    `;
+  }
+}
+ClockReader.register('clock-reader');

package/templates/gallery/modules/server-actions/queries/read-clock.server.ts

@@ -0,0 +1,38 @@
+'use server';
+// A GET server action. An action declares its HTTP semantics through reserved
+// sibling exports the framework reads statically, the same way a page declares
+// `export const revalidate`.
+//
+//   method     'GET' rides the args in the URL, is CSRF-exempt, and carries a weak
+//              ETag (a revalidation answers 304). It does NOT cache on its own: a
+//              GET with no `cache` export is `no-store`. With
+//              no `method` export an action is a POST mutation. (SSR seeding is
+//              NOT a GET feature: an action invoked during a fully buffered SSR
+//              render is seeded into the page whatever its verb. A streamed page
+//              emits no seed block at all.)
+//   cache      the max-age in seconds, and what makes the response cacheable at
+//              all. The number is shorthand for the object form, so
+//              { maxAge: 10, swr: 30 } adds a stale-while-revalidate grace
+//              window. PRIVATE by default. Only pass
+//              { public: true } for data identical for EVERY visitor, since a
+//              shared cache keys the entry on the URL and args alone. Same
+//              safety rule as a page's `export const revalidate`.
+//   tags       labels this cached entry so a mutation can evict it by name.
+//
+// One function per file is required once a file carries these config exports.
+import { serveReading } from '../utils/clock.server.ts';
+
+export const method = 'GET';
+export const cache = 10;
+export const tags = () => ['clock'];
+
+export async function readClock(): Promise<{ reading: number; serving: number; at: string }> {
+  // `at` goes over the wire as an ISO instant, not a formatted local time: the
+  // card sits it next to a browser-side timestamp, and a server in another
+  // timezone would otherwise put the two columns hours apart.
+  // `serving` counts the times this body actually ran, so a repeat call answered
+  // from the browser cache is visible: the number does not move. It is also why
+  // this particular read never answers a 304, since a per-execution counter gives
+  // every response a different ETag. A read whose result is stable does.
+  return { ...serveReading(), at: new Date().toISOString() };
+}

package/templates/gallery/modules/server-actions/utils/clock.server.ts

@@ -0,0 +1,27 @@
+// A server-only utility (no 'use server'), like format.server.ts next to it: the
+// tiny bit of state the cached GET read and the mutation that invalidates it
+// share. Not RPC-callable, so a browser import would throw at load. A real app
+// keeps this in the database.
+//
+// Two counters, because they show different things. `reading` is the domain
+// value the mutation changes. `servings` counts how many times the read actually
+// EXECUTED on the server, which is what makes a browser-cache hit visible: a
+// response served from cache does not run this function, so the number does not
+// move.
+//
+// Both are per-PROCESS and shared by every visitor, which is fine for a demo but
+// is exactly why a real app puts this in the database. On a deployed gallery
+// someone else's bump moves your reading, and your first read opens at whatever
+// serving number the process is on.
+let reading = 1;
+let servings = 0;
+
+export function serveReading(): { reading: number; serving: number } {
+  servings += 1;
+  return { reading, serving: servings };
+}
+
+export function bumpReading(): number {
+  reading += 1;
+  return reading;
+}

package/templates/gallery/modules/todo/queries/list-todos.server.ts

@@ -1,8 +1,10 @@
 'use server';
 // A READ is a `'use server'` action so the client (and SSR) can call it via the
 // normal import (rewritten to a typed RPC stub). `method = 'GET'` rides args in
-// the URL, is CSRF-exempt, and its result is SSR-seeded so the component does
-// not re-fetch on hydration.
+// the URL and is CSRF-exempt. It declares no `cache`, so the response is
+// `no-store`: the verb marks the read as safe, the `cache` export is what makes
+// it cacheable. The todo page awaits this server-side and hands the rows down as
+// a `.todos=${...}` property, so nothing re-fetches it on the client.
 import { db } from '#db/connection.server.ts';
 import type { Todo } from '../types.ts';
 

package/templates/public/sw.js

@@ -15,8 +15,17 @@
  *   - 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.
+ *     the FRAMEWORK-emitted URLs (modules, the core runtime, vendor bundles)
+ *     carry a ?v=<hash> content fingerprint automatically, so a changed file
+ *     gets a new URL and the cache cannot serve stale bytes for those.
+ *
+ *     A public/ asset is the exception: its URL is fingerprinted only when you
+ *     mark it with asset() (href=${asset('/public/app.css')}). An un-marked
+ *     public/ URL is stable across deploys, so this worker serves the CACHED
+ *     copy and revalidates behind it, and the first load after a deploy shows
+ *     the OLD bytes. The cache version below will not necessarily rescue you,
+ *     because the build id it derives from is a deploy fingerprint rather than
+ *     a per-file content hash. Mark any public/ asset whose bytes change.
  *
  * 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

package/templates/scripts/clear-gallery.mjs

@@ -163,7 +163,7 @@ export default function Home() {
         app from here. The guide is <code class="text-[0.9em]">.agents/skills/webjs/SKILL.md</code>.
       </p>
       <nav class="flex items-center gap-5 text-sm opacity-70">
-        <a href="https://docs.webjs.dev" target="_blank" rel="noopener" class="hover:opacity-100 transition-opacity no-underline">Docs</a>
+        <a href="https://webjs.dev/docs" target="_blank" rel="noopener" class="hover:opacity-100 transition-opacity no-underline">Docs</a>
         <a href="https://github.com/webjsdev/webjs" target="_blank" rel="noopener" class="hover:opacity-100 transition-opacity no-underline">GitHub</a>
       </nav>
     </div>
@@ -173,7 +173,7 @@ export default function Home() {
 }
 
 function MINIMAL_LAYOUT() {
-  return `import { html } from '@webjsdev/core';
+  return `import { html, asset } from '@webjsdev/core';
 
 /**
  * Root layout: the ONLY file that writes the document shell. It links the
@@ -194,7 +194,11 @@ export const metadata = { icons: '/public/favicon.svg' };
 export default function RootLayout({ children }: { children: unknown }) {
   return html\`
     <meta name="color-scheme" content="light dark">
-    <link rel="stylesheet" href="/public/tailwind.css">
+    <!-- asset() content-hashes the url in production, so a deploy that changes
+         the CSS changes the url and the framework serves it immutable for a
+         year. Without it this stable url can serve the PREVIOUS stylesheet
+         from a CDN or a service-worker cache after a deploy. -->
+    <link rel="stylesheet" href=\${asset('/public/tailwind.css')}>
     <style>
       html, body { margin: 0; }
       body {