@webjsdev/cli 0.10.50 → 0.10.52

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 };
-}

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

@@ -1,4 +1,5 @@
 import { html } from '@webjsdev/core';
+import type { LayoutProps } from '@webjsdev/core';
 import { buttonClass } from '#components/ui/button.ts';
 
 // Nested layout for the protected dashboard subtree. Logout is a plain
@@ -7,7 +8,7 @@ import { buttonClass } from '#components/ui/button.ts';
 // default). signOut is server-only (modules/auth/auth.server.ts), so we POST to
 // its route rather than import it into a browser-shipping page. After signout the
 // dashboard middleware bounces any later visit to login.
-export default function DashboardLayout({ children }: { children: unknown }) {
+export default function DashboardLayout({ children }: LayoutProps) {
   return html`
     <nav class="flex items-center gap-4 mb-6 pb-4 border-b border-border">
       <a href="/features/auth/dashboard" class="text-sm font-medium text-foreground hover:underline">Dashboard</a>

package/templates/gallery/app/features/auth/signup/page.ts

@@ -8,28 +8,6 @@ export const metadata = { title: 'Sign up' };
 
 const inputCls = inputClass();
 
-// Page server action: handles the POST from the form below. With JS disabled this
-// is a plain <form> round-trip; with JS the client router swaps the 422 re-render
-// (errors) or follows the 302 (success) in place. A validation failure returns
-// fieldErrors + values so the page re-renders with messages and the user's typed
-// input preserved.
-export async function action({ formData }: { formData: FormData }) {
-  const name = String(formData.get('name') || '').trim();
-  const email = String(formData.get('email') || '').trim();
-  const password = String(formData.get('password') || '');
-  const values = { name, email };
-  const fieldErrors: Record<string, string> = {};
-  if (!name) fieldErrors.name = 'Name is required';
-  if (!email.includes('@')) fieldErrors.email = 'Enter a valid email';
-  if (password.length < 8) fieldErrors.password = 'At least 8 characters';
-  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors, values, status: 422 };
-  const result = await signup({ name, email, password });
-  // On success signup returns signIn's 302 Response (auto-login -> dashboard); a
-  // page action may return a Response, so pass it straight through.
-  if (result instanceof Response) return result;
-  return { success: false, fieldErrors: { email: result.error }, values, status: result.status };
-}
-
 export default function SignupPage({ actionData }: { actionData?: { fieldErrors?: Record<string, string>; values?: Record<string, string> } }) {
   const errors = actionData?.fieldErrors || {};
   const values = actionData?.values || {};
@@ -37,7 +15,10 @@ export default function SignupPage({ actionData }: { actionData?: { fieldErrors?
     <div class="max-w-[420px] mx-auto">
       <h1 class="text-h2 font-bold mb-2">Create an account</h1>
       <p class="text-muted-foreground mb-5">Get started with your new workspace.</p>
-      <form method="POST" class="${cardClass()} grid gap-4 p-5">
+      <!-- The form is bound to the action: no adapter, no fetch handler. With JS
+           disabled this is a plain round-trip; with JS the client router swaps
+           the 422 re-render (errors) or follows the 302 (success) in place. -->
+      <form action=${signup} class="${cardClass()} grid gap-4 p-5">
         <div class="grid gap-1.5">
           <label for="name" class="text-[13px] font-medium text-muted-foreground">Name</label>
           <input id="name" name="name" type="text" value=${values.name || ''} required class=${inputCls} placeholder="Ada Lovelace" />

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

@@ -1,9 +1,9 @@
 // Caching: `export const revalidate = N` opts the page into the server HTML
-// response cache, keyed by URL for N seconds. The rendered timestamp below only
-// changes once per window: reload inside 10s and it is identical, reload after
-// and it refreshes. SAFETY: only cache a page that is identical for every
-// visitor (no cookies(), no session, no per-user data), since the key is the URL
-// alone. For per-query reads use cache() + tags with revalidateTag; for a
+// response cache, keyed by the request origin plus the URL for N seconds. The
+// rendered timestamp below only changes once per window: reload inside 10s and
+// it is identical, reload after and it refreshes. SAFETY: only cache a page that
+// is identical for every visitor (no cookies(), no session, no per-user data),
+// since the key carries no per-user component. For per-query reads use cache() + tags with revalidateTag; for a
 // public/ asset use asset(), demonstrated at the bottom of this page.
 import { html, asset } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
@@ -23,7 +23,7 @@ export default function CachingExample() {
     ${pageHeading('Caching')}
     ${lede(html`
       This page sets <code>export const revalidate = 10</code>, so its
-      server-rendered HTML is cached per URL for ten seconds.
+      server-rendered HTML is cached per origin and URL for ten seconds.
     `)}
     <p class="mb-4">
       Rendered at

package/templates/gallery/app/features/file-storage/page.ts

@@ -1,9 +1,10 @@
-// File storage: a no-JS upload. A multipart <form> posts to this page's `action`
-// (the progressive-enhancement write path); the action calls a 'use server'
-// helper that streams the bytes into the FileStore. On success it redirects
-// (PRG) with the new key in the query, and the page renders a download link that
-// streams the file back through file/[key]/route.ts. Works with JS off; the
-// client router applies the same flow in place with JS on.
+// File storage: a no-JS upload. A <form> bound to a 'use server' action streams
+// the bytes into the FileStore (the progressive-enhancement write path). The
+// framework emits the multipart enctype an upload needs, so the binding is the
+// whole wiring. On success the action redirects (PRG) with the new key in the
+// query, and the page renders a download link that streams the file back
+// through file/[key]/route.ts. Works with JS off; the client router applies the
+// same flow in place with JS on.
 import { html } from '@webjsdev/core';
 import { buttonClass } from '#components/ui/button.ts';
 import { cardClass } from '#components/ui/card.ts';
@@ -13,18 +14,6 @@ import { storeUpload } from '#modules/file-storage/actions/store-upload.server.t
 
 export const metadata: Metadata = { title: 'File storage (upload + serve) | features' };
 
-export async function action({ formData }: { formData: FormData }) {
-  const file = formData.get('file');
-  if (!(file instanceof File) || file.size === 0) {
-    return { success: false, error: 'Choose a file to upload.' };
-  }
-  const result = await storeUpload(file);
-  if (!result.success) return result;
-  const { key, name, size } = result.data;
-  const q = new URLSearchParams({ key, name, size: String(size) });
-  return { success: true, redirect: '/features/file-storage?' + q.toString() };
-}
-
 export default function FileStorageExample({
   searchParams,
   actionData,
@@ -43,7 +32,7 @@ export default function FileStorageExample({
       gitignored). Swap the backend for S3/R2 with one
       <code class="font-mono">setFileStore()</code> call, no call-site change.
     `)}
