@webjsdev/cli 0.10.45 → 0.10.47

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

@@ -4,7 +4,7 @@ Env vars, caching, rate limiting, broadcast, file storage, and the `package.json
 
 ## What This Covers
 
-- **Environment variables** and the `WEBJS_PUBLIC_` browser-exposed prefix.
+- **Environment variables**, the `WEBJS_PUBLIC_` browser-exposed prefix, and `env.ts` boot validation.
 - **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.
@@ -25,6 +25,18 @@ Read this when wiring caching or rate limiting, storing uploads, hardening heade
 
 Defaults are single-instance memory stores. To scale horizontally, switch the store once at startup: `setStore(redisStore({ url: process.env.REDIS_URL }))`.
 
+**Validate required vars at boot with an app-root `env.ts`** (optional). It default-exports either a SCHEMA object (each var mapped to a type `string` / `number` / `boolean` / `url` / `enum`, or an options object with `optional` / `default` / `minLength` / `pattern` / `values`) OR a validator function `(env) => void` that throws. It runs at boot after `.env` loads, coerces values and writes defaults back to `process.env`, and fails fast naming EVERY bad var:
+
+```ts
+// env.ts
+export default {
+  DATABASE_URL: 'url',
+  SESSION_SECRET: { type: 'string', minLength: 16 },
+  PORT: { type: 'number', default: 8080 },
+  LOG_LEVEL: { type: 'enum', values: ['debug', 'info', 'warn'], default: 'info' },
+};
+```
+
 ## Caching
 
 ### `cache()` for query and computation results
@@ -112,7 +124,7 @@ setFileStore(diskStore({ dir: '/var/data/uploads', baseUrl: '/files' }));
 
 **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.
+**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. Pass `base` to point the signed link at your own serve route instead of the default upload URL: `signedUrl(key, { secret, base: '/files/' + key, expiresIn: 3600 })`.
 
 **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`.
 
