@webjsdev/cli 0.10.50 → 0.10.51

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/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/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

@@ -29,7 +29,7 @@ export const FEATURE_GROUPS: NavGroup[] = [
     items: [
       { 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.' },
     ],
   },

package/templates/gallery/modules/server-actions/actions/greet.test.ts

@@ -13,7 +13,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { createRequestHandler, buildRouteTable, matchPage, matchApi, invokeActionForTest } from '@webjsdev/server';
-import { testRequest, loginAndGetCookies } from '@webjsdev/server/testing';
+import { submitForm, loginAndGetCookies } from '@webjsdev/server/testing';
 
 const appDir = process.cwd();
 process.env.AUTH_SECRET ||= 'test-secret-at-least-32-characters-long!!';
@@ -54,10 +54,11 @@ test('an authenticated greet reads the caller off the session via actionContext(
   // migrated (run db:generate + db:migrate) rather than fail misleadingly.
   const email = `greet+${Date.now()}@example.com`;
   const password = 'password123';
-  const signupRes = await testRequest(app.handle, '/features/auth/signup', {
-    method: 'POST',
-    headers: { 'content-type': 'application/x-www-form-urlencoded' },
-    body: new URLSearchParams({ name: 'Ada', email, password }).toString(),
+  // `submitForm` renders the signup page and reuses the identity the server put
+  // in the form's hidden `__webjs_action` field, which is what tells the
+  // dispatcher which action to run; a POST without it is answered 405.
+  const signupRes = await submitForm(app.handle, '/features/auth/signup', {
+    name: 'Ada', email, password,
   });
   if (signupRes.status !== 302) { t.skip('app deps/db not ready; run db:generate + db:migrate'); return; }
   const { cookies } = await loginAndGetCookies(app.handle, { email, password });

package/templates/gallery/modules/todo/actions/submit-todo.server.ts

@@ -0,0 +1,31 @@
+'use server';
+
+import { createTodo } from './create-todo.server.ts';
+import { toggleTodo } from './toggle-todo.server.ts';
+import { deleteTodo } from './delete-todo.server.ts';
+
+// The no-JS write path for the todo forms. Every <form> in <todo-app> binds
+// THIS action, and the submit button's own `name="intent"` says which mutation
+// to run, which is how one form serves several buttons.
+//
+// Why an intent dispatcher here rather than binding each button to its own
+// action: this form carries the todo's `id` on a hidden input and needs the
+// SAME id for whichever mutation runs, so one action reading both fields is the
+// simpler shape. When the buttons need no shared payload, bind each one
+// directly instead, with `formaction=${action}` on a <button> inside the bound
+// form. The identity then rides that button's own name/value pair, so it works
+// with JS off too. Two things to know: it must be a <button> (on an
+// <input type="submit"> the identity would occupy `value`, which is also that
+// control's visible label), and a bound submitter cannot carry its own
+// `name`/`value`, which is exactly the channel `name="intent"` uses below.
+//
+// With JS the component intercepts the submit and calls the underlying action
+// directly for the optimistic path, so this runs only with JS off.
+export async function submitTodo(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/modules/todo/components/todo-app.ts

@@ -1,6 +1,6 @@
 // The interactive surface. Demonstrates: the WebComponent factory + reactive
 // prop, the DECLARATIVE optimistic() API (instant update, auto-rollback), and
-// progressive enhancement (each mutation is a <form> posting to the page action,
+// progressive enhancement (each mutation is a <form action=${submitTodo}> bound to a server action,
 // intercepted by JS for the optimistic path). All interactivity lives in a
 // component; a page/layout cannot be interactive in its own markup.
 //
@@ -17,6 +17,7 @@ import { cn } from '#lib/utils/cn.ts';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
 import { deleteTodo } from '../actions/delete-todo.server.ts';
+import { submitTodo } from '../actions/submit-todo.server.ts';
 import type { Todo } from '../types.ts';
 
 type Op =
@@ -95,9 +96,9 @@ export class TodoApp extends WebComponent({
           </div>
         </header>
 
-        <!-- Add: a real <form> so it works with JS off (posts to the page action);
-             with JS, @submit intercepts and runs the optimistic path. -->
-        <form method="post" action="" @submit=${(e: SubmitEvent) => this.add(e)}
+        <!-- Add: a real <form> bound to the server action, so it works with JS
+             off; with JS, @submit intercepts and runs the optimistic path. -->
+        <form action=${submitTodo} @submit=${(e: SubmitEvent) => this.add(e)}
           class="${cardClass()} flex items-center gap-2 p-2 pl-4 shadow-[0_1px_0_0_color-mix(in_oklch,var(--foreground)_5%,transparent)]">
           <input type="hidden" name="intent" value="create" />
           <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
@@ -109,7 +110,9 @@ export class TodoApp extends WebComponent({
         <ul class="list-none m-0 p-0 grid gap-2">
           ${list.length ? list.map((todo) => html`
             <li>
-              <form method="post" action=""
+              <!-- One form, two submit buttons: each carries its own
+                   name="intent", which the bound action dispatches on. -->
+              <form action=${submitTodo}
                 class="group flex items-center gap-3 px-3 py-2.5 rounded-xl bg-card border border-border transition-colors hover:border-border-strong ${todo.pending ? 'opacity-55' : ''}">
                 <input type="hidden" name="id" value=${todo.id} />
                 <!-- Toggle is a submit button (degrades to a form POST no-JS); with JS

package/templates/gallery/modules/todo/types.ts

@@ -1,12 +1,17 @@
-// WHY a hand-written interface (not `typeof todos.$inferSelect` from the schema):
-// this type is imported by the browser-shipped <todo-app> component. A VALUE
-// import from `db/*.server.ts` would pin the component to a server module and
-// crash it at load (webjs check flags it). A browser-safe shape here is safe.
-// See the server-actions section in this app's AGENTS.md.
-export interface Todo {
-  id: string;
-  title: string;
-  completed: boolean;
-  createdAt: Date;
+// The row shape is DERIVED from the schema, never re-declared: rename a column
+// in db/schema.server.ts and every consumer of this type is a compile error
+// instead of a silent `undefined` at runtime.
+//
+// `import type` is what makes that safe here. This type is imported by the
+// browser-shipped <todo-app> component, and a VALUE import from a
+// `db/*.server.ts` file would pin the component to a server module and crash it
+// at load (webjs check's no-server-import-in-browser-module flags it). A
+// type-only import is erased by the TypeScript stripper before it can reach the
+// browser, so it is exempt from that rule and costs the client nothing.
+import type { todos } from '#db/schema.server.ts';
+
+type TodoRow = typeof todos.$inferSelect;
+
+export interface Todo extends TodoRow {
   pending?: boolean; // client-only: true while an optimistic create is in flight
 }

package/templates/gallery/test/auth/auth.test.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 
 import { createRequestHandler } from '@webjsdev/server';
-import { testRequest, loginAndGetCookies, withSessionCookie } from '@webjsdev/server/testing';
+import { testRequest, submitForm, loginAndGetCookies, withSessionCookie } from '@webjsdev/server/testing';
 
 const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
@@ -14,7 +14,11 @@ const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 // we detect that at the RESPONSE level (a 5xx on the dashboard) and SKIP with a
 // clear message rather than report a misleading failure. After the db is set up
 // every assertion runs for real.
-process.env.DATABASE_URL ||= 'file:./dev.db';
+// The SAME path `.env.example` and `drizzle.config.ts` use, so `db:migrate`
+// prepares the database this test connects to. Pointing somewhere else made the
+// skip below permanent: it told you to run `db:migrate`, and running it
+// migrated a different file.
+process.env.DATABASE_URL ||= 'file:./db/dev.db';
 process.env.AUTH_SECRET ||= 'test-secret-at-least-32-characters-long!!';
 
 function makeHandler() {
@@ -47,24 +51,35 @@ test('signup -> login -> dashboard renders for the authenticated user', async (t
   const email = `harness+${Date.now()}@example.com`;
   const password = 'password123';
 
-  // Real signup through the page server action (the no-JS form write-path).
-  let canSignup = true;
+  // Real signup through the bound server action (the no-JS form write-path).
+  // `submitForm` renders the page and reuses the identity the server put in the
+  // form's hidden field, exactly as a browser with JS off submits it; a POST
+  // without that field is not a form submission and is answered 405.
+  // Only the REQUEST is guarded: an unmigrated table makes the action throw, and
+  // that is the one condition worth skipping for. The assertions below stay
+  // outside the try on purpose, so a genuine regression fails loudly instead of
+  // being caught and reported as a database that was never set up.
+  let signupRes: Response | null = null;
   try {
-    const signupRes = await testRequest(app.handle, '/features/auth/signup', {
-      method: 'POST',
-      headers: { 'content-type': 'application/x-www-form-urlencoded' },
-      body: new URLSearchParams({ name: 'Harness', email, password }).toString(),
+    signupRes = await submitForm(app.handle, '/features/auth/signup', {
+      name: 'Harness', email, password,
     });
-    // Success auto-logs-in and 302s to the dashboard (carrying the session
-    // cookie); a 422 means validation failed. Either way the action ran.
-    assert.ok([302, 422].includes(signupRes.status), 'signup action ran');
-    if (signupRes.status === 302) assert.equal(signupRes.headers.get('location'), '/features/auth/dashboard', 'signup lands on the dashboard');
-    if (signupRes.status !== 302) canSignup = false;
   } catch {
-    // No migrated DB table -> the action throws. Skip the DB-backed assertions.
-    canSignup = false;
+    signupRes = null;
+  }
+  if (!signupRes || signupRes.status >= 500) {
+    t.skip('no migrated DB; run db:migrate to enable the full flow');
+    return;
+  }
+  // Success auto-logs-in and 302s to the dashboard (carrying the session
+  // cookie); a 422 means validation failed. Either way the action ran.
+  assert.ok([302, 422].includes(signupRes.status), 'signup action ran');
+  if (signupRes.status === 302) {
+    assert.equal(signupRes.headers.get('location'), '/features/auth/dashboard', 'signup lands on the dashboard');
+  } else {
+    t.skip('signup was rejected by validation; run db:migrate to enable the full flow');
+    return;
   }
-  if (!canSignup) { t.skip('no migrated DB; run db:migrate to enable the full flow'); return; }
 
   // Real login captures the genuine signed session cookie.
   const { cookies } = await loginAndGetCookies(app.handle, { email, password });