-    <form method="post" enctype="multipart/form-data" class="flex flex-wrap gap-3 items-center mb-4">
+    <form action=${storeUpload} class="flex flex-wrap gap-3 items-center mb-4">
       <input type="file" name="file" required aria-label="Choose a file to upload"
         class="text-sm text-muted-foreground file:mr-3 file:px-3.5 file:py-2 file:rounded-xl file:border-0 file:bg-card file:border file:border-border file:text-foreground file:text-sm file:cursor-pointer" />
       <button type="submit"

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

@@ -1,11 +1,14 @@
-// forms: the no-JS write path. A real <form method="post"> posts to this page's
-// `action` export, and the framework re-renders the SAME page with the result on
-// `actionData`. WHY it matters: the form works with JS OFF (server round-trip),
-// and with JS the client router applies the response in place (no full reload).
-// Never reach for fetch() + a click handler where a <form> + page action does.
-// On failure the framework re-renders at 422 with the result; on success it
-// does a 303 Post-Redirect-Get, so we redirect to ?sent=1 to show a confirmation.
+// forms: the no-JS write path. Bind a server action straight into the form with
+// `action=${sendMessage}` and that is the whole wiring: the framework posts to
+// this page's own url, runs the action, and re-renders the SAME page with the
+// result on `actionData`. WHY it matters: the form works with JS OFF (a plain
+// server round-trip), and with JS the client router applies the response in
+// place (no full reload). Never reach for fetch() + a click handler where a
+// bound <form> does. On failure the framework re-renders at 422 with the
+// result; on success it does a 303 Post-Redirect-Get, so we redirect to ?sent=1
+// to show a confirmation.
 import { html } from '@webjsdev/core';
