@webjsdev/cli 0.10.50 → 0.10.51

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

@@ -17,6 +17,8 @@ Read this when a mutation should feel instant, when the client can predict the r
 
 `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.
 
+**The reducer must be pure.** `.value` re-folds the whole queue on every read, so `update` runs again on each render rather than once per `.add()`. Anything it MINTS is therefore minted per render. Mint a temp id in the handler and pass it in the payload. A `crypto.randomUUID()` inside the reducer gives the pending row a different id on every read, which breaks a keyed list and anything else treating that id as stable.
+
 ```ts
 import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
 import { createTodo } from '#modules/todos/actions/create-todo.server.ts';
@@ -26,12 +28,18 @@ class TodoList extends WebComponent({
 }) {
   private optimisticTodos = optimistic(this, {
     source: () => this.todos,
-    update: (state, title: string) => [
+    // KEEP THIS REDUCER PURE. `.value` re-folds every queued update on EVERY
+    // read, not once per `.add()`, so anything minted in here is minted again
+    // on each render. A `crypto.randomUUID()` here would hand the pending row
+    // a NEW id per render, and a keyed list (`repeat(todos, t => t.id, ...)`)
+    // would tear the row down and rebuild it every update, losing focus, any
+    // in-progress transition, and DOM state. Mint the temp id in the handler
+    // and carry it in the payload, so it is stable for the life of the row.
+    update: (state, add: { tempId: string; 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 },
+      // `createdAt` is rebuilt per read too. That is tolerable only because
+      // nothing keys on it; put it in the payload as well if anything does.
+      { id: add.tempId, title: add.title, completed: false, createdAt: new Date(), pending: true },
     ],
   });
 
@@ -41,14 +49,22 @@ class TodoList extends WebComponent({
     if (!title) return;
     (e.target as HTMLFormElement).reset();
 
+    // Minted ONCE here, not in the reducer. `Todo['id']` is a string (a uuid
+    // primary key), so no cast is needed. Against an auto-increment integer
+    // id there is no honest client-side value, so model the temp row instead
+    // (an optional id, or a `tempId` the row keys on) rather than casting.
+    const tempId = crypto.randomUUID();
     const promise = createTodo({ title });
-    this.optimisticTodos.add(title, promise);
+    this.optimisticTodos.add({ tempId, 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.
+      // Reconcile: the optimistic row is never written to `this.todos`. The
+      // overlay holds only the PAYLOAD, and `update` rebuilds the row from it
+      // on each `.value` read, so this prop holds only confirmed rows. Append
+      // the server's canonical row, matching the order the `update` reducer
+      // used. (The overlay entry auto-released when the promise settled, so
+      // `.value` does not double-count it on the next paint.)
       this.todos = [...this.todos, result.data];
     }
   }
@@ -62,20 +78,23 @@ class TodoList extends WebComponent({
 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.
+**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 reconciling a temp id against the real one. The handler mints a temp id for the pending row, but nothing tracks it afterwards: the overlay drops whole when the promise settles, and the authoritative row arrives from `result.data`. 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.
 
 ### 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.
+Wrap the mutation in a REAL `<form>` bound to the action, then intercept it for the optimistic path. One form serves both: with JS off the browser submits and the server dispatches to that 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.
+
+The SAME imported function is the form binding and the optimistic path's callee, which is what makes a degrade-first form cheap to write: there is no second wiring to keep in step.
 
 ```ts
+import { createTodo } from '#modules/todo/actions/create-todo.server.ts';
+
 render() {
   return html`
-    <form method="post" action="" @submit=${this.handleSubmit}>
-      <input type="hidden" name="intent" value="create">   <!-- one page action dispatches on intent -->
+    <form action=${createTodo} @submit=${this.handleSubmit}>
       <input name="title" required>
       <button>Add</button>
     </form>
@@ -83,7 +102,9 @@ render() {
 }
 ```
 
-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.
+`method` and the enctype are supplied by the renderer, and the hidden identity field is re-inserted as the form's first child on every client render, so there is nothing to manage by hand.
+
+When a page owns SEVERAL mutations (create, toggle, delete), give each form its OWN binding (`action=${createTodo}` / `action=${toggleTodo}` / `action=${deleteTodo}`), or use per-button submitter server action bindings via `formaction=${action}` on submitter buttons inside a bound form (#1207). Alternatively, a form that dispatches dynamically can bind ONE action and inspect a submit button's `name="intent"`.
 
 ## Seed the list from the server for SSR plus optimistic
 

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

@@ -7,7 +7,7 @@
 - `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
+- The no-JS write path: a `<form>` bound to a `'use server'` action
 - 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).
@@ -32,7 +32,7 @@ export default function About() {
 
 `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).
+Optional named exports: `metadata` / `generateMetadata` (below) and `export const revalidate` (seconds, opts into the HTML response cache, only for a page identical for every visitor). There is no `action` export; the write path is a form bound to a `'use server'` action (below).
 
 ## Layouts (`app/**/layout.ts`)
 
@@ -41,7 +41,8 @@ The default export receives `{ children, params, searchParams, url }` and must e
 ```ts
 // app/layout.ts (root)
 import { html } from '@webjsdev/core';
-export default function RootLayout({ children }: { children: unknown }) {
+import type { LayoutProps } from '@webjsdev/core';
+export default function RootLayout({ children }: LayoutProps) {
   return html`<html lang="en"><head></head><body>${children}</body></html>`;
 }
 ```
@@ -114,24 +115,26 @@ Common fields: `title` (string or `{ template, default, absolute }`), `descripti
 
 ## Control-flow throws
 
-From `@webjsdev/core`: throw to short-circuit a page / layout render or a page `action`.
+From `@webjsdev/core`: throw to short-circuit a page / layout render or a form-bound 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 })`.
+- `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 form-bound 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`)
+## The no-JS write path (a form-bound 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.
+A page imports a `'use server'` action and binds it into the form: `<form action=${sendMessage}>`. There is no page `action` export; the binding IS the wiring. The renderer omits the `action` attribute (so the form posts to the page's own url), supplies `method="post"` and an enctype, and emits a hidden `__webjs_action` field carrying the action's `<hash>/<fn>` identity. A non-GET/HEAD submission carrying that identity runs the action, wrapped in the segment middleware of the URL it was submitted to AND the action's own declared `middleware`. It works with JS off; with JS on the client router posts the same body to the same url and 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';
+**Do not treat the page's segment middleware as the action's authorization gate.** An identity names the action, not the page that rendered it, so the same action is reachable by submitting to any page path (and, being a `'use server'` export, at its RPC endpoint too, where no segment middleware runs at all). That is the same reachability every server action has always had, and the removed page `action` export was the one shape where the URL really did scope the handler. Authorize the action itself: an `export const middleware = [requireAdmin]` on the action, or a check in its body, both of which run on either transport.
 
-export async function action({ formData }: { formData: FormData }) {
+A form-bound action always receives the `FormData` as its first argument, which is where it differs from the same action called over RPC. `validate` is the typing seam: it receives that `FormData`, and its transform-return becomes the action's typed input.
+
+```ts
+// modules/contact/actions/send-message.server.ts
+'use server';
+export async function sendMessage(formData: FormData) {
   const email = String(formData.get('email') || '').trim();
   const body = String(formData.get('body') || '').trim();
   const values = { email, body };
@@ -139,9 +142,15 @@ export async function action({ formData }: { formData: FormData }) {
   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 });
+  await deliver({ email, body });
   return { success: true, redirect: '/contact/thanks' };
 }
+```
+
+```ts
+// app/contact/page.ts
+import { html } from '@webjsdev/core';
+import { sendMessage } from '#modules/contact/actions/send-message.server.ts';
 
 export default function Contact({ actionData }: {
   actionData?: { fieldErrors?: Record<string, string>; values?: Record<string, string> };
@@ -149,7 +158,7 @@ export default function Contact({ actionData }: {
   const errors = actionData?.fieldErrors || {};
   const values = actionData?.values || {};
   return html`
-    <form method="POST" class="flex flex-col gap-3">
+    <form action=${sendMessage} 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>
@@ -160,7 +169,17 @@ export default function Contact({ actionData }: {
 }
 ```
 
-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.
+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 bound `<form>` over `fetch` in a `@click` for any write a form can express.
+
+Three responses that are not the happy path:
+
+- **A submission carrying no identity is a `405` + `Allow: GET, HEAD`.** A bare `<form method="post">` binds nothing, and the page path exists but only renders, so the method is what is wrong rather than the url.
+- **An identity whose hash no longer resolves re-renders at `422`** with a resubmit message and the submitted values on `actionData`. That is a form held open across a deploy; a 404 would discard what was typed and a silent no-op would show success for a write that never happened.
+- **A bound action declaring `export const method = 'GET'` is a `405`.** A GET action rides its args in the url and is CSRF-exempt, so it cannot answer a form POST. `webjs check`'s `form-action-not-a-get-action` catches it at edit time.
+
+The submission is Origin-verified (the same `Sec-Fetch-Site` / `Origin` check the RPC endpoint applies), so a no-JS form needs no CSRF token field.
+
+Refusals worth knowing: `formaction=${fn}` is supported only on a `<button>` inside a bound form, and that button may not carry `name`, `value`, `form`, or a static `formaction` attribute (`<input type="submit">` is refused, because the identity needs its `value`, which is also its label). A bound form may not declare `method="get"`, and a function bound to `action=` that is not a `'use server'` export throws at render rather than producing a form that posts nowhere. See `muscle-memory-gotchas.md` for the full table.
 
 ## Error, loading, and 404 boundaries
 

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

@@ -41,7 +41,11 @@ The 103 Early Hints gap costs only a small first-load latency edge where an edge
 
 Behind a TLS-terminating proxy (Railway, Fly, Render, Cloudflare, nginx), both shells rewrite the request URL from `X-Forwarded-Proto` / `X-Forwarded-Host`, so `ctx.url` in a page, `req.url` in a `route.{js,ts}` handler, and every absolute URL you build from either carry the ORIGINAL scheme and host rather than the internal `http://container` hop. A comma-separated chain (a CDN in front of a load balancer) takes the value closest to the client, only `http` and `https` are accepted as a scheme, and a malformed host is ignored rather than failing the request. This was Bun-only broken before #1090, which shipped an `http://` `og:image` on an HTTPS site.
 
-Two limits worth knowing. `WEBJS_NO_TRUST_PROXY=1` stops the URL rewrite (and the HSTS scheme check) from trusting the headers when the container is directly exposed, but it is not a global switch: the CSRF host check still reads `X-Forwarded-Host` regardless. And this rewrite belongs to `startServer`. An app embedded through `createRequestHandler` gets the `Request` its host adapter built, so that adapter owns the correction, the same boundary that already applies to the trusted client IP.
+`WEBJS_NO_TRUST_PROXY=1` is the global switch for "nothing trusted sits in front of this container, stop believing these headers". It is read in ONE place and is ABSOLUTE across every forwarded-header read: the URL rewrite, the HSTS scheme check, the CSRF host resolution, and `clientIp` (`x-forwarded-for` / `cf-connecting-ip` / `x-real-ip`) alike. So `rateLimit({ trustProxy: true })` is inert while the flag is set, falling back to the framework-stamped peer address (its default with no option) and warning once per process. The two CAN be set in contradiction, and the direction rule is what resolves it: the flag only ever SUBTRACTS trust and the per-call option can only add it, so the flag wins. Setting both is a misconfiguration that buckets every visitor behind the proxy onto one key, which is what the warning is for. It used to miss the CSRF host, which read `X-Forwarded-Host` regardless; that gap closed in #1104. Setting it on a genuinely proxied deploy is a misconfiguration, and it now shows up as one, since the legacy no-`Sec-Fetch-Site` CSRF fallback compares `Origin` against the raw `Host` and rejects a legitimate cross-host request. The primary `Sec-Fetch-Site` path, which nearly every real browser request takes, never consults the host at all and is unaffected either way.
+
+One limit worth knowing: the rewrite belongs to `startServer`. An app embedded through `createRequestHandler` gets the `Request` its host adapter built, so that adapter owns the correction, the same boundary that already applies to the trusted client IP.
+
+**Anything SHARED that you derive from `ctx.url` must be keyed by the origin.** Neither Cloudflare nor Railway strips a client-supplied `X-Forwarded-Host`, they forward it, so a hostile value reaches the container through the proxy rather than around it. That is fine for a per-request response (the attacker only poisons their own), and a real problem the moment a response is shared. WebJs handles the cache it owns: the server HTML response cache (`export const revalidate`) folds `url.origin` into every cache key (#1097), so a poisoned body is unreachable from any origin the attacker does not already control. Apply the same rule to anything you cache yourself off `ctx.url`, and note the rule reaches caches WebJs does not own either. A page served `Cache-Control: public` is stored by a CDN under the CDN's OWN key, which does not include `X-Forwarded-Host`, so keying the server cache cannot protect that copy. Derive nothing origin-dependent into a page you make publicly cacheable, or pin the origin from config rather than from `ctx.url`.
 
 ## Scaffolding a Bun app
 

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

@@ -70,7 +70,7 @@ Avoid `@apply`: it hides which utilities a class uses and creates a second sourc
 
 ### A design system for repeated PRIMITIVES: class helpers built on `@webjsdev/ui`
 
-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.
+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. Conflicts are keyed on the CSS PROPERTY wherever `cn` can tell the properties apart, rather than on the shared class prefix, so the common prefix collisions do NOT evict: `cn('border-2', 'border-primary')` keeps both (a width and a colour), `cn('flex', 'flex-1')` keeps both (a `display` and a `flex-grow`, the shape an element that is both a flex container and a flex child needs), and an arbitrary value carrying a type hint is read as the property the hint names (`cn('shadow-lg', 'shadow-[color:red]')` keeps both). It is a small hand-rolled merger, not `tailwind-merge`, so some prefixes are still grouped coarsely and a less common pair can collide (`bg-clip-text` against `bg-primary`, `shadow-lg` against `shadow-red-500`). When an override has to win and you are unsure, pass the one class rather than layering, or install `clsx` + `tailwind-merge` and replace the helper (its header comment shows the swap). 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  (npx webjsdev ui add button, themed to your app)

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

@@ -24,6 +24,35 @@ Feature folders are primary, and the test kind is a subfolder inside the feature
 
 Assert only on what the layer needs. A block that inspects only the HTTP response, the SSR HTML string, headers, or the importmap does NOT need a browser. Keep in the browser suite only blocks that genuinely need a DOM (live state via `page.evaluate`, hydration, client-router nav, slots, view transitions, streaming into the DOM, custom-element upgrade).
 
+### A browser test that clicks a real link or submits a real form MUST cancel the default
+
+web-test-runner aborts the whole SESSION, not one file, when the page navigates. So a test that clicks a real `<a href>` or submits a real `<form>` is a single point of failure for every browser test file you have: whenever the client router loses the race to intercept, the browser performs the real navigation and the run dies reporting `0 failed` and then exiting non-zero, which reads as an infrastructure blip rather than a test problem. Cancel the default so an interception gap fails ONE test on its own assertion.
+
+Register the canceling listener on `window` in the BUBBLE phase. That is the last step of the propagation path, so it runs after the router's own document-level listeners, and `preventDefault()` still cancels the default action because that action runs only once dispatch completes.
+
+**Never use the capture phase.** Capture sets `defaultPrevented` before the router ever sees the event, and the router returns immediately on that flag (the same guard that lets a component's `@click` opt out). Every guarded router test then passes while testing nothing. Capture is correct only when suppressing the router is the actual goal, for a test that exercises a menu or a drawer rather than navigation; say so in a comment when you do it, because it looks identical to the mistake. Do not reach for `stopPropagation` either, which hides the click from the router and turns the assertion into a tautology.
+
+Cancel a form on its `submit` event, not on the submit control's `click`. The form's default action fires on submit, so canceling the click stops the form from ever submitting and the router never sees it.
+
+Resolve the anchor from `e.composedPath()`, not `e.target.closest('a[href]')`. The listener is on `window`, so a click inside a shadow root (a `static shadow = true` component) arrives retargeted to the host, and `closest()` walks only light-tree ancestors and never finds the link, which fails open exactly where the router itself handles the case. A pure-fragment `href="#x"` link needs no guard at all, since it never navigates the page away.
+
+There is a SECOND channel a click guard cannot reach: the router assigns `location.href` when it degrades a soft navigation, and `preventDefault` does not cancel a script assignment. Do not try to intercept `location.href` itself, which is non-configurable on Chromium, Firefox, and WebKit alike, so its setter cannot be redefined on any of them. Listen for `webjs:navigation-fallback` on `document` and assert none fired; its `cause` is the diagnosis.
+
+It is a few lines, so write it in your suite's setup and detach it in teardown:
+
+```js
+const onClick = (e) => {
+  for (const el of e.composedPath()) {
+    if (el instanceof HTMLAnchorElement && el.hasAttribute('href')) { e.preventDefault(); return; }
+  }
+};
+const onSubmit = (e) => e.preventDefault();
+window.addEventListener('click', onClick);     // bubble, never capture
+window.addEventListener('submit', onSubmit);
+```
+
+(The WebJs framework repo keeps its own copy of exactly this in one shared module, `test/browser-nav-guard.js`, whose `installNavGuard()` returns `{ fallbacks, hardNavigations, remove }`. That module is framework-repo infrastructure and is not part of a scaffolded app.)
+
 ## App runners (`webjs test`)
 
 ```sh
@@ -48,11 +77,11 @@ test/
 
 ## The `handle()` harness (`@webjsdev/server/testing`)
 
-`createRequestHandler({ appDir }).handle(request)` drives the FULL request pipeline (middleware, routing, SSR, page actions, server-action RPC, auth, CSRF) and returns a native `Response`. It is the same entry the framework's own suite uses, so the most realistic way to test an app is to fire a `Request` through it and assert on the `Response`, with no spawned process and no network. `@webjsdev/server/testing` ships thin builders over that `handle()`, each a few lines over native `Request` / `Response` that reuse the REAL cookie names, header names, and wire serializer. For a browser test that needs to drive the app in a real DOM, `createBrowserTestHandler()` from `@webjsdev/server/testing` exposes the same `handle()` pipeline to the WTR Chromium session.
+`createRequestHandler({ appDir }).handle(request)` drives the FULL request pipeline (middleware, routing, SSR, form-dispatched actions, server-action RPC, auth, CSRF) and returns a native `Response`. It is the same entry the framework's own suite uses, so the most realistic way to test an app is to fire a `Request` through it and assert on the `Response`, with no spawned process and no network. `@webjsdev/server/testing` ships thin builders over that `handle()`, each a few lines over native `Request` / `Response` that reuse the REAL cookie names, header names, and wire serializer. For a browser test that needs to drive the app in a real DOM, `createBrowserTestHandler()` from `@webjsdev/server/testing` exposes the same `handle()` pipeline to the WTR Chromium session.
 
 ```js
 import { createRequestHandler } from '@webjsdev/server';
-import { testRequest, invokeActionForTest, rawActionRequest, loginAndGetCookies, withSessionCookie }
+import { testRequest, submitForm, invokeActionForTest, rawActionRequest, loginAndGetCookies, withSessionCookie }
   from '@webjsdev/server/testing';
 
 const app = await createRequestHandler({ appDir: process.cwd(), dev: true });
@@ -77,6 +106,28 @@ const dash = await testRequest(app.handle, '/dashboard', withSessionCookie({}, c
 assert.equal(dash.status, 200);
 ```
 
+### `submitForm`: the no-JS write path
+
+Use it for any page whose form binds an action (`<form action=${myAction}>`). A bound form carries a hidden `__webjs_action` field holding the action's identity, and that field is what tells the dispatcher which action to run, so a hand-written `POST` that omits it is not a form submission at all and is answered **405**. `submitForm` renders the page, reuses the identity the server put there, and posts it back, which is exactly what a browser with JS off does.
+
+```js
+import { submitForm } from '@webjsdev/server/testing';
+
+// success is a 303 PRG
+const ok = await submitForm(app.handle, '/signup', { name: 'Ada', email: 'ada@example.com', password: 'hunter2' });
+assert.equal(ok.status, 303);
+assert.equal(ok.headers.get('location'), '/dashboard');
+
+// a failure result re-renders the SAME page at 422 with the result on actionData
+const bad = await submitForm(app.handle, '/signup', { email: 'not-an-email' });
+assert.equal(bad.status, 422);
+assert.match(await bad.text(), /Enter a valid email/);
+```
+
+Options: `cookies` (submit as a logged-in user, paired with `loginAndGetCookies`), `match` (a string or RegExp the form's markup must contain, for a page with several forms), `index` (pick by position instead), `submitPath` (render one page, submit to another), and `headers`.
+
+Do not hand-roll the identity scrape. When it is wrong the symptom is a 405, an assertion fails, and a surrounding `catch` reports it as a database that was never migrated, so the test goes quiet rather than red.
+
 ### `invokeActionForTest`: round-trip an action through the REAL endpoint
 
 ```js
@@ -112,9 +163,16 @@ WebJs runs on Node 24+ or Bun. The Node suite is the source of truth; an additiv
 
 If your app targets Bun, Bun parity is part of the definition of done. A change to a runtime-sensitive surface (the serializer, the `node:http` vs `Bun.serve` listener and request path, SSR / action / CSRF dispatch, streams, `node:crypto`, the TS stripper, auth / session / cors) is NOT done until you also run your suite under the Bun runtime (needs `bun` installed) and add a cross-runtime assertion for the touched surface.
 
+### Writing a plain proof script that boots a server
+
+A cross-runtime proof is often a plain assert script rather than a test file, so the SAME file runs under `node script.mjs` and `bun script.mjs`. If it boots a real server through `startServer`, know what carries its verdict: the process EXIT CODE, since nothing is collecting results for you. WebJs makes that code trustworthy: a fatal shutdown, which is where a failed top-level assertion lands on both runtimes, exits 1, and so does a drain that rejects or is still hanging at the 10s deadline. The process exits 0 in one case only, an operator-requested stop that drained cleanly with no crash on the way out, so a proof script that finishes green really did finish green. Two habits keep it that way:
+
+- **Assert the exit code, never the logs.** These scripts conventionally pass a `quiet` logger, so anything that only logs is invisible. If your script catches its own failure, report it with an explicit `process.exit(1)` rather than a `console.error` alone, guarded as `if (import.meta.main) process.exit(1); else throw failure;`. The guard matters when a `.test.mjs` wrapper imports the script under `node --test`: an unguarded exit kills the whole single-process run and hides every other file's results, while the throw lets the harness report one failed test.
+- **Prove the script can FAIL before you trust it passing.** Break one assertion on purpose and confirm the run exits non-zero. A proof that cannot go red is worse than no proof: it reports success forever.
+
 ## Convention validation (`webjs check`)
 
-`npm run check` is the correctness validator. Every rule catches code that is wrong to ship (a crash, a security leak, a type-strip failure), plus the `no-scaffold-placeholder` sentinel for unreplaced scaffold content. Run it and fix every violation before considering the change done (`npm run check -- --json` for an agent loop, `npm run check -- --rules` to list the rules). It is separate from `CONVENTIONS.md`, which carries the customizable project conventions you follow by judgment.
+`npm run check` is the correctness validator. Every rule catches code that is wrong to ship, a crash, a security leak, a reactive prop that silently stops re-rendering, or a type-strip failure. Run it and fix every violation before considering the change done (`npm run check -- --json` for an agent loop, `npm run check -- --rules` to list the rules). It is separate from `CONVENTIONS.md`, which carries the customizable project conventions you follow by judgment.
 
 ## What NOT to do
 

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

@@ -5,8 +5,8 @@
 - TypeScript at runtime with **no build step**: `.ts` / `.mts` is stripped in place, not compiled.
 - **Erasable syntax only** (`erasableSyntaxOnly: true`) and the exact list of banned constructs, with their allowed rewrites.
 - The **pluggable stripper** (Node 24+ built-in vs `amaro` on Bun) and how the browser gets stripped source.
-- **Full-stack type safety**: server-action types flow to the call site, `import type` crosses the `.server` boundary, plus the carrier rule.
-- **Typing pages, layouts, and route handlers** with `PageProps` / `LayoutProps` / `RouteHandlerContext` and the generated route union (`webjs types`).
+- **Full-stack type safety**: the rule (derive the type at every boundary, never `unknown` / `any`), server-action types flowing to the call site, and the `import type` carrier rule across the `.server` boundary.
+- **Typing pages, layouts, and route handlers** with `PageProps` / `LayoutProps` / `RouteHandlerContext` and the generated route union (`npx webjsdev types`).
 
 Read this when you are writing `.ts` in a WebJs app, hit a strip-time 500, or want typed params and hrefs. For action signatures and the serializer wire see `data-and-actions.md`. For typing reactive props see `components.md`.
 
@@ -77,6 +77,75 @@ Prefer explicit `.ts` extensions in imports. A `.js` specifier pointing at a `.t
 
 ## Full-stack type safety
 
+### The rule: derive the type, never `unknown` or `any`
+
+Every value crossing an app boundary in WebJs already has a type you can reach, so reach for it. Writing `unknown` or `any` at a boundary throws away the framework's central guarantee, and it does so silently: the app still runs, the checker just stops helping. Nothing catches this for you. Both are valid TypeScript, so `webjs check` will not flag them (it is a correctness tool, and this is a convention), and `tsc --noEmit` passes happily.
+
+`unknown` is the more dangerous of the two, because it reads as the safe choice. It is safe only in the sense that it forces a narrow at the read site. As a boundary type it is exactly as uninformative as `any`, and it pushes a cast into every consumer.
+
+The ladder, in the order to climb it:
+
+| Boundary | Write this | Not this |
+|---|---|---|
+| A database row | `export type Todo = typeof todos.$inferSelect` in `db/schema.server.ts` (`$inferInsert` for a write) | a hand-written interface that drifts from the schema |
+| That row inside a shipping component | `import type { Todo } from '#db/schema.server.ts'` | `any[]`, or re-declaring the shape by hand |
+| A server action's input | a named `interface CreatePostInput` | `input: unknown` / `input: any` |
+| A server action's result | `Promise<ActionResult<Post>>` | `Promise<any>` |
+| `export const validate` | `(input: unknown)`, narrowed in the body, returning `data` that `satisfies` the action's input type | `(input: any)`, which un-types the returned `data` too |
+| A page | `PageProps<'/blog/[slug]'>` | `{ params: Record<string, any> }` |
+| A layout | `LayoutProps` (whose `children` is a `TemplateResult`) | `{ children: unknown }` |
+| A route handler's 2nd argument | `RouteHandlerContext<'/api/users/[id]'>` | `{ params: any }` |
+| A client-router href | the generated `Route` union (`npx webjsdev types`; `npm run dev` also emits it) | a bare `string` |
+| A reactive property | `prop<Student>(Object)`, `prop<Tag[]>(Array)` | `prop(Object)` plus a cast at every read |
+| An optimistic temp row | the pending shape on the row type (`pending?: boolean`) | `as any` on the temp id |
+
+One flow, end to end, with no escape hatch anywhere in it:
+
+```ts
+// db/schema.server.ts
+export const posts = table('posts', { id: uuidPk(), title: text().notNull(), body: text().notNull() });
+export type Post = typeof posts.$inferSelect;      // derived, never hand-written
+
+// modules/posts/actions/create-post.server.ts
+'use server';
+import type { Post } from '#db/schema.server.ts';  // type-only: erased before the browser sees it
+export interface CreatePostInput { title: string; body: string }
+export const validate = (input: unknown) => { /* narrows, returns data satisfying CreatePostInput */ };
+export async function createPost(input: CreatePostInput): Promise<ActionResult<Post>> { /* ... */ }
+
+// modules/posts/components/new-post.ts
+import { createPost } from '#modules/posts/actions/create-post.server.ts';
+const r = await createPost({ title, body });
+if (r.success && r.data) r.data.title;             // Post.title: string, checked at the call site
+```
+
+The payoff is not stylistic. A typo in `r.data.titel`, a renamed column, a changed action signature, and a page reading `params.slugg` are all compile errors in that version and all silent runtime `undefined` in the `unknown` version.
+
+### Where `unknown` is still the right type
+
+There are two cases, and only the first is about narrowing.
+
+**Case one: a value that genuinely has no type yet, at the moment before it is narrowed.**
+
+```ts
+// app/api/webhook/route.ts
+export async function POST(req: Request) {
+  const body: unknown = await req.json();   // correct: nothing has vouched for this yet
+  const parsed = parseWebhook(body);        // narrowed on the very next line
+  return Response.json({ ok: parsed.kind });
+}
+```
+
+The test is what the next line does. Correct `unknown` here is narrowed immediately by a parse, a validator, or a type guard, and the narrowed type is what the rest of the function sees. Anything standing at that boundary qualifies: a `route.ts` handler's `await req.json()` (above), a `catch (e)` binding (already `unknown` under `strict`), an action's `export const validate`, and any validator function those delegate to. In a validator, returning `data` that `satisfies` the action's input type is what carries a real type into the action body. See `data-and-actions.md`.
+
+**Case two: a parameter of YOUR OWN helper that forwards its argument into an `html` template hole, which is NOT narrowed.** A hole renders a string, a number, a `TemplateResult`, an array of those, a directive result, or nothing, so a helper like `lede(content: unknown)` is correctly typed and `TemplateResult` alone would be too narrow. Narrow it only when the helper genuinely accepts one shape (`backLink(href: string, ...)`).
+
+This case is about a value YOU accept, never one the framework hands you. A layout's `children` also ends up in a hole, but the framework already types it (`LayoutProps.children` is a `TemplateResult`), so `{ children: unknown }` is a discarded type, not this carve-out.
+
+Everywhere else `unknown` is a missing type, not a safe one: surviving into a return type, a component prop, a layout's `children`, or an action signature is the shape to fix.
+
+`any` gets no carve-out at all in app code. It does not defer checking, it disables it, so a validator typed `(input: any)` un-types everything downstream of the call.
+
 ### Server actions type-check automatically
 
 Calling a server action from a client component resolves at type-check time to the action's real source file. The runtime stub swap is invisible to the checker, and the RPC serializer makes runtime match the types (`Date` stays `Date`, `Map` stays `Map`, `BigInt` stays `BigInt`; see `data-and-actions.md` for the full supported set).

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

@@ -40,10 +40,13 @@ So the loop is: `add` the component, then query `ui <name>` (MCP) or
 
 ## Setup and resolution
 
-- `npx webjsdev ui init` writes `components.json`, `lib/utils.ts`, and the CSS design
+- `npx webjsdev ui init` writes `components.json`, `lib/utils/cn.ts`, and the CSS design
   tokens the helpers render against (`--background`, `--foreground`,
   `--destructive`, ...). It HARD-FAILS if the tokens cannot be written, so a
-  clean exit means the kit is styled. `add` self-heals the tokens if they go
+  clean exit means the kit is styled. Re-running it is safe on an existing
+  project: it keeps the aliases, stylesheet path, and base color already in
+  `components.json` and leaves an edited `cn.ts` / `dom.ts` alone, so it only
+  fills in what is missing (`--overwrite` resets them instead). `add` self-heals the tokens if they go
   missing.
 - Resolution is LOCAL-FIRST: `init` / `add` / `list` / `view` read the registry
   that ships inside the installed `@webjsdev/ui`, with no network. This pins you

package/templates/.github/pull_request_template.md

@@ -7,6 +7,7 @@
 - [ ] Unit tests added/updated (`webjs test` passes)
 - [ ] E2E tests added/updated for user-facing changes (`webjs test --e2e` passes)
 - [ ] `webjs check` passes (no convention violations)
+- [ ] `webjs doctor` passes (project health; it fails on whatever `webjs.doctor.gate` marks `error`, plus the hard `NODE_VERSION` / `TSCONFIG_ERASABLE` checks)
 
 ## Definition of done
 

package/templates/.github/workflows/ci.yml

@@ -34,6 +34,19 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run check
+      # Project health, on top of the correctness checks. WHICH findings are
+      # fatal is your call, declared in package.json under
+      # "webjs": { "doctor": { "gate": { "<CODE>": "off" | "warn" | "error" } } },
+      # so this step and a local `npm run doctor` always agree. The scaffold
+      # starts with UNMARKED_ASSET_LINKS at error (an un-versioned /public url
+      # is a real deploy-staleness bug). Two checks fail with no gate entry at
+      # all, NODE_VERSION and TSCONFIG_ERASABLE, because either would 500 the
+      # app at runtime; everything else stays a warn and cannot fail this job.
+      # Widen or narrow the gate in package.json, not
+      # here. Deliberately not --strict: the git-hook, env-drift, vendor-pin,
+      # and framework-resolve checks are environment-shaped and would fail a
+      # perfectly healthy runner.
+      - run: npm run doctor
 
   unit:
     name: Unit + integration (node --test)

package/templates/AGENTS.md

@@ -31,11 +31,37 @@ This is what separates a working app from a broken one.
 
 ## Type everything (all templates)
 
-Define explicit TypeScript interfaces and discriminated unions for your data
-payloads and action inputs and outputs (and, in a UI app, component props and
-optimistic updates). Narrow an `ActionResult` with
-`if (result.success && result.data)`. Never reach for `any` or a loose
-`as any` cast.
+Full-stack type safety is what the `.server.ts` boundary buys you: a client
+component importing a server action resolves to that action's real signature at
+type-check time, with no build step and no code generation in between. So
+DERIVE the type at every boundary instead of widening it:
+
+- A database row: `export type Todo = typeof todos.$inferSelect` in
+  `db/schema.server.ts` (`$inferInsert` for a write), carried into a
+  browser-shipped component with `import type` (erased before it reaches the
+  browser, so it does not trip the server-import boundary).
+- An action's input: a named `interface`. Its result: `ActionResult<T>`.
+  Narrow with `if (result.success && result.data)`.
+- Routing files: `PageProps<'/blog/[slug]'>`, `LayoutProps`,
+  `RouteHandlerContext`, all from `@webjsdev/core`. Run `npx webjsdev types`
+  for the typed `Route` union and per-route `params`.
+- A reactive property: `prop<Student>(Object)`, `prop<Tag[]>(Array)`.
+
+Never reach for `any` or a loose `as any` cast, and do not reach for `unknown`
+either just because it looks safer. `unknown` is right for a payload nothing
+has vouched for yet, narrowed on the very next line (a `route.ts` `await
+req.json()`, an action's `export const validate` or a validator it delegates
+to, a `catch` binding), and for a parameter of YOUR OWN helper that forwards
+into an `html` template hole (a hole renders a string, a number, a
+`TemplateResult`, or an array of those, so `TemplateResult` alone is too
+narrow). That second case is about a value you accept, never one the framework
+already types. Everywhere else it is a missing type, not a safe one: `unknown`
+that survives into a return type, a component prop, a layout's `children`, or
+an action signature is the shape to fix.
+Nothing enforces this (both are valid TypeScript, so `webjs check` and `tsc`
+pass either way), which is exactly why it is written down. The full ladder,
+with an end-to-end example, is in
+`.agents/skills/webjs/references/typescript.md`.
 
 Keep server-only code (database drivers, secrets, `node:*` builtins) in
 `.server.ts` modules. There are exactly two kinds:

package/templates/CONVENTIONS.md

@@ -24,8 +24,11 @@ is the short version.
   teaches the same and survives the clear), run `npm run gallery:clear` to shed
   the showcase, then grow the app in place. `AGENTS.md` has the full
   template-specific playbook.
+- **Derive types at every boundary.** Rows from `$inferSelect`, action inputs
+  from an `interface`, routing files from `PageProps` / `LayoutProps`. Never
+  `any`, and never `unknown` where a real type exists.
 - **Progressive enhancement is the default.** Pages render as HTML, `<a>`
-  navigates, `<form>` + a page action submits, all with JavaScript off; opt into
+  navigates, a `<form action=${importedAction}>` submits, all with JavaScript off; opt into
   interactivity per behaviour inside a component.
 - **Commit per logical unit** as soon as it is complete, and never push to `main`.
 

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

@@ -1,10 +1,11 @@
 import { html } from '@webjsdev/core';
+import type { LayoutProps } 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 }) {
+export default function ExamplesLayout({ children }: LayoutProps) {
   // 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`

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

@@ -1,14 +1,12 @@
 // A THIN route adapter: app/ is routing only. It fetches the initial data
 // (server-side) via the 'use server' query and renders the interactive
-// component, plus a page `action` for the no-JS write path. All the real logic
-// lives in modules/todo/. This is the idiomatic app-thin + modules-logic split.
+// component. All the real logic lives in modules/todo/, including the action
+// the component's forms bind to. 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';
-import { deleteTodo } from '#modules/todo/actions/delete-todo.server.ts';
 import '#modules/todo/components/todo-app.ts';
 
 export const metadata: Metadata = { title: 'Todo (optimistic UI) | examples' };
@@ -22,14 +20,3 @@ export default async function TodoExample() {
     <todo-app .todos=${todos}></todo-app>
   `;
 }
-
-// No-JS write path: the component's <form>s post here; with JS the component
-// intercepts and mutates optimistically instead. Success is a 303 PRG.
-export async function action({ formData }: { formData: FormData }) {
-  const intent = String(formData.get('intent') ?? '');
-  const id = String(formData.get('id') ?? '');
-  if (intent === 'create') return createTodo({ title: String(formData.get('title') ?? '') });
-  if (intent === 'toggle') return toggleTodo({ id });
-  if (intent === 'delete') return deleteTodo({ id });
-  return { success: false as const, error: 'Unknown action.', status: 400 };
-}