@webjsdev/cli 0.10.49 → 0.10.51

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,34 +1,22 @@
 // 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' };
 
 export default async function TodoExample() {
-  // SSR-fetched and seeded, so <todo-app> paints the real list on first byte.
+  // Fetched here on the server and handed down as a property, so <todo-app>
+  // paints the real list on the first byte with nothing to fetch on hydration.
   const todos = await listTodos();
   return html`
     ${pageHeading('Optimistic todo')}
     <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,11 +1,11 @@
 // 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 assets
-// use HTTP Cache-Control + ETag (conditional GET).
-import { html } from '@webjsdev/core';
+// 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';
 import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/caching/components/cache-buster.ts';
@@ -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
@@ -34,7 +34,9 @@ export default function CachingExample() {
       Only for pages identical for every visitor. For per-user or per-query data
       use <code>cache()</code> with <code>tags</code> and
       <code>revalidateTag</code>, or a GET action's
-      <code>export const cache</code>.
+      <code>export const cache</code>, which the
+      <a class="text-primary underline underline-offset-2" href="/features/server-actions">server actions card</a>
+      demonstrates end to end.
     </p>
     <p class="text-muted-foreground text-sm">
       A mutation evicts the cache on demand. Click below (it calls
@@ -44,5 +46,27 @@ export default function CachingExample() {
       copy until the window elapses.
     </p>
     <cache-buster></cache-buster>
+
+    <h2 class="mt-8 mb-2 font-semibold">Caching a public/ asset</h2>
+    <p class="mb-2">
+      A file in <code>public/</code> sits at a stable url, so after a deploy a
+      browser or CDN can keep serving the PREVIOUS bytes until its cache
+      expires. Wrap the url in <code>asset()</code> and it gains a content hash,
+      which the framework then serves <code>immutable</code> for a year:
+    </p>
+    <pre class="mb-2 overflow-x-auto rounded-md bg-muted p-3 text-sm"><code>&lt;link rel="stylesheet" href=\${asset('/public/tailwind.css')}&gt;</code></pre>
+    <p class="mb-2">
+      This app's stylesheet resolves to
+      <code class="font-mono text-primary">${asset('/public/tailwind.css')}</code>
+      (the hash appears in production only, so dev output stays byte-identical).
+      New bytes mean a new url, so a stale copy can never be served.
+    </p>
+    <p class="text-muted-foreground text-sm">
+      Mark the thing that FETCHES, not a hint. Wrapping a
+      <code>&lt;link rel="preload"&gt;</code> whose asset is really fetched by an
+      <code>@font-face url()</code> in your CSS would version the hint but not
+      the request, so the preload could never match and the file would download
+      twice.
+    </p>
   `;
 }

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/server-actions/page.ts

@@ -2,6 +2,7 @@ import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import { pageHeading, lede } from '#lib/utils/ui.ts';
 import '#modules/server-actions/components/greeter.ts';
+import '#modules/server-actions/components/clock-reader.ts';
 
 export const metadata: Metadata = { title: 'Server actions (.server vs use server) | features' };
 