+import { sendMessage, type Result } from '#modules/forms/actions/send-message.server.ts';
 import { cardClass } from '#components/ui/card.ts';
 import { inputClass } from '#components/ui/input.ts';
 import { buttonClass } from '#components/ui/button.ts';
@@ -14,13 +17,6 @@ import type { Metadata } from '@webjsdev/core';
 
 export const metadata: Metadata = { title: 'Forms (no-JS PE) | features' };
 
-interface Result {
-  success: boolean;
-  fieldErrors?: Record<string, string>;
-  values?: Record<string, string>;
-  redirect?: string;
-}
-
 const field = (label: string, name: string, input: unknown, error?: string) => html`
   <div class="grid gap-1.5">
     <label for=${name} class="text-[13px] font-medium text-muted-foreground">${label}</label>
@@ -48,8 +44,8 @@ export default function FormsFeature({ searchParams, actionData }: { searchParam
   const v = actionData?.values ?? {};
   return html`
     <h1 class="text-h2 font-bold mb-2">Forms</h1>
-    <p class="text-muted-foreground mb-5 max-w-[460px]">A real <code>&lt;form&gt;</code> posting to this page's <code>action</code>. It works with JS off; validation errors come back on <code>actionData</code>.</p>
-    <form method="post" action="" class="${cardClass()} max-w-[460px] grid gap-4 p-5">
+    <p class="text-muted-foreground mb-5 max-w-[460px]">A real <code>&lt;form&gt;</code> bound to a server action. It works with JS off; validation errors come back on <code>actionData</code>.</p>
+    <form action=${sendMessage} class="${cardClass()} max-w-[460px] grid gap-4 p-5">
       ${field('Name', 'name', html`<input id="name" name="name" value=${v.name ?? ''} class=${inputCls} placeholder="Ada Lovelace" />`, errs.name)}
       ${field('Email', 'email', html`<input id="email" name="email" type="email" value=${v.email ?? ''} class=${inputCls} placeholder="ada@example.com" />`, errs.email)}
       ${field('Message', 'message', html`<textarea id="message" name="message" rows="3" class=${inputCls} placeholder="Say hello...">${v.message ?? ''}</textarea>`, errs.message)}
