@webjsdev/cli 0.10.40 → 0.10.41

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

@@ -0,0 +1,226 @@
+---
+name: webjs
+description: Build and review WebJs applications. Use when working on WebJs app structure, pages, layouts, routes, server actions, components, signals, data and validation, auth, sessions, styling, the client router, streaming, or tests. WebJs is AI-first, web-components-first, and has no build step.
+---
+
+# Build a WebJs App
+
+Use this skill for end-to-end WebJs app work. It helps you choose the right layer first, reach for the right export, and avoid the WebJs-specific mistakes that Next.js or Lit muscle memory causes. WebJs is its own framework: the component API matches Lit and the routing feels like Next, but the execution model is neither.
+
+## 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.
+
+## What WebJs Is
+
+WebJs is an AI-first, web-components-first framework with **no build step**: source files are served as native ES modules, and TypeScript is stripped in place (Node 24+ or Bun). It runs SSR + progressive enhancement by default.
+
+**There is no server/client component split.** No RSC render tree, no Flight protocol, no `"use client"` boundary. Instead:
+
+- **Pages and layouts** (`app/**/page.ts`, `app/**/layout.ts`) run **only on the server** to produce HTML. They do NOT hydrate, so their own markup cannot be interactive (an `@click` in a page template is dropped at SSR). They still LOAD in the browser so imported components register.
+- **Components** (`WebComponent` custom elements) hydrate per element, islands-style. **All interactivity lives here**: `@event`, reactive property assignment, signal mutation.
+- **`*.server.ts`** is the one server boundary. With `'use server'` its exports are RPC-callable from the client (the import is rewritten to a stub); without it the file is a server-only utility whose browser import throws at load. This, not a component annotation, is how a dependency (the DB driver, secrets, `node:*`) is kept off the client.
+- **`route.ts`** is a server-only HTTP handler (named `GET`/`POST` exports), the one routing file that is NOT isomorphic.
+
+**Progressive enhancement is the default architecture.** With JS off, content reads, `<a>` navigates, and `<form>` server actions submit. JS is opt-in per interactive behaviour. Never write a first paint that depends on hydration.
+
+## When To Use This Skill
+
+- New features or refactors touching pages, routes, actions, components, data, auth, sessions, styling, or tests
+- Reviewing WebJs code for correctness or framework usage
+- Answering "how should this be structured in WebJs?"
+- Finding the right export, reference doc, or default pattern for a task
+
+## Load Only The References You Need
+
+Classify the task first, then load the smallest useful reference set. Each reference starts with a "What This Covers" section; read that to confirm relevance before reading the rest. Loading more than two or three at once usually means the task is not narrowed yet.
+
+| Task involves...                                                            | Start with                                    |
+| --------------------------------------------------------------------------- | --------------------------------------------- |
+| Pages, layouts, dynamic routes, route handlers, metadata, redirects, 404s   | `references/routing-and-pages.md`             |
+| Writing components: reactive props, signals, lifecycle, light vs shadow DOM  | `references/components.md`                     |
+| Server actions, mutations, queries, validation, the `ActionResult` envelope | `references/data-and-actions.md`              |
+| Sessions, login flows, route protection, `forbidden()` / `unauthorized()`   | `references/auth-and-sessions.md`             |
+| Tailwind, light-DOM tag-prefix rule, tokens, fixed headers, no-reflow layout | `references/styling.md`                        |
+| Client router, prefetch, frames, view transitions, Suspense streaming        | `references/client-router-and-streaming.md`   |
+| Optimistic UI for a user-facing mutation                                     | `references/optimistic-ui.md`                 |
+| TypeScript at runtime, erasable syntax, full-stack types                     | `references/typescript.md`                     |
+| Unit, browser, e2e tests, the `handle()` harness, Bun parity                 | `references/testing.md`                        |
+| Auth, caching, env vars, rate limit, file storage, the `webjs` config block  | `references/built-ins.md`                      |
+| Node vs Bun, running the app, deploying, runtime-specific differences        | `references/runtime.md`                        |
+| Offline support, an asset cache, the opt-in service worker                   | `references/service-worker.md`                 |
+| A pattern that feels like Next.js or Lit but might not transfer              | `references/muscle-memory-gotchas.md`         |
+
+Common bundles:
+
+- **Form or CRUD feature** then routing-and-pages, data-and-actions, testing; add auth if user-specific
+- **Interactive widget** then components, styling; add client-router-and-streaming only if it streams
+- **Protected area** then auth-and-sessions, routing-and-pages, testing
+- **Instant-feeling mutation** then data-and-actions, optimistic-ui
+
+## Default Workflow
+
+1. **Classify the change.** Route contract, data model, server mutation, auth, or only UI?
+2. **Start from the server.** Add the page/route and its server action or query before wiring interactive UI. A page render or a `<form>` POST should already return correct HTML before any component hydrates.
+3. **Put code in the narrowest owner.** Route-local first (`modules/<feature>/`), promote to `lib/` or `components/` only when reuse is real.
+4. **Keep server-only code behind `.server.ts`.** The DB driver, secrets, and `node:*` never belong in a page, layout, or component.
+5. **Add interactivity per behaviour.** Reach for a component (and a signal or `@event`) only where the UI is genuinely interactive. A display-only component is elided from the browser.
+6. **Validate input at the boundary.** Declare `export const validate` on an action; the RPC and `route()` boundaries run it.
+7. **Default mutations to optimistic UI** where the client can predict the result (`optimistic()` from `@webjsdev/core`).
+8. **Test the narrowest meaningful layer**, and render the app in a real browser for any UI change (static checks do not catch a collapsed layout).
+
+## Project Layout
+
+```
+app/                  ROUTING ONLY (thin adapters importing from modules/)
+  layout.ts           root layout (the ONLY file that may write <html>/<head>/<body>)
+  page.ts             /
+  <segment>/page.ts   /<segment>
+  [param]/page.ts     dynamic route (params.param)
+  <path>/route.ts     HTTP handler at /<path>
+  error.ts loading.ts not-found.ts forbidden.ts unauthorized.ts   boundaries (nearest wins)
+middleware.ts         root middleware
+modules/<feature>/    actions/ (mutations, *.server.ts), queries/ (reads, *.server.ts),
+                      components/, utils/ (pure), types.ts
+lib/                  lib/*.server.ts server-only infra, lib/utils/ browser-safe helpers
+components/*.ts        shared presentational custom elements (one per file)
+db/*.server.ts        Drizzle: schema, connection
+public/*              static assets, served at /public/<name>
+```
+
+App-internal imports use the `#` root alias (`import { db } from '#db/connection.server.ts'`), Node's native `package.json` imports field, not deep `../../../` relatives. A same-directory import stays relative.
+
+## Core WebJs Rules (invariants)
+
+1. Server-only code lives in `.server.ts`, `route.ts`, or `middleware.ts`. Never in a page, layout, or component (it crashes the browser at module load).
+2. `'use server'` exports are `async` functions returning serializer-safe values. Files without `'use server'` are server-only utilities.
+3. Custom element tag names contain a hyphen. Pass the tag to `Class.register('tag-name')`.
+4. Event (`@`), property (`.`), and boolean (`?`) holes in `html` are UNQUOTED: `@click=${fn}`, never `@click="${fn}"`.
+5. Signals are the default state primitive. Import `signal` / `computed` from `@webjsdev/core`, read via `signal.get()` inside `render()`. The base-class factory `WebComponent({ ... })` is only for values riding an HTML attribute or arriving via SSR hydration.
+6. Page and layout default exports are functions returning a value; they never call `render()` themselves.
+7. Light-DOM components with custom CSS prefix every class selector with their tag name. Prefer Tailwind (unique by construction).
+8. Only the root layout may write `<!doctype>` / `<html>` / `<head>` / `<body>`.
+9. No backtick characters inside an `html\`...\`` body, even in comments (it closes the literal and 500s).
+10. TypeScript must be erasable (`erasableSyntaxOnly: true`): no `enum`, no value `namespace`, no constructor parameter properties, no legacy decorators.
+11. Reactive properties are declared ONLY through the base-class factory `extends WebComponent({ count: Number })`. Never a `static properties` block, never a class-field initializer (it clobbers the reactive accessor).
+
+## Export Map
+
+Find the right export fast. Load the linked reference for full examples.
+
+### `@webjsdev/core` (browser + isomorphic)
+
+- `html` / `css` tagged templates. `WebComponent({ ... })` base-class factory; `prop(type?, opts?)` declares one reactive property. `register(tag, C)` / `Class.register('tag')`.
+- `signal` / `computed` reactive state; `render(v, el)` client render.
+- `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`.
+- 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`. `Task` lives at `@webjsdev/core/task`, context at `/context`.
+
+### `@webjsdev/server` (server side)
+
+- `createRequestHandler`, `cors()`, `route(action, opts?)` REST adapter, `sitemap()` / `sitemapIndex()`, `actionContext()`, `actionSignal()`, `requestId()`, `cache()` / `revalidateTag`.
+- Data layer is Drizzle in `db/*.server.ts`. Auth, sessions, caching, rate limit, file storage are built in and pluggable (`references/built-ins.md`).
+
+### File conventions
+
+`page.ts` (server-only fn), `layout.ts` (embeds `children`), `route.ts` (HTTP handler), `middleware.ts`, `*.server.ts` (server boundary), `error.ts` / `loading.ts` / `not-found.ts` / `forbidden.ts` / `unauthorized.ts` (boundaries), metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `opengraph-image.ts`).
+
+## Canonical Patterns
+
+### A page
+
+```ts
+// app/about/page.ts
+import { html } from '@webjsdev/core';
+export default function About() {
+  return html`<h1>About</h1>`;
+}
+```
+
+### A dynamic route reading data through an action
+
+```ts
+// app/users/[id]/page.ts
+import { html } from '@webjsdev/core';
+import { getUser } from '#modules/users/queries/get-user.server.ts';
+export default async function User({ params }: { params: { id: string } }) {
+  const user = await getUser(params.id); // never import the DB directly into a page
+  return html`<h1>${user.name}</h1>`;
+}
+```
+
+### A server action
+
+```ts
+// modules/users/actions/update-profile.server.ts
+'use server';
+import { eq } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { users } from '#db/schema.server.ts';
+export async function updateProfile(input: { id: string; name: string }) {
+  const name = String(input?.name || '').trim();
+  if (!name) return { success: false, error: 'name required', status: 400 };
+  const [row] = await db.update(users).set({ name }).where(eq(users.id, input.id)).returning();
+  return { success: true, data: row };
+}
+```
+
+Call it from a component via a normal import (rewritten to a typed RPC stub). Never hand-write `fetch()`.
+
+### An interactive component
+
+```ts
+// components/counter.ts
+import { WebComponent, prop, html } from '@webjsdev/core';
+class Counter extends WebComponent({ count: prop(Number) }) {
+  constructor() { super(); this.count = 0; }
+  render() {
+    return html`<button @click=${() => this.count++}>${this.count}</button>`;
+  }
+}
+Counter.register('my-counter');
+```
+
+### The no-JS write path (a page action)
+
+```ts
+// app/contact/page.ts
+export const action = async ({ formData }) => {
+  const email = String(formData.get('email') || '');
+  if (!email) return { success: false, fieldErrors: { email: 'required' } };
+  return { success: true, redirect: '/thanks' };
+};
+export default function Contact({ actionData }) { /* render form + actionData errors */ }
+```
+
+Success is a 303 (PRG); failure re-renders the page at 422 with the result on `actionData`. With JS the client router applies the response in place.
+
+## Security And Session Defaults
+
+- Never ship demo secrets. Require session and provider secrets from the environment and fail fast if missing.
+- Action RPC CSRF is an Origin / `Sec-Fetch-Site` check, not a token cookie. A safe GET action is CSRF-exempt. A `route.ts` REST endpoint is NOT covered: authenticate every mutating endpoint, validate, rate-limit.
+- Prod action errors are sanitized to a generic message plus a digest. Put a user-facing message on the `ActionResult` `{ success: false, error }` envelope, never on a raw throw.
+- Use `forbidden()` for an authenticated user lacking permission, `unauthorized()` for an unauthenticated request. Inside a `'use server'` RPC action, return an `ActionResult` for an auth failure instead of throwing.
+- For CORS use `cors()` from `@webjsdev/server`; `credentials: true` REQUIRES an explicit origin allowlist, never `'*'`.
+
+## Testing Defaults
+
+- Prefer server/handler tests first: drive the app with `handle()` from `@webjsdev/server/testing` and assert on the `Response`.
+- Add a browser test (`webjs test --browser`) for anything touching hydration, the client router, slots, or custom-element upgrade. A unit test is necessary but NOT sufficient for a browser-facing change.
+- Render the app and LOOK for any UI change: `webjs check` and `webjs typecheck` pass even when a layout collapses. Static tools give no signal for a visual defect.
+- WebJs runs on Node 24+ AND Bun. Prove a runtime-sensitive change (serializer, listener, streams, `node:crypto`, the TS stripper) on both.
+
+## Common Mistakes To Avoid
+
+- Treating a page or layout like a React component and expecting its markup to hydrate. It runs server-only; put interactivity in a component.
+- Importing a `.server.ts` utility (no `'use server'`) directly into a shipping component. Its browser stub throws at load; reach it through a `'use server'` action.
+- Using a `static properties` block or a class-field initializer for reactive props instead of the `WebComponent({ ... })` factory.
+- Quoting an event / property / boolean hole (`@click="${fn}"`).
+- Writing `fetch()` to call your own server instead of importing the action.
+- Throwing `redirect()` / `notFound()` inside a `route.ts` handler (uncaught 500). Return a `Response` there.
+- A placeholder first paint that fetches in `connectedCallback`. SSR does not call `connectedCallback`; put first-paint data in the constructor (server-known inputs) or use `async render()`.
+- A browser global (`window`, `document`, `localStorage`) in the constructor or `render()`. It throws at SSR; do browser-only work in `connectedCallback`.
+- Interpolating into a component's `<style>` / `<script>` body. Use `static styles` or Tailwind.

package/templates/.agents/skills/webjs/references/auth-and-sessions.md

@@ -0,0 +1,220 @@
+# Auth and Sessions
+
+## What This Covers
+
+- Sessions: cookie by default, Redis-backed when configured, the `SESSION_SECRET` requirement
+- Authentication: `createAuth` (NextAuth-style), Credentials plus OAuth providers, `auth()` in a page or action
+- Login and logout flows (`signIn` / `signOut` / `handlers`)
+- Protecting a route: gate at the top of a page or action, redirect when unauthenticated
+- `forbidden()` (403) vs `unauthorized()` (401) and their nearest-wins boundary files
+- Returning an `ActionResult` for an auth failure inside a `'use server'` action (do NOT throw there)
+- The Origin / `Sec-Fetch-Site` CSRF model (not a token cookie)
+- Requiring secrets from the environment and failing fast
+- `cors()` with an explicit allowlist when `credentials: true`
+
+Read this when a task touches login, logout, who-can-see-a-page, session
+state, or the CSRF / CORS posture of a mutation. Sibling refs:
+`data-and-actions.md` (the `ActionResult` envelope, validation, the RPC
+boundary), `routing-and-pages.md` (the `forbidden.ts` / `unauthorized.ts`
+boundary files and control-flow throws), `built-ins.md` (env vars, Redis
+scaling, the full caching surface).
+
+## Sessions
+
+Enable sessions in middleware, read and write them in a page or action.
+
+```ts
+// middleware.ts: enable on all routes
+import { session } from '@webjsdev/server';
+export default session();   // auto: REDIS_URL present -> server-side, else -> cookie
+
+// in a page or action
+import { getSession } from '@webjsdev/server';
+const s = getSession(req);
+s.userId = user.id;         // auto-saved after the response
+```
+
+Cookie sessions (the default) are signed and encrypted with no server
+state. Store sessions (with Redis) keep the session id in the cookie and
+the data in Redis. Both require `SESSION_SECRET`, read from the
+environment (never a literal in source) so boot fails if it is missing.
+
+## Authentication (`createAuth`)
+
+Configure providers once in a `.server.ts` file. `createAuth` returns
+`auth` (read the session), `signIn` / `signOut` (the flows), and
+`handlers` (the OAuth redirect endpoints).
+
+```ts
+// lib/auth.server.ts
+import { createAuth, Credentials, Google, GitHub } from '@webjsdev/server';
+import { db } from '#db/connection.server.ts';
+
+export const { auth, signIn, signOut, handlers } = createAuth({
+  providers: [
+    Credentials({
+      async authorize(credentials) {
+        const user = await db.query.users.findFirst({ where: { email: credentials.email } });
+        if (!user || !verifyPassword(credentials.password, user.passwordHash)) return null;
+        return { id: user.id, name: user.name, email: user.email, role: user.role };
+      },
+    }),
+    Google(),   // reads AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET
+    GitHub(),   // reads AUTH_GITHUB_ID, AUTH_GITHUB_SECRET
+  ],
+  secret: process.env.AUTH_SECRET,   // required, 32+ random chars, from the env
+});
+```
+
+Sessions are JWT by default (stateless, scales horizontally). OAuth
+providers handle the full redirect flow. Read the session anywhere on the
+server with `auth()`.
+
+```ts
+// in a page or action
+import { redirect } from '@webjsdev/core';
+const session = await auth();
+if (!session) throw redirect('/login');   // page-render gate: 302
+```
+
+`auth()` resolves `{ user }`, where `user` is `Record<string, unknown>` by
+default. To read custom fields (`session.user.id`, `session.user.role`)
+without a cast, type the session by augmenting the `AuthUser` interface
+(types-only, opt-in). See `typescript.md`.
+
+## Required secrets, fail fast
+
+| Variable | Effect |
+|---|---|
+| `AUTH_SECRET` | Required for auth JWT signing (32+ random chars) |
+| `AUTH_GOOGLE_ID` / `AUTH_GOOGLE_SECRET` | Google OAuth (optional) |
+| `AUTH_GITHUB_ID` / `AUTH_GITHUB_SECRET` | GitHub OAuth (optional) |
+| `SESSION_SECRET` | Cookie session signing |
+| `REDIS_URL` | When set, sessions and rate limit and cache use Redis |
+
+Never ship a demo secret or an in-source default. Read each secret from
+`process.env` and fail boot when a required one is absent (use the
+optional `env.ts` schema file to validate at boot and name every bad var).
+A guessable signing secret means forgeable sessions.
+
+## Protecting a route
+
+Gate at the top of the page or layout that owns the protected subtree.
+Because a page runs only on the server, the check happens before any HTML
+is produced, so a logged-out visitor never receives protected markup.
+
+```ts
+// app/dashboard/page.ts
+import { html, redirect } from '@webjsdev/core';
+import { auth } from '#lib/auth.server.ts';
+
+export default async function Dashboard() {
+  const session = await auth();
+  if (!session) throw redirect('/login');   // not signed in
+  return html`<h1>Welcome, ${session.user.name}</h1>`;
+}
+```
+
+Reading the session through `auth()` also auto-excludes the page from the
+server HTML response cache, so a per-user page is never cached and served
+to another visitor (see `built-ins.md`).
+
+## `forbidden()` (403) vs `unauthorized()` (401)
+
+Two control-flow throws from `@webjsdev/core`, mirroring the `notFound()`
+model. Both render the NEAREST matching boundary (innermost wins), else a
+default page.
+
+- `unauthorized()` for a request that is NOT authenticated (no valid
+  session). Renders the nearest `unauthorized.ts`. Use it when the fix is
+  "log in".
+- `forbidden()` for an authenticated user who LACKS permission for this
+  resource. Renders the nearest `forbidden.ts`. Use it when logging in as
+  a different account would not help.
+
+```ts
+// app/admin/page.ts
+import { html, forbidden, unauthorized } from '@webjsdev/core';
+import { auth } from '#lib/auth.server.ts';
+
+export default async function Admin() {
+  const session = await auth();
+  if (!session) throw unauthorized();          // 401, renders unauthorized.ts
+  if (session.user.role !== 'admin') throw forbidden();  // 403, renders forbidden.ts
+  return html`<h1>Admin</h1>`;
+}
+```
+
+Both work from a page or layout render AND from a page `action` (the no-JS
+write path). The boundary files (`app/forbidden.ts`, `app/unauthorized.ts`,
+or nested variants) live alongside the routes they cover and each
+default-export a function returning the boundary markup.
+
+`forbidden()` / `unauthorized()` are for a page / layout render or a page
+`action`. They are NOT for a `route.ts` handler (return a `Response` with
+the status there), and NOT for a `'use server'` RPC action (a raw throw
+becomes a generic 500). See the next section for the action case.
+
+## Auth failure inside a `'use server'` action: return, do not throw
+
+A `'use server'` RPC action must NOT throw `forbidden()` / `unauthorized()`
+/ `redirect()` for an auth failure. A raw throw there is sanitized to a
+generic 500 in production, so the caller loses the reason. Instead return
+an `ActionResult` failure envelope with a status the client can act on.
+
+```ts
+// modules/posts/actions/delete-post.server.ts
+'use server';
+import { auth } from '#lib/auth.server.ts';
+import { db } from '#db/connection.server.ts';
+
+export async function deletePost(input: { id: string }) {
+  const session = await auth();
+  if (!session) return { success: false, error: 'Sign in to continue.', status: 401 };
+  const post = await db.query.posts.findFirst({ where: { id: input.id } });
+  if (post?.authorId !== session.user.id) {
+    return { success: false, error: 'Not your post.', status: 403 };
+  }
+  await db.delete(posts).where(eq(posts.id, input.id));
+  return { success: true };
+}
+```
+
+The user-facing message belongs on the envelope's `error` field, never on
+a raw throw (prod strips a thrown message to a digest). See
+`data-and-actions.md` for the full `ActionResult` shape.
+
+## CSRF: an Origin / `Sec-Fetch-Site` check, not a token cookie
+
+Action RPC CSRF protection is an Origin / `Sec-Fetch-Site` header check
+(the Remix 3 / Go 1.25 model), NOT a token cookie. A state-changing verb
+(POST / PUT / PATCH / DELETE) passes only when:
+
+- `Sec-Fetch-Site` is `same-origin` or `none`, OR
+- (older browsers with no `Sec-Fetch-Site`) the `Origin` host matches the
+  request host, OR
+- the source is listed in `webjs.allowedOrigins`.
+
+Otherwise the request is a 403. A safe GET action is CSRF-exempt. Because
+there is no CSRF token cookie and no `Set-Cookie` rides the SSR HTML, a
+page that opts into a public `Cache-Control` stays CDN-edge-cacheable.
+
+A `route.ts` REST endpoint is NOT covered. Authenticate every mutating
+endpoint yourself, run `export const validate`, log without secrets, and
+rate-limit.
+
+## CORS: explicit allowlist when `credentials: true`
+
+For cross-origin requests use `cors()` from `@webjsdev/server` as
+middleware. When `credentials: true` you MUST pass an explicit origin
+allowlist. Never `'*'` with credentials (that would expose an
+authenticated response to any origin).
+
+```ts
+// middleware.ts
+import { cors } from '@webjsdev/server';
+export default cors({
+  origin: ['https://app.example.com', 'https://admin.example.com'],
+  credentials: true,   // requires the explicit allowlist above
+});
+```

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

@@ -0,0 +1,200 @@
+# Built-ins and Configuration
+
+Env vars, caching, rate limiting, broadcast, file storage, and the `package.json` `"webjs"` config block plus observability. Everything here is imported from `@webjsdev/server`.
+
+## What This Covers
+
+- **Environment variables** and the `WEBJS_PUBLIC_` browser-exposed prefix.
+- **Caching primitives.** `cache()` with tag invalidation, HTTP `Cache-Control`, the server HTML response cache (`export const revalidate`), content-hash asset URLs, conditional GET (ETag).
+- **Rate limiting** (`rateLimit()` middleware) and **broadcast** (`broadcast()` over WebSockets).
+- **File storage.** `FileStore` / `diskStore`, safe keys, signed URLs.
+- **The `"webjs"` config block.** Security headers, CSP, redirects, trailing-slash, basePath, allowed origins, client-router opt-out, ingress caps, dev/start task orchestration.
+- **Observability.** Access log, `requestId()`, the `onError` hook, `instrumentation.ts`, the build-info endpoint.
+
+Read this when wiring caching or rate limiting, storing uploads, hardening headers, or configuring redirects and observability. **Auth and sessions are a separate reference (`auth-and-sessions.md`).** Server actions, `revalidateTag` from a mutation, and the `ActionResult` envelope live in `data-and-actions.md`.
+
+## Environment variables
+
+`process.env.X` reads are **server-only**. `NODE_ENV` is defined both sides. A variable named with the `WEBJS_PUBLIC_` prefix is exposed to the browser via an inline `<script>` (no build step), so read it client-side as `process.env.WEBJS_PUBLIC_ANALYTICS_ID`.
+
+| Variable | Effect |
+|---|---|
+| `REDIS_URL` | When set, sessions, rate limit, and cache use Redis instead of memory |
+| `SESSION_SECRET` / `AUTH_SECRET` | Session and auth signing (see `auth-and-sessions.md`) |
+| `PORT` | Listen port. Precedence `--port` flag, then `PORT` (real env or `.env`), then `8080` |
+
+Defaults are single-instance memory stores. To scale horizontally, switch the store once at startup: `setStore(redisStore({ url: process.env.REDIS_URL }))`.
+
+## Caching
+
+### `cache()` for query and computation results
+
+Wrap an async function so identical calls serve from the store until the TTL expires. Cached values and keys round-trip through the rich serializer, so a `Date` stays a `Date` on a warm hit.
+
+```ts
+// modules/posts/queries/list-posts.server.ts
+'use server';
+import { cache } from '@webjsdev/server';
+import { db } from '#db/connection.server.ts';
+
+export const postById = cache(
+  async (id: string) => db.query.posts.findFirst({ where: { id } }),
+  { key: 'post', ttl: 300, tags: (id) => ['post:' + id] } // per-entity tag
+);
+export const listPosts = cache(
+  async () => db.query.posts.findMany(),
+  { key: 'posts', ttl: 60, tags: ['posts'] } // static tag
+);
+```
+
+A mutation invalidates a tagged read from an unrelated module with `revalidateTag('post:' + id)` (evicts only that entry) or `revalidateTags([...])`. See `data-and-actions.md` for the mutation side. An untagged `cache()` is untouched by any `revalidateTag`.
+
+### HTTP `Cache-Control`
+
+Standard HTTP caching. Let browsers, CDNs, and proxies do the work. Set it on a `route.ts` `Response` or via page `metadata.cacheControl`.
+
+```ts
+export const metadata = { cacheControl: 'public, max-age=60' };
+```
+
+### Server HTML response cache (`export const revalidate`)
+
+For a page that renders the **same HTML for every visitor**, opt into caching the SSR output (WebJs's no-build equivalent of ISR). Keyed by full URL only.
+
+```ts
+// app/blog/page.ts
+export const revalidate = 60;   // cache this page's HTML for 60s
+```
+
+**Safety.** This asserts the page is identical for everyone for N seconds. Never set it on a page that reads `cookies()`, a session, or per-user data. The framework auto-marks a request dynamic and refuses to cache when the render reads per-user state through a framework helper (`cookies()`, `headers()`, `getSession()`, `auth()`), so an `auth()`-gated page fails safe. It also never caches a non-200, a streamed Suspense body, a `Set-Cookie` response, or a page under CSP. Evict on a write with `revalidatePath('/blog')`; `revalidateAll()` clears everything (single-instance / dev). This differs from the client-side `revalidate()` in `@webjsdev/core`, which evicts the browser snapshot cache.
+
+### 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).
+
+## Rate limiting
+
+`rateLimit()` is middleware backed by the pluggable cache store (memory by default, Redis when the global store is switched). Fixed-window.
+
+```ts
+// middleware.ts (or a per-segment middleware.ts)
+import { rateLimit } from '@webjsdev/server';
+export default rateLimit({ window: '1m', max: 60 });
+```
+
+Options: `window` (ms or a string like `'1m'`), `max`, `key` (a string prefix or a `(req) => string` function, defaults to the client IP), `message`, `store`, `trustProxy`. Over-limit responds `429` with `Retry-After` and `X-RateLimit-*` headers; an allowed response carries the remaining-quota headers too. For multi-instance scaling, set the global store to Redis once at startup.
+
+## Broadcast
+
+Send data to every WebSocket client connected to a route path, from inside that route's `WS` handler.
+
+```ts
+// app/api/chat/route.ts
+import { broadcast } from '@webjsdev/server';
+export function WS(ws, req) {
+  ws.on('message', (data) => broadcast('/api/chat', data, { except: ws }));
+}
+```
+
+`broadcast(path, data, opts?)` fans out to all clients on `path`; `opts.except` skips one socket (typically the sender). `clientCount(path)` returns the live count. Single-instance by default; wire Redis pub/sub yourself for multi-instance.
+
+## File storage
+
+WebJs round-trips a native `File` / `Blob` / `FormData` over the wire; the file-storage primitive decides where the bytes land. Same adapter pattern as cache and sessions: a `FileStore` interface, a default `diskStore`, and a `setFileStore` / `getFileStore` singleton so swapping the backend touches no call site.
+
+```ts
+import { getFileStore, setFileStore, diskStore, generateKey, signedUrl, verifySignedUrl } from '@webjsdev/server';
+// Default: <cwd>/.webjs/uploads served under /uploads. Override at startup:
+setFileStore(diskStore({ dir: '/var/data/uploads', baseUrl: '/files' }));
+```
+
+`FileStore` methods (all web-standard, so an S3 / R2 adapter is a drop-in): `put(key, file, opts?)` streams to storage, `get(key)` returns a streaming handle (`{ body, size, contentType }`) or `null`, `delete(key)` (idempotent), `url(key)`, `has(key)`.
+
+**Never trust a user filename as a key.** `generateKey(file.name)` returns an opaque `<uuid>.<ext>` with a sanitized extension; a traversal attempt yields a bare safe key. Keys are containment-checked before any filesystem op.
+
+**Signed URLs** gate serving without a session lookup. `signedUrl(key, { secret, expiresIn })` mints an expiring HMAC signature; `verifySignedUrl(searchParams, secret)` returns `{ valid }`. An `expiresIn` of `0` or negative fails closed.
+
+**Serving-XSS warning.** The recorded content-type is attacker-controlled (the browser sent it at upload). A serving route MUST send `X-Content-Type-Options: nosniff` and SHOULD send `Content-Disposition: attachment` for user uploads. Only serve inline after validating bytes against a strict inert allowlist, never `text/html` / `image/svg+xml`. Add the uploads directory to `.gitignore`.
+
+## The `"webjs"` config block (package.json)
+
+All keys are optional; a malformed entry is dropped at boot with a warning, never crashing the pipeline.
+
+### Security headers
+
+On by default (`X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`, `Referrer-Policy`, `Permissions-Policy`, plus HSTS in prod over HTTPS). A default is set only when absent. Override per path:
+
+```jsonc
+{ "webjs": { "headers": [
+  { "source": "/embed/:path*", "headers": [{ "key": "X-Frame-Options", "value": null }] }
+] } }
+```
+
+`source` uses the native URLPattern syntax (`:param`, `:rest*`). A `value` of `null` disables a default. Precedence lowest to highest: secure defaults, then `webjs.headers`, then app middleware.
+
+### CSP (opt-in, nonce)
+
+Off by default. `{ "webjs": { "csp": true } }` enables a strict-dynamic + per-request nonce posture. An object form merges `directives` and supports `reportOnly`. Read the nonce with `cspNonce()` from `@webjsdev/core` to stamp your own inline `<script>`.
+
+### Redirects, trailing-slash, basePath, allowed origins
+
+```jsonc
+{ "webjs": {
+  "redirects": [{ "source": "/blog/:slug", "destination": "/posts/:slug" }],
+  "trailingSlash": "never",
+  "basePath": "/app",
+  "allowedOrigins": ["admin.example.com"],
+  "clientRouter": true
+} }
+```
+
+- **`redirects`** run first in the pipeline. `permanent` defaults to `true` (308); set `statusCode` for a legacy code. The query string is preserved. No server-side loop guard, so keep a `destination` off another rule's `source`.
+- **`trailingSlash`** picks a canonical form and 308-redirects the other. `"never"` (recommended), `"always"`, `"ignore"` (default). The root `/` is always exempt.
+- **`basePath`** prefixes every framework-emitted URL for a sub-path mount and strips the prefix at ingress. Author-written `<a href>` links are NOT auto-prefixed. Empty default is a byte-identical no-op.
+- **`allowedOrigins`** is the action-RPC CSRF allowlist (CSRF is an Origin / `Sec-Fetch-Site` check, not a token cookie). Default same-origin only. This is not CORS; use the `cors()` middleware for cross-origin `route.ts` reads.
+- **`clientRouter: false`** opts the whole app out of SPA navigation (pure MPA) while components still hydrate. Per-page escape hatch: `disableClientRouter()`.
+
+### Ingress caps
+
+Inbound bodies and connection lifetimes are capped by default. Override in the block or via env; precedence is env, then package.json, then default. A value of `0` disables a cap.
+
+| Cap | Default | Config key |
+|---|---|---|
+| JSON / RPC body | 1 MiB | `maxBodyBytes` |
+| Form / multipart body | 10 MiB | `maxMultipartBytes` |
+| Full request receive | 30s | `requestTimeoutMs` |
+| Headers receive | 20s | `headersTimeoutMs` |
+| Keep-alive idle | 5s | `keepAliveTimeoutMs` |
+
+An over-limit body responds `413` without buffering the whole payload.
+
+### Dev/start task orchestration
+
+`webjs dev` and `webjs start` run per-environment tasks from the block, so the primitive matches `npm run dev` / `npm start`.
+
+```jsonc
+{ "webjs": {
+  "dev":   { "before": ["webjs db migrate"], "parallel": ["tailwindcss ... --watch"], "watch": ["../blog"] },
+  "start": { "before": ["webjs db migrate"] }
+} }
+```
+
+`before` runs to completion first (a non-zero exit aborts the boot). `parallel` (dev only) runs long-lived watchers alongside the server and tears them down on exit. `watch` (dev only) adds extra live-reload directories outside the app tree.
+
+## Observability
+
+Wired at the single response funnel, covering pages, routes, actions, and assets uniformly.
+
+- **Access log.** One structured `info` line per handled request (`method`, `path`, `status`, `durationMs`, `requestId`). Never logs bodies or secrets; framework `/__webjs/*` traffic is suppressed.
+- **Request id.** Each request gets a `crypto.randomUUID()` correlation id, set as `X-Request-Id` (honoring a trusted inbound one) and readable server-side with `requestId()` from `@webjsdev/server` (returns `null` outside a request scope).
+- **`onError` hook.** Register via `createRequestHandler({ onError })` or `startServer({ onError })`. Called with `(error, { request, requestId, phase })` on any caught pipeline error, before the sanitized response is sent. Best-effort (a throwing hook is ignored), purely additive (the sanitized 500 / action digest is unchanged). Point it at Sentry or an APM.
+
+```ts
+const app = await createRequestHandler({
+  appDir: process.cwd(),
+  onError(error, { requestId, phase }) { Sentry.captureException(error, { tags: { requestId, phase } }); },
+});
+```
+
+- **`instrumentation.ts`** (app root) default-exports or names a `register()` function run once at boot, before the route table builds. Inside it, `setOnError(fn)` composes with the handler option. A sibling `instrumentation-client.ts` runs first in the client boot script for browser-side init.
+- **Build info.** `GET /__webjs/version` returns `{ version, build, node, uptime }` (`Cache-Control: no-store`), alongside the `/__webjs/health` and `/__webjs/ready` probes, so a deploy can confirm which build is live.