@@ -20,5 +21,47 @@ export default function ServerActionsExample() {
     </p>
     <p class="text-muted-foreground mb-4 text-sm">Signed out, the greeter returns a real 401. <a class="text-primary underline underline-offset-2" href="/features/auth/login">Sign in</a> first to see it succeed. (This card depends on the auth card; prune both together.)</p>
     <server-greeter></server-greeter>
+
+    <h2 class="text-xl font-semibold mt-10 mb-3">HTTP verbs and caching</h2>
+    <p class="text-muted-foreground mb-4">
+      An action declares its HTTP semantics through reserved sibling exports the
+      framework reads statically, the same way a page declares
+      <code class="font-mono">export const revalidate</code>. The read below sets
+      <code class="font-mono">method = 'GET'</code>, so its args ride the URL, it is
+      CSRF-exempt, and it carries a weak ETag, so a revalidated read whose result has
+      not changed answers 304. Caching itself is opted into by the
+      <code class="font-mono">cache</code> export below, not by the verb: a GET without
+      one is <code class="font-mono">no-store</code>. An action with no
+      <code class="font-mono">method</code> export is a POST mutation. Seeding is a
+      separate mechanism and needs no verb: an action invoked during a fully
+      buffered SSR render has its result serialized into the page, so the first
+      client call reads that seed instead of making a hydration round-trip. A page
+      that streams (a <code class="font-mono">Suspense</code> or
+      <code class="font-mono">&lt;webjs-suspense&gt;</code> boundary) emits no seed
+      block, so its actions do call out on hydration.
+    </p>
+    <p class="text-muted-foreground mb-4">
+      <code class="font-mono">cache = 10</code> is the max-age in seconds, and it is
+      <strong class="text-foreground">private</strong> by default. Reach for
+      <code class="font-mono">{ public: true }</code> only when the data is identical
+      for every visitor, because a shared cache keys the entry on the URL and args
+      alone. That is the same safety rule as a page's
+      <code class="font-mono">export const revalidate</code>. The number is shorthand
+      for the object form, so
+      <code class="font-mono">cache = { maxAge: 10, swr: 30 }</code> keeps serving an
+      expired entry for another thirty seconds while the browser revalidates it in
+      the background. There is no separate <code class="font-mono">swr</code> export.
+    </p>
+    <p class="text-muted-foreground mb-4">
+      <code class="font-mono">tags</code> labels the cached entry and
+      <code class="font-mono">invalidates</code> on the mutation evicts it by name.
+      The read reports how many times it actually ran on the server, so press Read twice
+      inside ten seconds and that count does not move: the second answer came from the
+      browser cache without reaching the server. Then bump the counter and read again.
+      The count moves and the value is fresh, because the mutation reported its
+      invalidated tag and the next read bypassed the stale entry instead of waiting out
+      the window.
+    </p>
+    <clock-reader></clock-reader>
   `;
 }

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/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' });
 }

package/templates/gallery/modules/auth/queries/current-user.server.ts

@@ -2,11 +2,13 @@
 
 import { getCurrentUser } from '../auth.server.ts';
 
-// This read deliberately stays POST-default (no 'method' export). A GET server
-// action (a cacheable, SSR-seeded read) is wrong for a per-session lookup: the
-// result differs per user and changes on sign-in / sign-out, so it must never be
-// browser-cached or shared. Reserve GET + cache + tags for data identical for
-// every visitor.
+// This read deliberately stays POST-default (no 'method' export). A per-session
+// result differs per user and changes on sign-in / sign-out, so it must never
+// end up in a cache, and GET is the verb a `cache` window would later be added
+// to. Keeping it POST keeps that door shut. Reach for GET + cache + tags on a
+// read stable enough to serve twice, and for `{ public: true }` only when the
+// data is identical for every visitor. (Staying POST costs nothing on the first
+// paint, since SSR seeding applies to an action of any verb.)
 export async function currentUser() {
   return getCurrentUser();
 }

package/templates/gallery/modules/file-storage/actions/store-upload.server.ts

@@ -1,21 +1,32 @@
-// 'use server' so the page's action can call it (server-side, a direct call) and
-// it never crashes the browser module that imports it (the client gets a safe
-// RPC stub, not the node:fs code). getFileStore() is the pluggable storage
-// singleton: a local diskStore rooted at <cwd>/.webjs/uploads by default
-// (gitignored), swappable for S3/R2/GCS with one setFileStore() call at boot.
-// generateKey() mints a collision-free, traversal-safe key preserving a
-// whitelisted extension.
 'use server';
+
+// The directive comes FIRST, ahead of this header: the framework reads it from
+// the file's first few lines, so a long comment block above it would push it
+// out of range and the file would not register as an action at all.
+//
+// The action the upload <form> is bound to. 'use server' means it never
+// crashes the browser module that imports it (the client gets a safe RPC stub,
+// not the node:fs code). getFileStore() is the pluggable storage singleton: a
+// local diskStore rooted at <cwd>/.webjs/uploads by default (gitignored),
+// swappable for S3/R2/GCS with one setFileStore() call at boot. generateKey()
+// mints a collision-free, traversal-safe key preserving a whitelisted
+// extension.
+//
+// It takes the FormData, which is what a form-bound action always receives, and
+// pulls the File out of it. The framework emits the multipart enctype the
+// upload needs, so a bound form carries a file with no extra attribute.
 import { getFileStore, generateKey } from '@webjsdev/server';
 // Importing the config module runs setFileStore(diskStore(...)) once at load,
 // so uploads land in the configured store. See ../store.server.ts.
 import '../store.server.ts';
 
-export async function storeUpload(file: File) {
+export async function storeUpload(formData: FormData) {
+  const file = formData.get('file');
   if (!(file instanceof File) || file.size === 0) {
-    return { success: false as const, error: 'No file provided.' };
+    return { success: false as const, error: 'Choose a file to upload.' };
   }
   const key = generateKey(file.name);
   const { size, contentType } = await getFileStore().put(key, file, { contentType: file.type });
-  return { success: true as const, data: { key, name: file.name, size, contentType } };
+  const q = new URLSearchParams({ key, name: file.name, size: String(size) });
+  return { success: true as const, redirect: '/features/file-storage?' + q.toString(), data: { key, name: file.name, size, contentType } };
 }

package/templates/gallery/modules/forms/actions/send-message.server.ts

@@ -0,0 +1,34 @@
+'use server';
+
+// The action a <form action=${sendMessage}> submits to. It receives the
+// FormData directly: a form-bound action always does, on the JS path and the
+// no-JS path alike.
+//
+// Return a FAILURE to re-render the SAME page at 422 with the result on
+// `actionData` (so the fields repopulate), or a SUCCESS with a same-site
+// `redirect` for a 303 Post-Redirect-Get.
+//
+// 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 form 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.
+export interface Result {
+  success: boolean;
+  fieldErrors?: Record<string, string>;
+  values?: Record<string, string>;
+  redirect?: string;
+}
+
+export async function sendMessage(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/modules/gallery/nav.ts

@@ -27,9 +27,9 @@ export const FEATURE_GROUPS: NavGroup[] = [
   {
     label: 'Data & actions',
     items: [
-      { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, and why the boundary matters.' },
+      { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, plus the HTTP-verb config exports that make a read a cached GET.' },
       { href: '/features/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the WebJs equivalent of a Next route handler.' },
-      { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form posting to the page action, with server-side validation errors.' },
+      { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form bound to a server action, with server-side validation errors.' },
       { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'The imperative optimistic(signal, value, action) flip: instant update, automatic rollback on failure.' },
     ],
   },