@@ -57,25 +53,3 @@ export default function FormsFeature({ searchParams, actionData }: { searchParam
     </form>
   `;
 }
-
-// The page action runs on a non-GET submission to this URL (the no-JS write
-// path). Validate, then return a failure (re-renders at 422 with fieldErrors +
-// values) or a success with a same-site `redirect` (a 303 PRG to the confirmation).
-//
-// FOOTGUN: to redirect on success, RETURN `{ success: true, redirect: '/path' }`
-// (a 303 See Other, so the browser follows with a GET). Do NOT THROW `redirect()`
-// from a page action, that is a 307 which PRESERVES the POST method and body, so
-// the browser re-POSTs to the target and re-runs the mutation (a duplicate write).
-// Throw `redirect()` only from a page render / GET context, never a page action.
-export async function action({ formData }: { formData: FormData }): Promise<Result> {
-  const name = String(formData.get('name') ?? '').trim();
-  const email = String(formData.get('email') ?? '').trim();
-  const message = String(formData.get('message') ?? '').trim();
-  const fieldErrors: Record<string, string> = {};
-  if (!name) fieldErrors.name = 'Your name is required.';
-  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) fieldErrors.email = 'A valid email is required.';
-  if (message.length < 5) fieldErrors.message = 'Message must be at least 5 characters.';
-  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors, values: { name, email, message } };
-  // A real app would persist / email here. We just confirm.
-  return { success: true, redirect: '/features/forms?sent=1' };
-}

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

@@ -1,4 +1,5 @@
 import { html } from '@webjsdev/core';
+import type { LayoutProps } from '@webjsdev/core';
 import { backLink } from '#lib/utils/ui.ts';
 import '#modules/gallery/components/gallery-nav.ts';
 
@@ -45,8 +46,11 @@ const STACK_CSS = `
 // sidebar is hidden, so a slim back link keeps a demo from being a dead end.
 // Nested layouts (like the auth dashboard's sub-nav) render inside ${children}.
 // A non-root layout, so it never writes the document shell (the framework does).
-export default function FeaturesLayout({ children, url }: { children: unknown; url: URL | string }) {
-  const path = typeof url === 'string' ? new URL(url, 'http://x').pathname : url.pathname;
+// LayoutProps types every argument a layout receives, so `url` is known to be
+// an absolute URL string (the framework passes url.toString()) and needs no
+// defensive widening or runtime typeof check.
+export default function FeaturesLayout({ children, url }: LayoutProps) {
+  const path = new URL(url).pathname;
   return html`
     <style>${SIDENAV_CSS}${STACK_CSS}</style>
     <div class="lg:hidden mb-6">${backLink('/', html`&larr; Gallery`)}</div>

package/templates/gallery/app/features/route-handler/data/route.ts

@@ -24,7 +24,8 @@ export async function GET(req: Request) {
     // not a cookie, so do not read it here.
     cookieCount: cookies().entries().length,
     // cspNonce() reads the request's CSP nonce ('' with CSP off). Server-side
-    // you use it to nonce a server-rendered inline <script>/<style> under CSP.
+    // you use it to nonce a server-rendered inline <script> under CSP (a <style>
+    // only needs it if you tighten style-src, which by default allows inline).
     hasNonce: cspNonce().length > 0,
   });
 }

package/templates/gallery/app/features/view-transitions/page.ts

@@ -22,7 +22,7 @@ export default function ViewTransitionsExample() {
     ${pageHeading('View transitions')}
     <div class="rounded-2xl bg-primary/10 border border-primary/30 p-6 mb-6">
       <p class="text-foreground m-0">Page one. Navigate to page two: with the
-        <code class="font-mono">&lt;meta name="view-transition"&gt;</code> opt-in,
+        <code class="font-mono">&lt;meta name="view-transition" content="same-origin"&gt;</code> opt-in,
         the swap cross-fades.</p>
     </div>
     <label class="block mb-6">

package/templates/gallery/app/global-error.ts

@@ -5,8 +5,9 @@
 // returned verbatim with NO framework <head> splice, so it ships no importmap
 // and no boot script. Keep it static HTML with no components or hydration: a
 // last-resort page must not depend on the module system that may have just
-// failed. (Under an opt-in CSP, any inline <style>/<script> here needs a nonce
-// via cspNonce() from @webjsdev/server.)
+// failed. (Under an opt-in CSP, an inline <script> here needs a nonce via
+// cspNonce() from @webjsdev/core. An inline <style> only needs one if you
+// tighten style-src, since the default policy allows inline style outright.)
 //
 // Distinct from error.ts (a nested, per-segment boundary that renders a body
 // fragment the framework wraps) and from global-not-found.ts (the unmatched-URL
@@ -17,8 +18,10 @@ export default function GlobalError({ error }: { error: Error }) {
   const message = process.env.NODE_ENV === 'production'
     ? 'Something went wrong. Please try again.'
     : error?.message || 'Unknown error';
-  // cspNonce() is '' with CSP off (the default), so this is safe as-is; under an
-  // opt-in CSP it carries the per-request nonce so the inline <style> is allowed.
+  // cspNonce() is '' with CSP off (the default), so this is safe as-is. Under the
+  // default opt-in policy the inline <style> is allowed by 'unsafe-inline' rather
+  // than by this nonce, which is stamped so the page still works if you tighten
+  // style-src to a nonce source.
   return html`<!doctype html>
     <html lang="en">
       <head>

package/templates/gallery/modules/async-render/components/server-clock.ts

@@ -16,8 +16,9 @@ export class ServerClock extends WebComponent {
   // serves it with ZERO JavaScript and skips the redundant on-hydration
   // re-fetch. This is the common fetch-and-display leaf shape. If you ever need
   // to force a component to ship when the analyser would elide it (for
-  // interactivity static analysis cannot see, like a dynamically-computed tag
-  // string), declare `static interactive = true`.
+  // interactivity static analysis cannot see, like an observer that computes
+  // the tag it waits for), declare `static interactive = true`. Run
+  // `webjs elision` to see the verdict for every component in this app.
   async render() {
     const info = await serverGreeting();
     return html`<p class="font-mono text-sm">server rendered this at

package/templates/gallery/modules/auth/actions/signup.server.ts

@@ -5,15 +5,31 @@ import { users } from '#db/schema.server.ts';
 import { hash } from '../password.server.ts';
 import { signIn } from '../auth.server.ts';
 
-// Creates the account, then signs the new user in and lands on the dashboard.
-// signIn returns a 302 Response carrying the session cookie; the signup page
-// action returns that Response as-is (a page action may return a Response).
-// signIn lives in the server-only auth module, imported here server-to-server,
-// so it never reaches the browser (the signup page only imports this action's
-// RPC stub).
-export async function signup(input: { name: string; email: string; password: string }) {
-  const exists = await db.query.users.findFirst({ where: { email: input.email }, columns: { id: true } });
-  if (exists) return { success: false as const, error: 'Email already registered', status: 409 };
-  await db.insert(users).values({ name: input.name, email: input.email, passwordHash: await hash(input.password) });
-  return signIn('credentials', { email: input.email, password: input.password }, { redirectTo: '/features/auth/dashboard' });
+// The action the signup <form> is bound to. It takes the FormData directly:
+// that is what a form-bound action always receives, on the JS path and the
+// no-JS path alike, so validation lives HERE rather than in a per-page adapter.
+//
+// A validation failure returns fieldErrors + values, which re-renders the SAME
+// page at 422 with the messages and the user's typed input preserved. On
+// success it signs the new user in: signIn returns a 302 Response carrying the
+// session cookie, and an action may return a Response, which the framework
+// honors verbatim. signIn lives in the server-only auth module, imported here
+// server-to-server, so it never reaches the browser.
+export async function signup(formData: FormData) {
+  const name = String(formData.get('name') || '').trim();
+  const email = String(formData.get('email') || '').trim();
+  const password = String(formData.get('password') || '');
+  const values = { name, email };
+  const fieldErrors: Record<string, string> = {};
+  if (!name) fieldErrors.name = 'Name is required';
+  if (!email.includes('@')) fieldErrors.email = 'Enter a valid email';
+  if (password.length < 8) fieldErrors.password = 'At least 8 characters';
+  if (Object.keys(fieldErrors).length) return { success: false as const, fieldErrors, values, status: 422 };
+
+  const exists = await db.query.users.findFirst({ where: { email }, columns: { id: true } });
+  if (exists) {
+    return { success: false as const, fieldErrors: { email: 'Email already registered' }, values, status: 409 };
+  }
+  await db.insert(users).values({ name, email, passwordHash: await hash(password) });
+  return signIn('credentials', { email, password }, { redirectTo: '/features/auth/dashboard' });
 }