@@ -136,6 +148,8 @@ On by default (`X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`,
 
 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>`.
 
+Enforcement is the HTTP `Content-Security-Policy` HEADER, never a `<meta http-equiv>` tag, so `frame-ancestors` / `report-uri` work. The emitted `<meta name="csp-nonce">` is only the client-side nonce CARRIER. Across a client-router soft navigation the ORIGINAL page-load nonce stays authoritative (the browser enforces the original document's CSP header, not the fetched response's fresh one), so the router preserves that meta and re-stamps every dynamically-inserted script / preload with the original nonce via `getCspNonce()`. The server still mints a fresh nonce per request, and CSP pages are excluded from the HTML cache so a nonce is never served stale. No client config is needed.
+
 ### Redirects, trailing-slash, basePath, allowed origins
 
 ```jsonc

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

@@ -35,10 +35,13 @@ Note for anyone testing this: **the Chromium web-test-runner currently resolves
 ```
 
 ```js
-import { disableClientRouter } from '@webjsdev/core';
-disableClientRouter();
+import { disableClientRouter, enableClientRouter } from '@webjsdev/core';
+disableClientRouter();   // stop intercepting document <a> / <form> (plain links resume full loads)
+enableClientRouter();    // turn soft navigation back on
 ```
 
+`disableClientRouter()` / `enableClientRouter()` are a runtime pair that toggle only the document-level `<a>` / `<form>` interception. An explicit `navigate(url)` call still does a soft navigation either way (it is not gated by the toggle).
+
 Per link, opt out with `data-no-router` (auth flows like `/logout`, OAuth redirects, print views, an experimental route with a different runtime). Cross-origin hrefs, `download`, a non-`_self` target, pure same-page hash jumps, and non-HTML extensions are auto-skipped.
 
 **Programmatic navigation and cache eviction.**
@@ -113,8 +116,17 @@ The router can wrap a navigation's DOM mutation in the native View Transitions A
 <meta name="view-transition" content="same-origin">
 ```
 
+A page (or layout) does not write raw `<head>` markup, so emit that meta through the `other` metadata field, which scopes it to the page that declares it:
+
+```ts
+// app/gallery/page.ts
+export const metadata = { other: { 'view-transition': 'same-origin' } };
+```
+
 The accepted value is `same-origin`. When enabled it wraps every swap path (the two-tier boundary swap, the `<webjs-frame>` swap, and the background-revalidation full-body path). When `startViewTransition` is unavailable the swap runs synchronously with no flash and no throw. To persist a live element (a playing `<audio>`, an open menu) across a swap by node identity, mark it `data-webjs-permanent` and give it an `id`.
 
+The opt-in is **per page**, so it is a page-scoped meta: put it on a page's metadata to animate that page, or on the root layout to animate the whole app. Navigating to a page that does NOT declare it turns transitions back off, because the soft-nav head merge reconciles page-scoped `<meta>` tags (a stale one the previous page declared is removed, not left to leak, #1046). View transitions **compose with Suspense streaming**: a streamed boundary (a `loading.{js,ts}` skeleton or a `<webjs-suspense>` region) navigated to under an active transition still resolves its content progressively, because the streamed resolve waits for the transition's DOM swap to commit before it applies (#1048).
+
 ## `<webjs-stream>` Surgical Updates
 
 `<webjs-stream>` is WebJs's take on Turbo Streams, and the action set mirrors `<turbo-stream>`. It is the only SINGLE-element update primitive (append one row, remove one item, bump a count, insert a toast), whereas a frame or layout swap redraws a whole region.
@@ -186,13 +198,25 @@ export function WS(ws, req, { params }) {
 }
 ```
 
-**Client.** `connectWS(url, handlers)` from `@webjsdev/core` auto-reconnects with exponential backoff, handles JSON parse/stringify, and queues sends while disconnected.
+**Client.** `connectWS(url, handlers)` from `@webjsdev/core` auto-reconnects with exponential backoff, handles JSON parse/stringify, and queues sends while disconnected. The handler set is `{ onOpen, onMessage, onClose }`, and it RETURNS a connection handle with `.send(data)` and `.close()`. Open it in `connectedCallback` and close it in `disconnectedCallback`, driving a connection-status signal from `onOpen` / `onClose`:
 
 ```js
 import { connectWS, renderStream } from '@webjsdev/core';
-connectWS('/feed', { onMessage: (m) => renderStream(m) });
+
+connectedCallback() {
+  super.connectedCallback();
+  this.conn = connectWS('/feed', {
+    onOpen:    () => (this.online = true),
+    onClose:   () => (this.online = false),
+    onMessage: (m) => renderStream(m),   // apply a server-pushed <webjs-stream> payload
+  });
+}
+disconnectedCallback() { super.disconnectedCallback(); this.conn?.close(); }
+send(text) { this.conn.send(text); }
 ```
 
+**Gotcha: a component re-render clobbers surgical `renderStream()` updates.** `renderStream()` (and `<webjs-stream>` in general) mutates the DOM out of band, appending rows the component's own `render()` does not know about. If the component then re-renders, `render()` re-runs and wipes those out-of-band rows. So render the target container ONCE and drive any mutation counter with a PLAIN instance field, never a signal or reactive prop that `render()` reads (a read would re-render and blow away the streamed-in DOM).
+
 **Broadcast.** `broadcast(path, data)` from `@webjsdev/server` fans a message to every connected client on that path (single-instance). For multi-instance, add Redis pub/sub yourself, there is no framework magic.
 
 ## Navigation-Loading Indicator (opt-in)

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

@@ -3,11 +3,13 @@
 ## What This Covers
 
 - Declaring reactive properties through the `WebComponent({ ... })` factory and `prop()`, with options (`reflect`, `state`, `attribute`, `default`, `converter`, `hasChanged`)
-- Signals as the default state primitive for component-local and shared state
+- Signals as the default state primitive for component-local and shared state, plus `effect` / `batch`
 - The Lit-aligned lifecycle and exactly which hooks SSR runs versus skips
 - Light DOM (default) versus shadow DOM, and the light-host `display: block` rule
 - Slots with full shadow-DOM parity in both DOM modes
 - `async render()`: SSR-blocking first paint, client stale-while-revalidate, `renderFallback()` / `renderError()`
+- `Task` for client-only async data, and context (`createContext` / `ContextProvider` / `ContextConsumer`) to avoid attribute drilling
+- The lit-html directive set (`repeat`, `watch`, `live`, `keyed`, `guard`, `cache`, `until`, `unsafeHTML`, `ref`, `asyncAppend` / `asyncReplace`, `templateContent`)
 - Display-only elision (when a component is stripped from the browser)
 - Inherited members app code must NOT shadow (`title`, `remove`, `render`, ...)
 
@@ -70,6 +72,19 @@ const count = computed(() => cart.get().length); // derived
 
 Read with `signal.get()` inside `render()`; the built-in `SignalWatcher` tracks the read and re-renders on change. An instance signal created in the constructor is component-local. For a fine-grained DOM swap use `${watch(signal)}` from `@webjsdev/core/directives`.
 
+Two more signal primitives from `@webjsdev/core` cover client-side reactions and batched writes:
+
+- `effect(fn)` runs `fn` now and re-runs it whenever a signal it read changes. It is a BROWSER-ONLY side-effect primitive (a subscription, a `document.title` sync, an analytics ping), not a render path. It returns a disposer, so create it in `connectedCallback` and call the disposer in `disconnectedCallback` to avoid a leak.
+- `batch(fn)` coalesces several `.set()` writes inside `fn` into ONE re-render instead of one per write. Reach for it when a handler updates multiple signals at once.
+
+```ts
+import { signal, effect, batch } from '@webjsdev/core';
+const open = signal(false), count = signal(0);
+connectedCallback() { super.connectedCallback(); this.dispose = effect(() => { document.title = `(${count.get()})`; }); }
+disconnectedCallback() { super.disconnectedCallback(); this.dispose?.(); }
+reset() { batch(() => { open.set(false); count.set(0); }); }   // one re-render, not two
+```
+
 ## Lifecycle (Lit-aligned) and what SSR runs
 
 Each update cycle runs these in order; each receives a `changedProperties` Map.
@@ -158,6 +173,71 @@ Errors are isolated per component by default (no user code): a thrown `await` re
 
 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.
 
+## Task: client-only async data
+
+For async data that is genuinely CLIENT-only (it depends on a click, viewport, or a live source, so `async render()` cannot bake it in at SSR), use the `Task` reactive controller. It shows its pending state at SSR (staying `INITIAL`), then runs in the browser.
+
+```ts
+import { Task, TaskStatus } from '@webjsdev/core/task';
+
+class SearchResults extends WebComponent({ q: String }) {
+  #search = new Task(this, {
+    task: async ([q], { signal }) => (await fetch(`/api/s?q=${q}`, { signal })).json(),
+    args: () => [this.q],   // the args array spreads into the task's first parameter
+  });
+  render() {
+    switch (this.#search.status) {
+      case TaskStatus.PENDING: return html`<p>Searching...</p>`;
+      case TaskStatus.ERROR:   return html`<p>${this.#search.error.message}</p>`;
+      case TaskStatus.COMPLETE: return html`<ul>${this.#search.value.map((r) => html`<li>${r.title}</li>`)}</ul>`;
+      default: return html`<p>Type to search.</p>`;   // INITIAL (also the SSR state)
+    }
+  }
+}
+```
+
+`args()` re-runs the task whenever its return changes; call `this.#task.run()` to trigger it manually. `TaskStatus` is `INITIAL` / `PENDING` / `COMPLETE` / `ERROR`. Prefer `async render()` for server data that should be in the first paint; reach for `Task` only when the data cannot exist until the browser runs.
+
+## Context: share state without attribute drilling
+
+When a value must reach a deep descendant without threading it through every intermediate component's attributes, use context (from `@webjsdev/core/context`). This is a CLIENT-TIME concern: a provider publishes on connect, so context is empty at SSR. For server-known data, pass it through the page function or a `.prop` instead (see `muscle-memory-gotchas.md`).
+
+```ts
+import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context';
+
+export const themeContext = createContext<'light' | 'dark'>('theme');
+
+class ThemeRoot extends WebComponent({}) {
+  #provider = new ContextProvider(this, { context: themeContext, initialValue: 'dark' });
+  toggle() { this.#provider.setValue(this.#provider.value === 'dark' ? 'light' : 'dark'); }
+}
+
+class ThemedCard extends WebComponent({}) {
+  #theme = new ContextConsumer(this, { context: themeContext, subscribe: true }); // re-renders on change
+  render() { return html`<div class=${this.#theme.value === 'dark' ? 'bg-black' : 'bg-white'}>...</div>`; }
+}
+```
+
+`subscribe: true` re-renders the consumer on every provider change; omit it for a one-shot read. A component can also fire a `ContextRequestEvent` to pull a value imperatively.
+
+## Directives (lit-html parity)
+
+Import from `@webjsdev/core/directives`. Everything a `class`/`style`/conditional needs is plain JS (`classMap` is `class=${cond ? 'a' : 'b'}`, `when` is a ternary, `map` is `.map`); reach for a directive only for the jobs below.
+
+| Directive | Use it for |
+|---|---|
+| `repeat(items, keyFn, tpl)` | A keyed list where items reorder / insert / remove (preserves DOM + state per key). A static list is a plain `.map`. |
+| `watch(signal)` | A fine-grained DOM swap of one signal's value without re-rendering the whole component. |
+| `live(value)` | An `input` / `textarea` `.value` bound to state, so a user edit that equals the last committed value still resets. |
+| `keyed(key, tpl)` | Force a fresh subtree (discard old DOM + state) when `key` changes. |
+| `guard(deps, () => tpl)` | Skip re-rendering an expensive subtree unless `deps` change. |
+| `cache(tpl)` | Keep the DOM of an inactive branch around when toggling between templates. |
+| `until(promise, fallback)` | Render `fallback` until `promise` resolves (prefer `Task` in a component, `Suspense` for a page). |
+| `unsafeHTML(str)` | Render a TRUSTED raw HTML string. NEVER pass user input (XSS). |
+| `ref(cb)` / `createRef()` | Get a handle to the rendered DOM node. |
+| `asyncAppend(iter)` / `asyncReplace(iter)` | Stream from an async iterable, appending each value or replacing with the latest. |
+| `templateContent(el)` | Render the content of a `<template>` element. |
+
 ## Display-only elision
 
 A component that does no client-side work renders the same SSR'd HTML with or without its JS, so WebJs strips its import from the served source (and any vendor reachable only through it). This is automatic and conservative. A component stays elidable while it has NONE of:
@@ -174,7 +254,7 @@ A bare `async render()` (no other signal, light DOM) is elided too: the SSR'd da
 
 ## Members app code must not shadow
 
-A `WebComponent` inherits `HTMLElement` (browser) or an `ElementShim` (SSR) plus the framework reactivity base. A reactive prop or method whose NAME collides either fails to compile (`TS2415` for a type-incompatible property, `TS2416` for a method signature) or silently hijacks the native member at runtime. The fix is always to rename.
+A `WebComponent` inherits `HTMLElement` (browser) or an `ElementShim` (SSR) plus the framework reactivity base. A reactive prop or method whose NAME collides either fails to compile (`TS2415` for a type-incompatible property, `TS2416` for a method signature) or silently hijacks the native member at runtime. The fix is always to rename. The DOM MUTATION methods WebJs instruments for the light-DOM slot API (`append`, `prepend`, `before`, `after`, `replaceWith`, `replaceChildren`, `remove`, `appendChild`, `insertBefore`, `removeChild`, `replaceChild`) are the dangerous case TypeScript does NOT catch (a shorter override is assignable to the native signature), so a handler named `append()` compiles yet silently never runs. `webjs check`'s `no-shadowed-native-member` rule catches exactly these.
 
 - HTMLElement / Element: `title`, `id`, `slot`, `role`, `hidden`, `dir`, `lang`, `translate`, `draggable`, `tabIndex`, `className`, `dataset`, `remove`, `closest`, `matches`, `focus`, `blur`, `click`, `append` / `prepend`, `before` / `after`. Rename (`postTitle`, `removeItem`, `handleClick`).
 - WebComponent base: `render`, `update`, `requestUpdate`, `updated` / `firstUpdated`, `willUpdate` / `shouldUpdate`, `connectedCallback`, `renderError` / `renderFallback`, `addController` / `removeController`, `updateComplete` (#1021: there is no WebJs slot API to override; slots are native). Only override one deliberately, with its exact signature; never repurpose the name for app logic.

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

@@ -5,7 +5,7 @@
 - The `modules/<feature>/` architecture (thin `app/` adapters, `actions/` mutations, `queries/` reads, one function per file)
 - `'use server'` RPC actions, the serializer-safe wire, and how a client import becomes a typed stub
 - Input validation at the boundary via `export const validate`
-- HTTP-verb config exports (`method`, `cache`, `tags`, `invalidates`, `middleware`)
+- HTTP-verb config exports (`method`, `cache`, `tags`, `invalidates`, `middleware`), the middleware `ctx` shape, and `actionSignal()` cancellation
 - The `ActionResult<T>` envelope and its robust failure detection
 - The `route()` REST adapter that exposes an action over HTTP
 - Drizzle rc.3 reads (`db.query.*`) and mutations (`.returning()`)
@@ -141,7 +141,24 @@ 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`.
 - **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`.
+- 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.
+
+### Cancellation with `actionSignal()`
+
+Inside an action, `actionSignal()` from `@webjsdev/server` returns the request's `AbortSignal`. It fires when the client disconnects OR when a newer client render supersedes this one (the RPC stub aborts the previous in-flight fetch). Thread it into the work you start, and re-check it after an await to map an abort to a cancelled envelope:
+
+```ts
+'use server';
+import { actionSignal } from '@webjsdev/server';
+export async function search(q: string) {
+  const signal = actionSignal();
+  const res = await fetch(`https://api/x?q=${q}`, { signal });   // aborts the fetch on disconnect
+  if (signal.aborted) return { success: false, error: 'Request cancelled.', status: 499 };
+  return { success: true, data: await res.json() };
+}
+```
+
+A guard placed BEFORE any await can never fire (nothing has yielded yet). Outside an action the signal never aborts, so a server-to-server call stays safe.
 
 ## The `ActionResult<T>` envelope
 

package/templates/.agents/skills/webjs/references/optimistic-ui.md

@@ -67,6 +67,24 @@ TodoList.register('todo-list');
 - Multiple `.add()` calls stack independently. Each carries its own release by ID, so overlapping in-flight mutations do not clobber one another.
 - When `update` is omitted, the payload REPLACES the state directly (`Action = State`), matching the simple `useOptimistic(setState)` pattern.
 
+### Author the optimistic mutation as a degrade-first form
+
+Wrap the mutation in a REAL `<form method="post" action="">` posting to the page's own URL, then intercept it for the optimistic path. One form then serves both: with JS off the browser submits to the page `action` (the no-JS write path, see `routing-and-pages.md`), and with JS on `@submit` calls `e.preventDefault()` and runs the optimistic path. That is the progressive-enhancement contract, not a fetch-only handler.
+
+```ts
+render() {
+  return html`
+    <form method="post" action="" @submit=${this.handleSubmit}>
+      <input type="hidden" name="intent" value="create">   <!-- one page action dispatches on intent -->
+      <input name="title" required>
+      <button>Add</button>
+    </form>
+    <ul>${this.optimisticTodos.value.map(t => html`<li class=${t.pending ? 'opacity-50' : ''}>${t.title}</li>`)}</ul>`;
+}
+```
+
+When a page owns SEVERAL mutations (create, toggle, delete), give each form a hidden `intent` field and let the single page `action` dispatch on it. Each interactive control (a toggle button, a delete button) is also its own tiny form so it still works with JS off.
+
 ## Seed the list from the server for SSR plus optimistic
 
 For a page that server-renders a list AND lets the user add to it optimistically, let ONE component own both the list and the form, and seed it from the page through a `.prop` hole (a DOM property that round-trips through SSR on custom elements). The list is then fully server-rendered on first paint (readable with JS off) and re-renders optimistically on each add. A separate static list in the page would not update on an optimistic add.

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

@@ -4,8 +4,8 @@
 
 - Pages, layouts, and where the HTML shell comes from
 - Dynamic (`[param]`), catch-all (`[...rest]`), and optional catch-all (`[[...rest]]`) segments, route groups, private folders
-- `route.ts` HTTP handlers and `middleware.ts`
-- `metadata` and `generateMetadata` (folded in here)
+- `route.ts` HTTP handlers and `middleware.ts`, the route-handler toolkit (`json` / `readBody` / `clientIp` / the no-arg accessors), and calling one from the client with `richFetch`
+- `metadata` and `generateMetadata` (folded in here), including image metadata routes that return a `Response`
 - Control-flow throws: `notFound()`, `redirect()`, `forbidden()`, `unauthorized()`
 - The no-JS page `action` write path
 - Boundaries: `error.ts`, `loading.ts`, `not-found.ts`, `forbidden.ts`, `unauthorized.ts`, and the two root-only ones
@@ -78,6 +78,18 @@ export async function GET() {
 
 **NEVER throw `redirect()` / `notFound()` / `forbidden()` inside a `route.ts` handler** (an uncaught throw is a generic 500). Return a real response instead: `return Response.redirect(url, 303)` for a redirect, `return new Response('Not Found', { status: 404 })` for a 404. A `route.ts` is also NOT covered by the action CSRF check, so authenticate every mutating endpoint, validate, and rate-limit. Export `WS(ws, req, { params })` from the same file for a WebSocket endpoint.
 
+**The route-handler toolkit** (from `@webjsdev/server`). Two accessors take the request explicitly: `readBody(req)` decodes a rich request body (the inverse of `json()`, round-tripping `Date` / `Map` / `Set` / `BigInt` / `Blob`), and `clientIp(req)` reads the caller IP. To respond with rich types, `json(value)` serializes with the same wire (so a `Date` survives), versus a plain object return that auto-JSONs. The context accessors take NO argument because they read the in-flight request from context: `headers()`, `cookies()`, `requestId()`, `cspNonce()`.
+
+```ts
+import { json, readBody, clientIp } from '@webjsdev/server';
+export async function POST(req: Request) {
+  const body = await readBody(req);            // rich types decoded
+  return json({ at: new Date(), ip: clientIp(req) });  // Date survives the wire
+}
+```
+
+**Calling your own `route.ts` from the client:** use `richFetch<T>(url, opts?)` from `@webjsdev/core`, a drop-in `fetch` that sends `Accept: application/vnd.webjs+json`, encodes a plain-object `body` with the rich wire, and decodes the `json()` response (so `data.at` is a real `Date`). This is the ONE legitimate hand-fetch (importing a `'use server'` action is the way to call the server otherwise, never a hand-written `fetch` to an action).
+
 ## Middleware (`middleware.ts`)
 
 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.
@@ -156,3 +168,14 @@ How the result is read (server side): a success PRG-redirects with `303` (to a s
 - Root-only (in `app/` exactly): `global-error.ts` is the app-wide catch-all after nested `error` boundaries are exhausted and renders its OWN `<!doctype><html><body>` (returned verbatim, so keep it static HTML with no components or hydration). `global-not-found.ts` renders for an unmatched-anywhere URL when no `not-found` matches.
 
 Metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `apple-icon.ts`, `opengraph-image.ts`, `twitter-image.ts`) live at app root or static segments and default-export a possibly-async function; `sitemap()` / `sitemapIndex()` from `@webjsdev/server` serialize spec-valid XML.
+
+The IMAGE metadata routes (`icon`, `apple-icon`, `opengraph-image`, `twitter-image`) default-export a function returning a `Response` with an explicit `content-type`, so an inline SVG needs no asset file (buildless). Then point `metadata` at the route via `openGraph.images` / `twitter.images` / `icons` (or drop a static file in `public/` instead).
+
+```ts
+// app/opengraph-image.ts  (OG is 1200x630; apple-icon 180x180)
+export default function OgImage() {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">...</svg>`;
+  return new Response(svg, { headers: { 'content-type': 'image/svg+xml' } });
+}
+// app/page.ts  ->  export const metadata = { openGraph: { images: ['/opengraph-image'] } };
+```

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

@@ -8,6 +8,7 @@
 - Design tokens: `:root` / `@theme` in the root layout
 - Light-DOM host `display: block` behaviour (and shadow hosts via `:host`)
 - When to use `static styles` (shadow DOM)
+- Accessible native controls (label association, `aria-pressed`, `aria-label`)
 - `position: fixed`, not `sticky`, for a pinned header (the iOS WebKit flicker)
 - Even-grid / no-reflow layout tips
 
@@ -67,9 +68,77 @@ export default function Post({ params }) {
 
 Avoid `@apply`: it hides which utilities a class uses and creates a second source of truth. A JS helper keeps the bundle visible at the definition site, composes with conditional classes and active states, and runs at SSR time.
 
-## Design tokens
+### A design system for repeated PRIMITIVES: class helpers built on `@webjsdev/ui`
 
-The default stack is a static compiled Tailwind stylesheet (`css:build` compiles `public/input.css` to the linked `public/tailwind.css`, so it works with JS off) plus `@theme` design tokens (palette, fonts, fluid type, motion durations) declared once in the root layout. Consume them as utility classes (`text-foreground`, `bg-card`, `font-serif`, `duration-fast`). If you wire your own theme switch, drive BOTH signals on `<html>` (the `data-theme` attribute for the app palette blocks AND the `.dark` class for the `@webjsdev/ui` kit), or half the UI renders stale tokens. Verify dark mode in a real browser, light mode passing proves nothing about dark.
+An `html`-fragment helper is right for a repeated CHUNK of markup (the rubric above). For a repeated UI PRIMITIVE (button, input, card, badge) that needs variants and sizes, use a class helper instead: a function that returns a Tailwind class STRING you spread onto a native element. That is exactly what `@webjsdev/ui` ships (`buttonClass({ variant, size })`, `cardClass()`, `inputClass()`, `badgeClass({ variant })`), and it is what the scaffold gallery uses in `components/ui/`. To style a ONE-OFF that a variant does not cover (a circular icon button, a pill), compose the helper and override the bespoke bits with `cn()`: `cn(buttonClass({ variant: 'secondary', size: 'none' }), 'w-9 h-9 rounded-full')`. `cn` resolves Tailwind conflicts so a later class wins, including a shorthand over the axis it subsumes (`p-0` beats an earlier `px-4 py-2`), so an override just works. For an icon button prefer `size: 'none'` (it states "I supply my own box" by dropping the helper's padding + radius) over layering a `p-0` on top of the default size.
+
+```ts
+// components/ui/button.ts  (webjs ui add button, themed to your app)
+import { cn } from '#lib/utils/cn.ts';
+const BASE = 'inline-flex cursor-pointer items-center justify-center ...';
+const VARIANTS = { default: 'bg-primary text-primary-foreground ...', secondary: '...' } as const;
+const SIZES = { default: 'px-4 py-2 rounded-xl', sm: '...' } as const;
+export function buttonClass(o: { variant?: keyof typeof VARIANTS; size?: keyof typeof SIZES } = {}) {
+  return cn(BASE, VARIANTS[o.variant ?? 'default'], SIZES[o.size ?? 'default']);
+}
+```
+
+```ts
+// a page or component
+import { buttonClass } from '#components/ui/button.ts';
+html`<button class=${buttonClass({ variant: 'secondary', size: 'sm' })} @click=${...}>Reset</button>`;
+```
+
+Why a class helper (not a `<ui-button>` wrapper): it adds NO indirection, so the element stays native (`@click`, `?disabled`, form submission, focus, a11y all just work) and the markup stays readable, while every button shares one source of truth (so no button can forget `cursor-pointer` or drift). Put the affordance every variant needs (like `cursor-pointer`) on the shared BASE.
+
+**Default: `webjs ui add`, then modify. Do not hand-write a primitive from scratch.** For a repeated primitive with variants, run `webjs ui add <name>` then trim and theme the copied source. The scaffold already ships the `cn` prerequisite at `lib/utils/cn.ts`, so `add` works out of the box (a non-scaffold app runs `webjs ui init` once first to write `components.json`, the `cn` util, and the design tokens). The kit is shadcn-style, so `add` COPIES the helper's source INTO your `components/ui/` and you own and edit it exactly as freely as code you typed yourself. That is the key point: `add`-then-modify and hand-writing end at the SAME place (owned, editable class-helper source), so the difference is only the STARTING POINT. `add` starts you from vetted, variant-complete source you then adapt (and the copied header spells out the primitive's accessibility obligations), where hand-writing starts from a blank file and re-derives all of it for no benefit. Theme it to YOUR app (change the class values so the helper produces YOUR look, rather than bending your app to the kit's defaults) and keep only the parts you use (the gallery's `cardClass` is surface-only, since its panels vary their own padding and layout). Hand-author a primitive yourself ONLY for a one-off the kit does not cover, or a deliberate opt-out of the kit. Reserve `lib/utils/ui.ts` `html`-fragment helpers for repeated markup chunks; reserve `components/ui/*` class helpers for themed primitives with variants.
+
+## Accessible native controls
+
+Even with the kit, an app hand-authors SOME markup (a one-off primitive the kit does not cover, or the native element you wrap a class helper around), and there accessibility is your job (the `@webjsdev/ui` primitives carry their own, but a raw `<button>` / `<input>` does not). Three habits keep hand-authored interactive markup accessible on BOTH the JS and no-JS paths:
+
+- **Associate a label with its control.** `<label for="email">` paired with `<input id="email">` (or wrap the control in the `<label>`), so a click on the label focuses the field and a screen reader announces it.
+- **State a toggle's pressed state.** A button that toggles carries `aria-pressed=${on}` so assistive tech announces on/off, not just "button".
+- **Name an icon-only button.** A button whose only content is an icon has no accessible name, so give it `aria-label="Delete task"`.
+
+Native `<button>` / `<a>` / `<input>` already have correct focus + keyboard behaviour, which is the main reason to prefer them (and the `buttonClass()` / `inputClass()` class helpers) over a custom `<div role>` element.
+
+## Design tokens and theming
+
+The default stack is a static compiled Tailwind stylesheet (`css:build` compiles `public/input.css` to the linked `public/tailwind.css`, so it works with JS off) plus `@theme` design tokens declared once in the root layout. You consume them as utility classes (`bg-background`, `text-foreground`, `bg-card`, `border-border`, `font-serif`).
+
+**Two halves.** (1) `public/input.css` MAPS token names into Tailwind with `@theme inline` (`--color-background: var(--background)`), so `bg-background` resolves to `var(--background)`. That is infrastructure; leave it. (2) The root layout (`app/layout.ts`) DEFINES the values as plain CSS custom properties in a `<style>` block. That is your palette; make it your own. A freshly cleared app (after `npm run gallery:clear`) ships only the OS system-colour base (`Canvas` / `CanvasText`) with NO tokens, so building this palette is your first styling step.
+
+**Light and dark, defined once (DRY).** Write each colour token ONE time with the native CSS `light-dark(LIGHT, DARK)` function and let `color-scheme` pick the side. The default `color-scheme: light dark` follows the OS; a `[data-theme]` attribute forces one. No duplicated light/dark blocks:
+
+```html
+<style>
+  :root {
+    --font-sans: ui-sans-serif, system-ui, sans-serif;
+    color-scheme: light dark;                        /* follow the OS by default */
+    --background:       light-dark(#ffffff, #1e2226);
+    --foreground:       light-dark(#191c20, #dee2e6);
+    --card:             light-dark(#f7f8fa, #313539);
+    --muted-foreground: light-dark(#565c64, #94989c);
+    --border:           light-dark(#e2e5e9, #3d434b);
+    --primary:          light-dark(#1e2226, #dee2e6);
+    /* a derived token tracks BOTH themes for free via var(--primary) */
+    --primary-tint: color-mix(in srgb, var(--primary) 22%, transparent);
+  }
+  :root[data-theme='light'] { color-scheme: light; }  /* the toggle forces a scheme */
+  :root[data-theme='dark']  { color-scheme: dark; }
+</style>
+```
+
+`light-dark()` is a native CSS function (CSS Color 5, Baseline 2024), not a library, so nothing to import. A single-theme app drops the `[data-theme]` rules and gives each token one colour.
+
+**A manual theme toggle** writes `data-theme` on `<html>` (`light` / `dark`, or removes it for "follow the OS"). If you use `@webjsdev/ui` components, ALSO keep the `.dark` class in sync (the ui kit keys its own tokens off `.dark`), and apply the saved choice in a tiny inline `<script>` in the layout head so there is no first-paint flash. Verify dark mode in a real browser. Light mode passing proves nothing about dark.
+
+**Edge cases.** `light-dark()` is COLOUR-only. A colour needed in just one theme sets the unused side to a no-op (`light-dark(#fff, transparent)`). A derived token that references a `light-dark()` one (like `--primary-tint` above) tracks both themes automatically. A NON-colour token that must differ per theme (a shadow's geometry, a gradient, a size, an image) cannot use `light-dark()`; give it a `:root[data-theme='dark']` override plus an `@media (prefers-color-scheme: dark) { :root:not([data-theme]) { ... } }` rule for the OS default.
+
+**The ui class helpers build on these tokens.** `buttonClass()` / `cardClass()` / `inputClass()` / `badgeClass()` emit Tailwind utilities that reference the same tokens (`bg-primary`, `border-border`), so theming the tokens re-skins every helper at once.
+
+**Focus rings.** The design system applies ONE themed, keyboard-only focus ring globally in the theme CSS: `@layer base { * { @apply border-border outline-ring/50 } }` themes the outline COLOUR to `--ring/50`, and a `:focus-visible { outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent); outline-offset: 2px }` forces a SOLID outline. That second rule matters: `outline-ring/50` alone leaves `outline-style: auto`, so the browser draws its OWN focus ring (which can look thick and white and ignore the colour). So every focusable element (button, link, input) shares one `--ring`-coloured ring with no per-element styling (a native `<button>` renders it a touch wider than a link, a Chromium form-control quirk, but the colour is the same). Do NOT re-add a focus style on a light-DOM element (`buttonClass` deliberately carries none), and NEVER remove it (`outline: none` with no replacement fails WCAG 2.4.7). `:focus-visible` already limits the ring to keyboard / programmatic focus, not a mouse click. A SHADOW-DOM component is the ONE exception: a document rule cannot cross the shadow boundary, so it styles its own focus in `static styles`, matching the global ring EXACTLY (`--ring` at 50%, the same as `outline-ring/50`): `button:focus-visible { outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent); outline-offset: 2px }`. Without it, its controls fall back to the raw browser outline (thick, light on a dark theme, and shown on window-refocus).
 
 ## Light-DOM host display, and shadow hosts
 
@@ -83,6 +152,17 @@ static styles = css`:host { display: block }`;   // a shadow host with no :host
 
 **Size the HOST, not just an inner wrapper.** The host custom element is the box the parent lays out. A host that is a flex/grid item in a centering parent (`flex justify-center`, `grid place-items-center`) is sized to its content unless it carries width itself. Put the sizing classes on the host (`w-full max-w-[400px]`), not only on an inner `<div>`. Symptom: a board or card renders tiny even though its inner grid says `w-full max-w-[400px]`. Fix: move the sizing onto the host.
 
+## Section rhythm: one gap, defined once
+
+Per-element margins can never give consistent vertical spacing: each element controls only one side, so a block's gap-above (the previous element's margin) drifts from its gap-below (its own). For a content column (a docs page, a demo page, an article), make the COLUMN own the spacing with a flex stack, and zero the children's own margins so only the one gap applies:
+
+```css
+.stack { --section-gap: 1.5rem; display: flex; flex-direction: column; gap: var(--section-gap); }
+.stack > * { margin: 0; }
+```
+
+Every top-level child (heading, paragraph, component, list) is then equally spaced from ONE variable, and a spacing change is a one-line edit. Flex `gap` beats forcing `display: block` + margins on children: a `grid`/`flex` child keeps its own layout (a blanket `display: block` clobbers it), an inline shadow-DOM host is blockified as a flex item so it honours the gap, a `display: contents` element (a streaming `<webjs-suspense>`) is replaced by its children which become the flex items, and a `display: none` node (a streaming `<script>`/`<template>`) is not an item at all, so it gets no phantom gap. A group that must stay tight (a caption directly above its code block) wraps in one child `<div>` and keeps its own inner spacing. The gallery's `/features` layout (`demo-stack`) is the worked example.
+
 ## Even grids, no reflow
 
 The reflow bug (a cell grows when it gets content while the others shrink) comes from `auto`-sized grid rows. Size the tracks explicitly so every cell is an equal fraction regardless of content:

package/templates/.agents/skills/webjs/references/ui-kit.md

@@ -1,8 +1,13 @@
 # The `@webjsdev/ui` component kit
 
-Load this when the app has a `components.json` (it uses `@webjsdev/ui`, the
-shadcn-style kit for WebJs). The source is copied into your repo (`components/ui/`),
-so you own and edit it. Two tiers:
+Load this when the app uses `@webjsdev/ui` (a `components.json` is present), OR
+when you are about to add a UI primitive (button, card, input, badge) to a fresh
+app that has not initialised the kit yet: running `webjs ui init` then
+`webjs ui add <name>` is HOW the kit comes to exist, and it is the default for a
+repeated primitive over hand-writing one from scratch. `@webjsdev/ui` is the shadcn-style
+kit for WebJs. The source is copied into your repo (`components/ui/`), so you own
+and edit it exactly as freely as code you wrote yourself (the copied file is
+yours to trim and theme). Two tiers:
 
 - **Tier 1, class helpers (23 components).** Pure functions returning Tailwind
   class strings (`buttonClass({ variant })`, `cardClass()`), composed with

package/templates/AGENTS.md

@@ -30,14 +30,22 @@ The order matters:
    `.agents/skills/webjs/` teaches the same patterns and SURVIVES the clear, so
    clearing is not a knowledge-loss event, the gallery is just a runnable bonus.
 2. **Clear it.** Run `npm run gallery:clear` to shed the whole gallery in one
-   step (removes `app/features/`, `app/examples/`, the demo `modules/`, the demo
-   `todos` table, and resets `app/page.ts` to a minimal home), while KEEPING the
-   agent skill, the layout, and the database wiring.
+   step: it removes `app/features/`, `app/examples/`, the demo `modules/`, the
+   gallery's example design system (`components/ui/`, the theme-toggle), the
+   example tests, and the demo `todos` table, and resets `app/page.ts` to a
+   minimal home AND `app/layout.ts` to a token-free blank slate (OS system
+   colours, no navbar, no palette). A layout you already customised (the gallery
+   brand removed) is KEPT, with only the theme-toggle wiring stripped. It KEEPS
+   the agent skill, the database wiring, and `lib/utils/cn.ts` (the
+   `webjs ui add` prerequisite).
 3. **Build.** Regenerate the database (`npm run db:generate` then `npm run
    db:migrate`), then grow the app in place: routes under `app/`, components
    under `components/`, features under `modules/<feature>/`, server-only code
-   behind `.server.ts`, and the app's own palette via the tokens in
-   `app/layout.ts`.
+   behind `.server.ts`. Build the app's OWN design system from the blank slate:
+   define design tokens in `app/layout.ts` and pull primitives with
+   `npx webjsdev ui add <name>` then theme the copied source (you own it, so
+   modify it rather than hand-writing a primitive from scratch), following
+   `.agents/skills/webjs/references/styling.md`.
 
 If you are only exploring, keep the gallery and browse it.
 

package/templates/gallery/app/apple-icon.ts

@@ -1,14 +1,11 @@
-// (delete this file), then delete this marker line. webjs check fails while the
-// marker remains.
-//
 // app/apple-icon.ts serves /apple-icon (the Apple touch icon iOS uses when a
 // visitor adds the site to their home screen). Apple expects a 180x180 square
 // with no rounded corners (iOS rounds them). Same shape as icon.ts: return a
 // Response with the exact content type. Swap the inline SVG for your real mark.
 export default function AppleIcon() {
   const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="180" height="180" viewBox="0 0 180 180">
-    <rect width="180" height="180" fill="#1c1613"/>
-    <text x="90" y="120" font-family="system-ui, sans-serif" font-size="104" font-weight="700" fill="#ff8a3d" text-anchor="middle">w</text>
+    <rect width="180" height="180" fill="#1e2226"/>
+    <text x="90" y="120" font-family="system-ui, sans-serif" font-size="104" font-weight="700" fill="#94989c" text-anchor="middle">w</text>
   </svg>`;
   return new Response(svg, {
     headers: { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=3600' },

package/templates/gallery/app/examples/layout.ts

@@ -1,11 +1,16 @@
 import { html } from '@webjsdev/core';
+import { backLink } from '#lib/utils/ui.ts';
 
 // Shared layout for every gallery example app under /examples/*. It adds the same
 // slim "back to the gallery" link the feature demos get, so an example is never a
 // dead end. A non-root layout, so it never writes the document shell.
 export default function ExamplesLayout({ children }: { children: unknown }) {
+  // An example app has no sidebar, so center it in a focused reading column
+  // (the root centers the whole page; this narrows the example within it).
   return html`
-    <a href="/" class="inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground transition-colors no-underline mb-6">&larr; Gallery</a>
-    ${children}
+    <div class="max-w-xl mx-auto">
+      <div class="mb-6">${backLink('/', html`&larr; Gallery`)}</div>
+      ${children}
+    </div>
   `;
 }

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

@@ -4,6 +4,7 @@
 // lives in modules/todo/. This is the idiomatic app-thin + modules-logic split.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core'; // Metadata is a @webjsdev/core type
+import { pageHeading } from '#lib/utils/ui.ts';
 import { listTodos } from '#modules/todo/queries/list-todos.server.ts';
 import { createTodo } from '#modules/todo/actions/create-todo.server.ts';
 import { toggleTodo } from '#modules/todo/actions/toggle-todo.server.ts';
@@ -16,7 +17,7 @@ export default async function TodoExample() {
   // SSR-fetched and seeded, so <todo-app> paints the real list on first byte.
   const todos = await listTodos();
   return html`
-    <h1 class="text-h2 font-bold mb-4">Optimistic todo</h1>
+    ${pageHeading('Optimistic todo')}
     <todo-app .todos=${todos}></todo-app>
   `;
 }

package/templates/gallery/app/features/async-render/page.ts

@@ -1,5 +1,6 @@
 import { html, Suspense } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
+import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/async-render/components/server-clock.ts';
 
 export const metadata: Metadata = { title: 'Async render (server data in first paint) | features' };
@@ -14,8 +15,8 @@ async function slowRegion() {
 
 export default function AsyncRenderExample() {
   return html`
-    <h1 class="text-h2 font-bold mb-4">Async render</h1>
-    <p class="text-muted-foreground mb-4">A component's <code>async render()</code> awaits server data. SSR blocks, so the resolved value is in the first paint (no fallback, readable with JS off).</p>
+    ${pageHeading('Async render')}
+    ${lede(html`A component's <code>async render()</code> awaits server data. SSR blocks, so the resolved value is in the first paint (no fallback, readable with JS off).`)}
     <server-clock></server-clock>
     <p class="text-muted-foreground mt-6 mb-2">For a SLOW region where blocking the first byte hurts, wrap it in <code class="font-mono">Suspense</code> to stream it instead:</p>
     ${Suspense({ fallback: html`<p class="text-muted-foreground">loading slow region…</p>`, children: slowRegion() })}

package/templates/gallery/app/features/auth/dashboard/layout.ts

@@ -1,4 +1,5 @@
 import { html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 
 // Nested layout for the protected dashboard subtree. Logout is a plain
 // <form method="POST"> posting to the createAuth signout route: it clears the
@@ -12,7 +13,7 @@ export default function DashboardLayout({ children }: { children: unknown }) {
       <a href="/features/auth/dashboard" class="text-sm font-medium text-foreground hover:underline">Dashboard</a>
       <a href="/features/auth/dashboard/settings" class="text-sm font-medium text-foreground hover:underline">Settings</a>
       <form method="POST" action="/api/auth/signout" class="ml-auto">
-        <button type="submit" class="px-3 py-1.5 rounded-lg border border-border text-sm text-foreground bg-transparent cursor-pointer transition-colors hover:bg-accent">Log out</button>
+        <button type="submit" class=${buttonClass({ variant: 'secondary', size: 'sm' })}>Log out</button>
       </form>
     </nav>
     ${children}