@webjsdev/cli 0.10.40 → 0.10.41

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

@@ -0,0 +1,170 @@
+# Muscle-Memory Gotchas
+
+## What This Covers
+
+- The Next.js patterns that LOOK right in WebJs but break, because WebJs borrows Next's file-based routing shape but not its execution model (no RSC, no `'use client'` split): `redirect()` in a route handler, `fetch()` in a page, `<Link>`, `NEXT_PUBLIC_`, `await params`.
+- The Lit patterns that break WebJs SSR or reactivity, because WebJs is HTML-first (real HTML first paint, JS opt-in per behaviour) not JS-first: `static properties` / the `@property()` decorator, class-field initializers, browser globals in `render()`, fetching in `connectedCallback`, interpolation into `<style>`.
+- The WebJs-shaped fix for each, with short code.
+
+Read this when a pattern feels familiar from Next.js or Lit but you are not sure it transfers. For the component runtime see `components.md`; for the routing surface see `routing-and-pages.md`. The one difference underneath everything: pages and layouts render server-only and never hydrate, and the one client boundary is a `WebComponent` custom element.
+
+---
+
+## Coming from Next.js
+
+### `'use client'` does nothing; `'use server'` is a file boundary, not a component annotation
+
+There is no RSC render tree and no server/client component split. Interactivity lives in a `WebComponent` island that hydrates per element. A page or layout cannot be interactive in its own markup (an `@click` in a page template is dropped at SSR). `'use server'` is real, but it is the RPC plus source-protection directive at the top of a `*.server.ts` file, not a component annotation. Apply it to an action file, never to a component or page.
+
+### `redirect()` throws, and it is illegal in a route handler
+
+In Next, `redirect()` works in Server Components, Actions, and Route Handlers alike. In WebJs, `redirect()` and `notFound()` throw a control-flow sentinel that the SSR page pipeline and the action pipeline catch. They are valid in page functions, layouts, and server actions. They are NOT valid in a `route.ts` handler, where the throw goes uncaught and returns a 500 (the `no-redirect-in-api-route` check flags this).
+
+```ts
+// route.ts WRONG: redirect() is uncaught here.
+export async function GET() { redirect('/login'); }
+// route.ts RIGHT: return a real redirect Response.
+export async function GET() { return Response.redirect(new URL('/login', req.url), 303); }
+```
+
+Do NOT throw `redirect()` from a page `action` to bounce a form POST either. The method-preserving 307 default re-POSTs the body and re-runs the mutation. Return an `ActionResult` with a `redirect` field instead (a 303 PRG), or throw only for a real external redirect.
+
+### Reads are server actions, not `fetch()` in a Server Component
+
+Next fetches by calling `fetch()` or an ORM directly inside an async Server Component. WebJs has no Server Components, so fetch server data in the page function (server-only) and pass it down, or fetch in a component via an async `render()` (the resolved data is in the first paint), or a `'use server'` GET action.
+
+```ts
+// WRONG: hand-written fetch to your own endpoint.
+const res = await fetch('/api/users');
+// RIGHT: importing a 'use server' action IS the API (the import becomes an RPC stub).
+import { getUsers } from '#modules/users/queries/get-users.server.ts';
+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.
+
+### `params` and `searchParams` are awaitable AND synchronously readable
+
+Next 15/16 made `params` / `searchParams` Promises. WebJs supports BOTH, so either muscle memory is correct.
+
+```ts
+export default async function User({ params, searchParams }: PageProps<'/users/[id]'>) {
+  const id = params.id;              // sync read, works
+  const { id: id2 } = await params;  // Next 15/16 await, also works
+  const tab = (await searchParams).tab;
+}
+```
+
+The runtime hands a plain object with a non-enumerable `then`, so a spread, `JSON.stringify`, and `Object.keys` see only the data keys. This holds for pages, layouts, and `route.ts` handler context alike.
+
+### The page default export returns a template and runs server-only
+
+A Next page returns JSX and may embed client interactivity directly. A WebJs page default export returns a `TemplateResult` from `html` and runs only on the server. It is never re-invoked in the browser, so a signal read or `@click` in a page body does nothing after load. Put interactivity in a `WebComponent` and render its tag from the page.
+
+### Route handlers: named method exports, value returns auto-JSON
+
+Export `GET` / `POST` / etc. as named async functions `(request, { params }) => Response | value` (a non-Response value is auto-JSON'd). A folder cannot have both `page` and `route`. There is no `NextRequest` / `NextResponse`; use the platform `Request` / `Response`. A WebSocket endpoint is a `WS(ws, req, { params })` export from the same file.
+
+### `middleware.ts` is per-segment and chainable, not one matcher config
+
+The file stays `middleware.ts`, NOT Next 16's renamed `proxy.ts`. WebJs middleware is in-process, chainable, and per-segment (the Remix / Koa model). There is no `export const config = { matcher }` and no single-file restriction. The default export is `async (req, next) => Response`: return a Response to short-circuit, or call `next()` and post-process. Colocate `app/admin/middleware.ts` next to the admin routes and it runs for that subtree only. An optional root `middleware.ts` runs on every request, outermost to innermost.
+
+### No `<Link>`, no `next/navigation`, no `next/*` libraries
+
+Navigation is automatic. The client router auto-enables when `@webjsdev/core` loads (any page with a component), so a plain `<a href>` gets soft navigation for free. There is no `<Link>` to import and no `useRouter`. For programmatic navigation import `navigate()` / `revalidate()` from `@webjsdev/core`. There is no `next/image`, `next/font`, `next/script`, or `next/dynamic`. WebJs is no-build: use a plain `<img>`, a `<link>` / `@font-face`, a component's `static lazy = true` for viewport lazy-loading, and a dynamic `import()` where code should load lazily.
+
+### Server-only code: the `.server.ts` boundary, not a `server-only` package
+
+Next poisons a client-imported module with the `server-only` package. WebJs uses the file extension: `*.server.ts` is the path-level boundary (the file router refuses to serve the source). A `'use server'` file's exports are RPC-callable; a `.server.ts` file WITHOUT `'use server'` is a server-only utility whose browser import throws at load. Reach a no-`'use server'` utility through a `'use server'` action, `route.ts`, or `middleware`, never by direct import into a shipping page or component.
+
+### Public env vars use `WEBJS_PUBLIC_`, not `NEXT_PUBLIC_`
+
+`process.env.X` is server-only. To expose a value to the browser, prefix it `WEBJS_PUBLIC_` (inlined via an inline `<script>`, no build step). `NODE_ENV` is defined both sides. Reading a non-public server env var in a component is flagged by `no-server-env-in-components` (it would leak into SSR'd HTML or read as undefined after hydration).
+
+---
+
+## Coming from Lit
+
+The disagreement underneath: Lit is JS-first (hydration is the API), WebJs is HTML-first (first paint is real HTML, JS is opt-in per interactive behaviour). JS is requested by the specific interactive holes you write: a `@click`, a `signal.set(...)`, a `.data=${richObject}` property binding, a `Task`. A plain `<a href>`, a `<form action>`, and a display-only component request no JS. The SSR contract: the pipeline runs the constructor, applies attributes, runs `willUpdate` and controllers' `hostUpdate`, reflects `reflect: true` props, then calls `render()`. Nothing past render fires server-side (not `connectedCallback`, `firstUpdated`, `updated`).
+
+### Fetching in `connectedCallback` or `firstUpdated`
+
+Neither hook runs server-side, so the first paint is empty and content pops in after hydration with a layout shift. Fetch in the page function and pass the data down as props or attributes.
+
+```ts
+// app/users/[id]/page.ts (correct)
+export default async function User({ params }) {
+  const user = await fetchUser(params.id); // via a *.server.ts query
+  return html`<user-card .user=${user}></user-card>`;
+}
+```
+
+### `Task` for initial-paint data
+
+`Task` deliberately does not auto-run at SSR: it keeps its `INITIAL` state and runs only on hydration, so the client renders the resolved state after a flash. `Task` stays right for client-time async (interaction-triggered mutations, polling, websocket reactions). For initial-paint data, fetch in the page function, or use an async `render()` (which Lit does not have): write `const u = await getUser(this.id)` directly in the component and SSR bakes the resolved data into the first paint. A bare async `render()` blocks SSR and renders real data with no fallback. To STREAM slow data wrap the region in `<webjs-suspense .fallback=${html`...`}>`. `renderFallback()` is the OPTIONAL client re-fetch UI, never a first-paint concern.
+
+### Browser globals in the constructor or `render()`
+
+`window.matchMedia`, `localStorage`, `navigator`, `document.querySelector`, and layout reads crash SSR (the instance has no DOM). The constructor is for pure-JS init. Browser APIs belong in `connectedCallback` or later (client-only by construction). Flagged by `no-browser-globals-in-render`.
+
+```ts
+// wrong
+constructor() { super(); this.dark = window.matchMedia('(prefers-color-scheme: dark)').matches; }
+// right
+constructor() { super(); this.dark = false; }
+connectedCallback() {
+  super.connectedCallback();
+  this.dark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+}
+```
+
+The attribute methods (`getAttribute` / `setAttribute` / `hasAttribute`), the event methods, and `attachInternals()` ARE backed by a server shim, so reading an attribute in `render()` is safe. Only the genuinely DOM-backed members (`classList`, `querySelector`, `attachShadow`, `getBoundingClientRect`, `focus`) throw.
+
+### Top-level imports of browser-only libraries
+
+`import Chart from 'chart.js'` or any library that touches `window` at import time crashes SSR, because the page module loads on the server. Use a dynamic `import()` inside `connectedCallback` for client-only behaviour, or wrap server work in a `.server.ts` file.
+
+```ts
+connectedCallback() {
+  super.connectedCallback();
+  import('chart.js').then(({ Chart }) => { this.chart = new Chart(this.canvas, this.config); });
+}
+```
+
+### Class-field initializers for reactive properties
+
+A class-field initializer (`student: Student = { ... }`) compiles to an assignment after `super()` that uses `[[Define]]` and overwrites the reactive accessor the base class installed, silently breaking reactivity. Declare the prop in the factory and set its default in the constructor after `super()`. Flagged by `reactive-props-no-class-field`.
+
+```ts
+class StudentCard extends WebComponent({ student: prop<Student>(Object) }) {
+  constructor() { super(); this.student = { name: '', email: '' }; }
+}
+```
+
+### The `@property()` decorator and a `static properties` block
+
+The `@property()` decorator is banned by the erasable-TS invariant (decorators are non-erasable, they would force a build step). A `static properties = { ... }` block THROWS at runtime (`no-static-properties`). The single replacement for both is the declare-free base-class factory `WebComponent({ ... })`, with the `prop()` helper carrying options.
+
+### Expecting shadow DOM and reaching for scoped CSS
+
+Lit defaults to shadow DOM, so `static styles = css` scopes automatically. WebJs defaults to light DOM. A `static styles` block without `static shadow = true` does nothing useful and any inline `<style>` with bare class names leaks globally. The webjs-shaped fix is Tailwind utilities, which apply directly in light DOM. Reach for `static shadow = true` plus `static styles` only when scoped CSS genuinely belongs in a shadow root, or prefix every selector with the tag name if authoring vanilla light-DOM CSS.
+
+### `:host { display: block }` on a light-DOM component
+
+A custom element is `display: inline` by default, so a block container collapses. In Lit you fix this with `:host { display: block }`, which works because Lit is shadow-DOM-first. A light-DOM WebJs component has no shadow root, so there is no `:host` to write. There is nothing to do: the framework already defaults every light-DOM host to `display: block` via a low-priority `@layer webjs-host` rule, overridable by any Tailwind utility (`class="flex"` wins). A shadow-DOM component (`static shadow = true`) still sets `:host { display: block }` in `static styles` itself, exactly like Lit.
+
+### Interpolating into a `<style>` or `<script>` inside a component
+
+In Lit a binding inside `<style>` works. In a WebJs component it fails silently after hydration: the server emits the interpolated content (first paint looks right), but the client drops the raw-text hole and rebuilds the element EMPTY, so the styles vanish. Use `static styles` (shadow) or Tailwind (light DOM). A fully static `<style>` with no `${}` is fine. Flagged by `no-interpolation-in-raw-text-element`. Note the exception: pages and layouts never hydrate, so a page's `<style>${STYLES}</style>` is a legitimate pattern.
+
+### Reordering a `.map()` list needs a keyed `repeat()`
+
+A plain `.map()` list reconciles in place and preserves node identity on item-level updates (drag-and-drop, focus, caret, and input state all survive), so it is fine for append-only or update-in-place lists. What it does NOT do is keyed reordering: reconciliation is positional, so on a middle insert or a reorder the nodes stay put and their contents are rewritten. When a list reorders or splices in the middle and each item owns DOM state that must move with it, use `repeat(items, (i) => i.id, template)` from `@webjsdev/core/directives`, exactly as in Lit.
+
+### `ContextProvider` for server-known data
+
+Context providers publish on connect via `hostConnected`, which does not run at SSR, so descendants read the default (or undefined) during SSR and re-render on hydration with a content shift. For server-known data (session, user, theme, locale, feature flags), pass it through props from the page function. Reserve `ContextProvider` for client-time concerns (interaction state, focus management, transient UI).
+
+### Vanilla DOM instead of Lit idioms
+
+WebJs components are Lit-shaped on purpose: the value is the declarative DX. Prefer a factory-declared reactive prop over `this.getAttribute`, a `signal` over a `state: true` prop for internal state, a `class=${...}` binding over `this.classList`, a `@click=${...}` binding over `this.addEventListener`, and `C.register('x')` over `customElements.define`. Vanilla DOM stays right only where the platform offers nothing declarative: `this.closest('ui-tabs')` for compound-component ancestor lookup (resolves at SSR too), slotted-content queries, global `document` / `window` listeners, and imperative `el.focus()`. This is a convention, not a lint rule.

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

@@ -0,0 +1,128 @@
+# Optimistic UI
+
+## What This Covers
+
+- The declarative `optimistic(host, { source, update })` API (preferred) with `.add(payload, promise)` auto-release
+- The imperative `optimistic(signal, value, action)` API for simple boolean flips
+- When optimistic UI is appropriate, and when to skip it
+- Why you never hand-roll try-catch, cache-and-restore, or temp-ID reconciliation
+
+Read this when a mutation should feel instant, when the client can predict the result of a create/update/delete/like/toggle/reorder before the server confirms it. Sibling refs: `data-and-actions.md` (the server actions and the `ActionResult` envelope these calls invoke), `components.md` (the `WebComponent` host, reactive props, and signals these APIs attach to).
+
+## The Idea
+
+`optimistic()` from `@webjsdev/core` shows a mutation's expected result IMMEDIATELY (the UI feels instant), runs the real server action, and ROLLS BACK automatically on failure. It is the default for every user-facing mutation where the client can construct the expected result from the input. **Never write manual try-catch, cache-and-restore, or temp-ID reconciliation** when `optimistic()` covers the pattern.
+
+## Declarative API (preferred)
+
+`optimistic(host, { source, update })` returns an `OptimisticState<State, Action>` with a `.value` getter and an `.add(payload, promise?)` method. The `source` reads the authoritative state (usually a reactive prop). The `update` reducer transforms that state with each payload. Calling `.add()` pushes an update and schedules a re-render, so `.value` reflects the optimistic state on the next paint.
+
+```ts
+import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+import { createTodo } from '#modules/todos/actions/create-todo.server.ts';
+
+class TodoList extends WebComponent({
+  todos: prop<Todo[]>(Array),
+}) {
+  private optimisticTodos = optimistic(this, {
+    source: () => this.todos,
+    update: (state, title: string) => [
+      ...state,
+      // A client-only placeholder id for the pending row; the real id arrives
+      // from the server on reconcile, so the `as any` cast on this temp row is
+      // fine (the row is dropped when the promise settles).
+      { id: crypto.randomUUID() as any, title, completed: false, pending: true },
+    ],
+  });
+
+  async handleSubmit(e: SubmitEvent) {
+    e.preventDefault();
+    const title = new FormData(e.target as HTMLFormElement).get('title') as string;
+    if (!title) return;
+    (e.target as HTMLFormElement).reset();
+
+    const promise = createTodo({ title });
+    this.optimisticTodos.add(title, promise);
+
+    const result = await promise;
+    if (result.success && result.data) {
+      // Reconcile: the optimistic entry has ALREADY auto-released (the promise
+      // settled), so `this.todos` holds only confirmed rows here. Append the
+      // server's canonical row, matching the order the `update` reducer used.
+      this.todos = [...this.todos, result.data];
+    }
+  }
+
+  render() {
+    return html`<ul>${this.optimisticTodos.value.map(todo => html`
+      <li class=${todo.pending ? 'opacity-50' : ''}>${todo.title}</li>
+    `)}</ul>`;
+  }
+}
+TodoList.register('todo-list');
+```
+
+**Auto-release is the whole point.** Pass the action's promise as the second argument to `.add(payload, promise)`, and the update auto-releases the moment that promise settles (resolve OR reject). It uses `.finally()`, with a `.then()` fallback for thenables that lack `.finally`. No try-catch, no manual rollback, no temp-ID bookkeeping. On success you reconcile the authoritative row from `result.data` (as above); on failure the optimistic entry simply drops when the promise rejects.
+
+- 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.
+
+## 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.
+
+```ts
+// app/notes/page.ts (runs server-only; awaits the data so it is in the first paint)
+import { html } from '@webjsdev/core';
+import '#modules/notes/components/note-composer.ts'; // registers <note-composer>
+import { listNotes } from '#modules/notes/queries/list-notes.server.ts';
+
+export default async function NotesPage() {
+  const notes = await listNotes();
+  // .notes=${notes} seeds the component; the list SSRs through the component.
+  return html`<note-composer .notes=${notes}></note-composer>`;
+}
+```
+
+The component reads that seeded prop as its `optimistic()` `source`, so `source: () => this.notes` is both the SSR list and the base for optimistic additions.
+
+## Imperative API (simple boolean flips)
+
+For a boolean toggle where the value itself is the mutation (like, follow, pin), `optimistic(signal, value, action)` is a thin wrapper over the signal primitive.
+
+```ts
+import { signal, optimistic } from '@webjsdev/core';
+import { likePost } from '#modules/posts/actions/like-post.server.ts';
+
+const liked = signal(false);
+// in an @click handler:
+const result = await optimistic(liked, true, () => likePost(postId));
+// `liked` flips to true instantly. If likePost THROWS or returns
+// { success: false }, `liked` rolls back to its prior value: the throw
+// re-throws, and the { success: false } result is returned so you can
+// read its error / fieldErrors. On success the optimistic value stays;
+// reconcile to the authoritative value from `result` if you need it.
+```
+
+It rolls back on a thrown error OR an `ActionResult` `{ success: false }` envelope, and never on success. It is client-only (it mutates a signal), so a component importing it is never elided as a display-only component.
+
+## When Optimistic UI Is Appropriate
+
+- Todo items, comments, posts, likes, follows, toggles, reorders, renames, status changes.
+- Any mutation where the client can construct the expected result from the input.
+- CRUD operations where the server returns the same shape the client already has.
+
+## When To Skip It
+
+- The result is unpredictable (AI-generated content, server-computed values the client cannot guess).
+- The mutation has side effects the user must wait for (payment processing, email sending, OAuth).
+- The action validates against data that may have changed server-side (unique constraints, race conditions).
+- The mutation is destructive and irreversible with no undo (confirm-first UX is better).
+
+## Rules
+
+1. Default to `optimistic()` for every predictable user-facing mutation. Instant UI, automatic rollback.
+2. Prefer the declarative `.add(payload, promise)` form for list mutations. Pass the promise so release is automatic.
+3. Use the imperative `optimistic(signal, value, action)` form only for a boolean flip whose value is the mutation.
+4. Never hand-roll try-catch, cache-and-restore, or temp-ID reconciliation when one of these APIs covers the pattern.
+5. Reconcile the authoritative result from the returned `ActionResult` after the promise settles when you need the server's canonical row.

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

@@ -0,0 +1,158 @@
+# Routing and Pages
+
+## What This Covers
+
+- 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)
+- 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
+
+Read this when a task touches the route contract, a URL, a `<head>` tag, a redirect, a 404, or a form POST that a page owns. Sibling refs: `components.md` (anything interactive), `data-and-actions.md` (server actions, queries, validation, the `ActionResult` envelope), `auth-and-sessions.md` (`forbidden()` / `unauthorized()` flows).
+
+## The Execution Model (read this first)
+
+Pages and layouts 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, a signal read in a page body never re-renders). They still LOAD in the browser so imported components register. Put every interactive behaviour in a component.
+
+`route.ts` is the one routing file that is NOT isomorphic: a server-only HTTP handler, never shipped to the client.
+
+## Pages (`app/**/page.ts`)
+
+The default export is a possibly-async function receiving `{ params, searchParams, url, actionData }`. It returns a `TemplateResult`; it never calls `render()` itself.
+
+```ts
+// app/about/page.ts
+import { html } from '@webjsdev/core';
+export default function About() {
+  return html`<h1>About</h1>`;
+}
+```
+
+`params` and `searchParams` are awaitable AND synchronously readable (`params.id` and `await params` both work, Next.js 15/16 parity). Throw `notFound()` or `redirect(url)` to short-circuit. Reach data through a `.server.ts` query; never import the DB driver into a page.
+
+Optional named exports: `metadata` / `generateMetadata` (below), `export const revalidate` (seconds, opts into the HTML response cache, only for a page identical for every visitor), and `export const action` (the write path, below).
+
+## Layouts (`app/**/layout.ts`)
+
+The default export receives `{ children, params, searchParams, url }` and must embed `children`. Layouts nest by folder; `metadata` merges with the deepest winning.
+
+```ts
+// app/layout.ts (root)
+import { html } from '@webjsdev/core';
+export default function RootLayout({ children }: { children: unknown }) {
+  return html`<html lang="en"><head></head><body>${children}</body></html>`;
+}
+```
+
+Only the **root layout** (`app/layout.ts` exactly) MAY write `<!doctype>` / `<html>` / `<head>` / `<body>`; the framework splices in the importmap, modulepreload, title, and meta. Non-root layouts and pages MUST NOT write the shell (the `shell-in-non-root-layout` rule). If the root layout omits the shell, the framework auto-emits `<!doctype><html lang="en"><head></head><body>`.
+
+## Dynamic and catch-all routes
+
+```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); // via a server query, never the DB directly
+  return html`<h1>${user.name}</h1>`;
+}
+```
+
+- `[param]/page.ts` dynamic segment, read via `params.param`.
+- `[...rest]/page.ts` catch-all, `[[...rest]]/page.ts` optional catch-all.
+- `(group)/...` route group: the folder is NOT in the URL but still scopes layout / error.
+- `_private/...` private folder: ignored by the router.
+
+## Route handlers (`app/**/route.ts`)
+
+Named async exports per HTTP method, each `(Request, { params }) => Response | value` (a non-Response value auto-JSONs). A folder cannot have both `page.ts` and `route.ts`.
+
+```ts
+// app/api/health/route.ts
+export async function GET() {
+  return { ok: true };
+}
+```
+
+**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.
+
+## 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.
+
+## 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.
+
+```ts
+import type { Metadata, MetadataContext } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Home', description: 'Welcome' };
+
+export async function generateMetadata(ctx: MetadataContext): Promise<Metadata> {
+  return { title: `Post: ${ctx.params.slug}`, metadataBase: new URL(ctx.url).origin };
+}
+```
+
+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.
+
+## Control-flow throws
+
+From `@webjsdev/core`: throw to short-circuit a page / layout render or a page `action`.
+
+- `notFound()` renders the nearest `not-found.ts` (nearest wins from the throwing chain).
+- `redirect(url[, status])`. The no-status default is convention-picked at the catch site: `302` for a GET page render, `307` (method-preserving) for a page action. Override with `redirect(url, 308)` or `redirect(url, { status })`.
+- `forbidden()` renders the nearest `forbidden.ts` (authenticated user lacking permission); `unauthorized()` renders the nearest `unauthorized.ts` (request not authenticated).
+
+None of these belong in a `route.ts` (return a `Response` there). Inside a `'use server'` RPC action, return an `ActionResult` for an auth failure rather than throwing (`data-and-actions.md`).
+
+## The no-JS write path (a page `action`)
+
+A `page.ts` may export an `action` beside its default render function. A non-GET/HEAD submission to the page's own URL runs it, wrapped in the page's segment middleware. It works with JS off; with JS on the client router applies the response in place.
+
+```ts
+// app/contact/page.ts
+import { html } from '@webjsdev/core';
+import { sendMessage } from '#modules/contact/actions/send-message.server.ts';
+
+export async function action({ formData }: { formData: FormData }) {
+  const email = String(formData.get('email') || '').trim();
+  const body = String(formData.get('body') || '').trim();
+  const values = { email, body };
+  const fieldErrors: Record<string, string> = {};
+  if (!email.includes('@')) fieldErrors.email = 'Enter a valid email';
+  if (body.length < 10) fieldErrors.body = 'Message is too short';
+  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors, values, status: 422 };
+  await sendMessage({ email, body });
+  return { success: true, redirect: '/contact/thanks' };
+}
+
+export default function Contact({ actionData }: {
+  actionData?: { fieldErrors?: Record<string, string>; values?: Record<string, string> };
+}) {
+  const errors = actionData?.fieldErrors || {};
+  const values = actionData?.values || {};
+  return html`
+    <form method="POST" class="flex flex-col gap-3">
+      <input name="email" type="email" value=${values.email || ''} required>
+      ${errors.email ? html`<p class="text-sm text-red-600">${errors.email}</p>` : ''}
+      <textarea name="body" required>${values.body || ''}</textarea>
+      ${errors.body ? html`<p class="text-sm text-red-600">${errors.body}</p>` : ''}
+      <button type="submit">Send</button>
+    </form>
+  `;
+}
+```
+
+How the result is read (server side): a success PRG-redirects with `303` (to a same-site `redirect` path if present, else the page's own URL); a failure re-SSRs the SAME page with `status` (default `422`) and the result on `ctx.actionData`. Failure is detected robustly (`success === false`, OR `fieldErrors` present, OR `error` present with `success !== true`), so an error is never swallowed. `result.redirect` must be a same-site local path (a single leading `/`); for a real external redirect, throw `redirect(absoluteUrl)` instead. On a plain GET render `actionData` is `undefined`. Prefer a `<form>` + page action over `fetch` in a `@click` for any write a form can express.
+
+## Error, loading, and 404 boundaries
+
+- `error.ts` default-exports `({ error, ...ctx }) => TemplateResult`; catches sibling-page and deeper render errors, innermost wins (prod sends only `error.message`).
+- `loading.ts` wraps the sibling page in `Suspense` with an immediately-flushed fallback.
+- `not-found.ts` / `forbidden.ts` / `unauthorized.ts` render the nearest matching boundary for the thrown control-flow signal.
+- 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.

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

@@ -0,0 +1,80 @@
+# Runtime: Node and Bun
+
+## What This Covers
+
+- Running a WebJs app on **Node 24+** or **Bun**, and why the app source you write is identical on either.
+- The three things that actually differ under the hood (the listener shell, the TypeScript stripper, a handful of built-ins), and the one feature gap (103 Early Hints on Bun).
+- Scaffolding a Bun-flavored app and the `bun --bun run dev` / `start` commands.
+- Where Deno fits (planned, not yet supported).
+
+Read this when you are choosing a runtime, deploying, debugging a runtime-specific difference, or a scaffold emitted `bun.lock` and you want to know what changed. For the TypeScript stripping mechanics see `typescript.md`. For SQLite, caching, and other built-ins see `built-ins.md`. For the cross-runtime test matrix see `testing.md`.
+
+## The app source is identical
+
+There is nothing runtime-specific in the app you write. The same `app/`, `modules/`, `components/`, and `db/` files run byte-for-byte on Node and Bun, and the bytes the browser fetches are identical either way. WebJs picks the runtime shell at boot through a runtime-neutral seam inside its server (`node:http` on Node, `Bun.serve` on Bun), so nothing in your code branches on the runtime.
+
+Pick a runtime from the deploy target, not the code. Default to Node unless you specifically want Bun's faster listener or a Bun-native deploy image. You do not import a runtime adapter, set a flag in your pages, or handle Node and Bun differently anywhere in application code. The one place the runtime is chosen is the scaffold (`--runtime`) plus the run command (`bun --bun` versus `npm`), covered below.
+
+### Where the difference actually lives
+
+Three seams pick a runtime-specific implementation, all inside the framework, none in your app:
+
+- **The listener.** `startServer` selects the `node:http` request shell on Node and a native `Bun.serve` shell on Bun. Both parse the request, run middleware, dispatch to your routes, and stream the response through the same downstream pipeline, so an SSR page, a server action RPC, and a route handler behave identically.
+- **The type stripper.** WebJs serves `.ts` / `.tsx` as ES modules by erasing the types in place with no bundler. On Node that is the built-in `module.stripTypeScriptTypes`; on Bun it is `amaro` (the same engine, byte-identical and position-preserving so stack traces still point at the right line). Either way your TypeScript must be erasable (see `typescript.md`).
+- **A few built-ins.** SQLite, hot reload, and WebSockets each bind to the runtime's native primitive (see the table).
+
+## Node vs Bun at a glance
+
+| Area | Node 24+ | Bun |
+|---|---|---|
+| Install | `npm install` | `bun install` |
+| Run | `npm run dev` / `npm run start` | `bun run dev` / `bun run start` |
+| Listener | `node:http` shell | native `Bun.serve` (faster on the listening path only, not end-to-end, because SSR render dominates a real page) |
+| TS strip | built-in `module.stripTypeScriptTypes` | `amaro` (byte-identical, position-preserving) |
+| SQLite | built-in `node:sqlite` + `drizzle-orm/node-sqlite` | built-in `bun:sqlite` + `drizzle-orm/bun-sqlite` |
+| 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) |
+
+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.
+
+## 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):
+
+```sh
+webjs create my-app --runtime bun
+```
+
+`--runtime` is orthogonal to `--template`, so it re-flavors any of full-stack, saas, or api. A Bun scaffold emits a `bun.lock`, a pure `oven/bun:1` Dockerfile plus a bun-install CI, and bun-command agent docs. The test, db, and check tooling still runs on Node.
+
+## Running on Bun
+
+A Bun app installs with `bun install` like Node, then its `dev` / `start` / `db` scripts force `bun --bun` so the server itself runs on Bun:
+
+```sh
+bun install
+bun run dev      # or: bun run start
+```
+
+`bun --bun` overrides the `webjs` bin's Node shebang so the server runs on Bun, selecting the native `Bun.serve` listener and `amaro` type stripping. The app's dependencies resolve from `node_modules` exactly as on Node. The `start.before` migrate step (`webjs db migrate`) runs under Bun too. Commit the `bun.lock` for reproducible, offline installs. The scaffold's Bun Dockerfile runs `bun install` and serves via `CMD ["bun", "--bun", "run", "start"]`.
+
+## Deploying either runtime
+
+Production runs `npm run start` (Node) or `bun run start` (Bun), which serves the source directly with no build step. Both speak plain HTTP/1.1, so put a reverse proxy or platform edge in front for TLS and HTTP/2 (production perf leans on HTTP/2 multiplexing plus `modulepreload` hints, not a bundle). A `start.before` migrate runs first on both runtimes.
+
+The scaffold ships a matching Dockerfile per runtime: a Node image for the default, a pure `oven/bun:1` image for `--runtime bun`. Commit the lockfile the runtime uses (`package-lock.json` for Node, `bun.lock` for Bun) so the deploy install is reproducible and offline.
+
+## SQLite busy_timeout
+
+Both `node:sqlite` and `bun:sqlite` default `busy_timeout` to 0, so a contended write throws `database is locked` immediately. The generated connection sets `PRAGMA busy_timeout = 5000` plus `PRAGMA journal_mode = WAL` on the raw client before Drizzle wraps it, on both runtime branches, so you get a sane 5-second wait instead of an instant failure. This is already wired in the scaffold's `db/connection.server.ts`.
+
+## Verifying a runtime-sensitive change
+
+Most app code needs no runtime-specific testing, because it does not touch a runtime seam. If you DO change something runtime-sensitive (the serializer, a stream, `node:crypto`, low-level request handling, anything that behaves differently under `Bun.serve` versus `node:http`), prove it on both runtimes. The Node suite is the source of truth, and an additive Bun matrix re-runs the runtime-sensitive tests under Bun. See `testing.md` for the cross-runtime matrix and the `test/bun/**` assertions.
+
+For an ordinary feature (a page, an action, a component) a single-runtime test is enough, since the source is identical on either runtime.
+
+## Future runtimes
+
+The listener seam is runtime-neutral, so a `Deno.serve` shell (or an embedded adapter) slots in at the same point when added. Edge runtimes with no filesystem are a separate, later target. Until then, treat Deno as planned, not supported, and build on Node or Bun.

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

@@ -0,0 +1,78 @@
+# Service Worker (offline, opt-in)
+
+## What This Covers
+
+- The opt-in progressive-enhancement service worker that UI scaffolds ship dormant (`public/sw.js` plus `public/offline.html`).
+- Why it is progressive-enhancement-safe: the worker registers only from JS, so the JavaScript-disabled baseline is unchanged.
+- How to enable it (the registration snippet in the root layout), what it caches, and the offline fallback.
+- Cache versioning tied to the deploy, updating the worker, and removing it.
+
+Read this when you want an offline experience or an asset cache in a WebJs app, or you see `public/sw.js` in a scaffold and want to know what it does. For CSP nonces see `built-ins.md`. For the root layout see `routing-and-pages.md`. For the content-hash `?v=` asset URLs it relies on see `built-ins.md`.
+
+## What ships and why it is safe
+
+WebJs's UI scaffolds (full-stack and saas, not the api template) ship a hand-authored service worker at `public/sw.js` and an offline fallback at `public/offline.html`. Both ship **dormant**: they do nothing until the app registers the worker, and the worker only ever registers from JavaScript. So with JS off no worker exists, and pages, links, and forms behave exactly as before. It is opt-in and adds an offline experience plus an asset cache without changing the no-JS baseline.
+
+This is a thin, hand-readable worker built directly on the native Service Worker and Cache Storage APIs. There is no Workbox, no precache framework, and no bundler step, matching WebJs's no-build, close-to-web-standards posture. The file is yours to edit, not a framework internal.
+
+## Enabling it
+
+Add this inline script to the root layout's `<head>` (`app/layout.ts`). It registers after load and only when JS is present, so it stays progressive-enhancement-safe:
+
+```html
+<script>
+  if ('serviceWorker' in navigator) {
+    addEventListener('load', () => {
+      // Tie the worker version to the deploy: read the importmap build id and
+      // register /sw.js?v=<build>, so a new deploy registers a "new" worker.
+      const tag = document.querySelector('script[type="importmap"]');
+      const build = (tag && tag.dataset.webjsBuild) || '';
+      navigator.serviceWorker.register('/sw.js' + (build ? '?v=' + build : ''));
+    });
+  }
+</script>
+```
+
+With WebJs's CSP enabled (`webjs.csp` in package.json), stamp the nonce on the script. Read it in the layout with `import { cspNonce } from '@webjsdev/core'` and emit `<script nonce="${cspNonce()}">...`.
+
+## Scope and caching strategy
+
+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.
+
+**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.
+
+## The offline fallback page
+
+`public/offline.html` is a plain, self-contained HTML page the worker serves only when a navigation fails and no cached copy of that URL exists. Treat it as the app's offline chrome and edit it to match the app's branding. It ships as a minimal placeholder in the scaffold. Because it renders with no network and no module system, keep it static: no component tags, no importmap dependency, inline any styles it needs.
+
+## Versioning ties to the deploy
+
+The cache name is `webjs-<build>`, where `<build>` is the `?v=` query the registration passes (the importmap build id from `data-webjs-build`). When a deploy changes the build id:
+
+1. the page registers `/sw.js?v=<new-build>`, a different worker URL, so the browser fetches and installs the new worker;
+2. the new worker's `activate` deletes every cache whose name is not the current `webjs-<new-build>`, evicting the prior deploy's cache.
+
+So a deploy refreshes the offline cache automatically, with no manual cache busting. Without a `?v=` (a dev registration, say), the cache name is `webjs-dev`.
+
+## Updating the worker
+
+The browser re-checks `/sw.js` on navigation and replaces the worker when its bytes change. Because the registration URL carries the build id, a deploy always changes that URL and triggers the update. The worker calls `skipWaiting()` plus `clients.claim()`, so a new version takes control promptly. To change the caching strategy, edit `public/sw.js`.
+
+## Removing it
+
+Delete the registration snippet (and optionally `public/sw.js` and `public/offline.html`). To also un-register an already-installed worker on clients, ship this for one release:
+
+```js
+navigator.serviceWorker.getRegistrations().then(rs => rs.forEach(r => r.unregister()));
+```
+
+Or rely on the worker's own update lifecycle to phase it out.
+
+## Verifying it
+
+After adding the registration snippet, load the app, then open the browser devtools Application panel and confirm a worker is registered and activated for the origin. To exercise the offline path, visit a page (so it caches), then toggle offline in devtools and reload: a previously visited page should serve from cache, and an unvisited URL should render `public/offline.html`. Confirm the JS-off baseline is unchanged by disabling JavaScript and checking that no worker registers and navigation still works as a plain server-rendered app.
+
+Do not register the worker until the offline experience is something you actually want, because a registered worker keeps serving cached shells to returning visitors until its cache is evicted by a new deploy build id.