acrylblends 0.7.0 → 0.7.2

package/docs/framework/getting-started/nodejs.md

@@ -80,27 +80,29 @@ app.get('/', (c) => c.text('Hello Node.js!'))
 serve(app)
 ```
 
-If you want to gracefully shut down the server, write it like this:
+`serve()` listens on `127.0.0.1` unless you pass `hostname`, so a development server is reachable from this machine only, not from the rest
+of the network. See [Listen on another interface](#listen-on-another-interface).
+
+To shut the server down gracefully, stop taking requests, let the ones in flight finish, and exit after a bounded time, so a connection
+that never ends cannot keep the process alive:
 
 ```ts
 const server = serve(app)
 
-// graceful shutdown
-process.on('SIGINT', () => {
-  server.close()
-  process.exit(0)
-})
-process.on('SIGTERM', () => {
-  server.close((err) => {
-    if (err) {
-      console.error(err)
-      process.exit(1)
-    }
-    process.exit(0)
-  })
-})
+function shutdown(): void {
+  server.close(() => process.exit(0))
+  // Keep-alive connections with no request in flight would otherwise hold close() open until they time out.
+  server.closeIdleConnections()
+  setTimeout(() => process.exit(1), 10_000).unref()
+}
+process.once('SIGINT', shutdown)
+process.once('SIGTERM', shutdown)
 ```
 
+`serve(app)` and `serve({ fetch, ... })` return an `http.Server`, which has `closeIdleConnections()`. With `createServer` from
+`node:https` the result is an `https.Server`, and with `node:http2` an `Http2Server` or `Http2SecureServer`, which has no such method;
+there, `server.close()` waits for the open sessions.
+
 > **Note.** On Node.js, `serve()` wraps the `node:http` module and returns the underlying server instance, so closing it is up to you. Bun serves Fetch handlers natively and manages the server itself, which is why its guide doesn't include this step.
 
 ## 3. Run
@@ -136,6 +138,22 @@ serve({
 })
 ```
 
+## Listen on another interface
+
+`serve()` binds `127.0.0.1` when `hostname` is not given. That is right on a developer machine and behind a reverse proxy on the same
+host. Inside a container, or when other machines should reach the app directly, bind every interface on purpose:
+
+```ts
+serve({
+  fetch: app.fetch,
+  port: 3000,
+  hostname: '0.0.0.0', // or '::' for IPv6 and IPv4
+})
+```
+
+> **Note.** Many Node servers listen on every interface by default. `serve()` does not, so starting a development server never exposes
+> the app to the local network by accident.
+
 ## WebSocket
 
 WebSocket support is built into `acrylblends/node-server`. Install `ws` and, if you use TypeScript, `@types/ws`. Then create a `WebSocketServer` with `{ noServer: true }` and pass it to `serve()` with the `websocket` option.
@@ -311,7 +329,9 @@ bun run build
 
 ### Dockerfile
 
-Here is an example of a Node.js Dockerfile.
+Here is an example of a Node.js Dockerfile. A container's published port reaches the app only when it listens on every interface, so
+the app reads its hostname from the environment, as the templates do (`hostname: process.env.HOST || '127.0.0.1'`), and the image
+sets `HOST=0.0.0.0`.
 
 ```Dockerfile
 FROM node:22-alpine AS base
@@ -338,6 +358,7 @@ COPY --from=builder --chown=acrylblends:nodejs /app/dist /app/dist
 COPY --from=builder --chown=acrylblends:nodejs /app/package.json /app/package.json
 
 USER acrylblends
+ENV HOST=0.0.0.0
 EXPOSE 3000
 
 CMD ["node", "/app/dist/index.js"]

package/docs/framework/guides/client-modules.md

@@ -0,0 +1,175 @@
+# Client components without a bundler
+
+A page can run [client components](jsx-dom.md) written in TypeScript and JSX with no bundler and no build configuration. `clientModules` from
+`acrylblends/node-server` serves a folder of client modules to the browser: each `.tsx`, `.ts` or `.jsx` file is compiled when the browser asks
+for it, with your app's own `typescript`, and the framework's browser imports are pointed at the browser builds the package ships. The page
+needs one script tag.
+
+It runs on Node, the runtime the framework targets. For a large client app with many npm packages, a bundler (Vite, esbuild) remains the
+better tool; see [The `acrylblends/jsx/dom` runtime](jsx-dom.md#the-acrylblendsjsxdom-runtime).
+
+## Set up
+
+The routes, with the type the browser's typed client uses, in a file of their own (`app.ts`):
+
+```ts
+import { Acryl } from 'acrylblends'
+
+export const app = new Acryl()
+  .get('/', (c) =>
+    c.html(
+      '<!doctype html><div id="counter"></div><p id="greeting"></p>' +
+        '<script type="module" src="/client/counter.tsx"></script>'
+    )
+  )
+  .get('/api/hello', (c) => c.json({ hello: 'browser' }))
+
+export type AppType = typeof app
+```
+
+The Node entry routes the client modules next to them (`site.ts`):
+
+```ts
+import { Acryl } from 'acrylblends'
+import { clientModules, serve } from 'acrylblends/node-server'
+import { app } from './app.ts'
+
+const site = new Acryl()
+  .route('/', app)
+  .route('/client', clientModules({ root: 'src/client', compiled: 'dist/client' }))
+
+serve({ fetch: site.fetch, port: 3000 })
+```
+
+A client component (`src/client/counter.tsx`), with a helper module beside it (`src/client/parts/label.ts`):
+
+```tsx
+import { render, useState } from 'acrylblends/jsx/dom'
+import { hc } from 'acrylblends/client'
+import type { AppType } from '../../app.ts'
+import { label } from './parts/label.ts'
+
+const Counter = () => {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(count + 1)}>{label(count)}</button>
+}
+
+render(<Counter />, document.getElementById('counter')!)
+
+const client = hc<AppType>(location.origin)
+const { hello } = await (await client.api.hello.$get()).json()
+document.getElementById('greeting')!.textContent = `hello ${hello}`
+```
+
+```ts
+export const label = (count: number): string => `Count ${count}`
+```
+
+Start the site with `node site.ts` and open `http://localhost:3000`. Edit `counter.tsx` and reload: the module is compiled again.
+
+Your editor checks the client folder as browser code with its own `src/client/tsconfig.json`: the DOM library, the DOM renderer, no Node
+types. This is why `AppType` comes from `app.ts`, which does not import the Node adapter.
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "acrylblends/jsx/dom",
+    "types": []
+  },
+  "include": ["**/*.ts", "**/*.tsx"]
+}
+```
+
+## Server markup and `hydrateRoot`
+
+A page can carry server-rendered markup for an island and take it over in the browser with `hydrateRoot` from `acrylblends/jsx/dom/client`:
+
+```tsx
+import { useState } from 'acrylblends/jsx/dom'
+import { hydrateRoot } from 'acrylblends/jsx/dom/client'
+
+const Counter = () => {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(count + 1)}>Count {count}</button>
+}
+
+hydrateRoot(document.getElementById('island')!, <Counter />)
+```
+
+The DOM renderer does not reuse server markup: `hydrateRoot` renders the component and replaces the element's children with its output
+in one step, so the page shows the server markup until the module runs and the component from then on, with no empty frame between. The
+server's nodes are gone afterwards, together with anything the visitor did to them before the module ran: focus, a selection, text typed
+into an input. Keep the server markup the same as the component's first render, so the swap does not show, and keep inputs out of the
+server markup of an island, or render them only in the browser.
+
+## How the imports reach the browser
+
+- JSX in a client module always compiles for the DOM renderer (`acrylblends/jsx/dom`), whatever the server's `tsconfig.json` says. A file's
+  own `/** @jsxImportSource ... */` comment still wins.
+- `acrylblends/jsx/dom`, its `jsx-runtime`, `jsx-dev-runtime` and `client` are one browser module (`@acrylblends/jsx-dom.js`), and
+  `acrylblends/client` is another (`@acrylblends/client.js`). Neither imports anything. The same app serves them, and each import is
+  rewritten to a URL relative to the module, so the setup works under whatever path you route `clientModules` at.
+- Import your own modules with their file names, as the browser fetches them: `import { label } from './parts/label.ts'`.
+- Another package (`import confetti from 'canvas-confetti'`) is left as it is: add an
+  [import map](https://developer.mozilla.org/docs/Web/HTML/Element/script/type/importmap) to the page for it, or use a bundler.
+- `.js` and `.mjs` files are served unchanged.
+
+A module is compiled once and kept in memory until its file changes, up to 16 MiB of compiled code (the least recently served goes first;
+set `cacheBytes` to change the bound). Responses carry an `ETag` and `Cache-Control: no-cache`, so the browser revalidates and an edit shows
+on the next reload. Only files inside the folder are served: a path with `..` or a dot segment, a `.d.ts` file, a symbolic link out of the
+folder and other file types answer 404.
+
+## In production
+
+Templates install `typescript` as a development dependency, and a deploy that leaves those out (`npm ci --omit=dev`) has no compiler.
+Compile the client folder once when you build, as the `build` script of your `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "acrylblends build-client"
+  }
+}
+```
+
+`acrylblends build-client [root] [outDir]` (from acrylblends 0.7.2; `src/client` and `dist/client` when not given) calls
+`buildClientModules`. With an earlier version, or without the command line tool, call the function itself:
+
+```json
+{
+  "scripts": {
+    "build": "node --input-type=module -e \"import { buildClientModules } from 'acrylblends/node-server'; buildClientModules({ root: 'src/client', outDir: 'dist/client' })\""
+  }
+}
+```
+
+It writes each module compiled to `dist/client` at the same path and file name, so the page's URLs stay the same, and copies the two
+browser modules to `dist/client/@acrylblends/`. Run it where `typescript` is installed, before the development dependencies are removed.
+
+With `NODE_ENV=production` and the `compiled` option set, `clientModules` serves only that folder and compiles nothing. A module that is in
+`src/client` but missing from `dist/client` answers 500 with a message to build again, and a `compiled` folder that does not exist stops the
+server at startup. Outside production, modules are always compiled on request, so a stale `dist/client` never hides an edit.
+
+When `typescript` is missing where a module has to be compiled, the module answers 500 with the message
+`... is a client module, and compiling it needs the typescript package in this app: npm install --save-dev typescript`.
+
+## Reference
+
+`clientModules(options)` returns an app; route it where the page's script tags point.
+
+| Option | Meaning |
+| --- | --- |
+| `root` | The folder of client modules, absolute or relative to the working directory. |
+| `compiled` | The folder `buildClientModules` wrote. Served instead of compiling when `NODE_ENV` is `production`. |
+| `cacheBytes` | The bound of the in-memory cache of compiled modules, in bytes. 16 MiB when not given. |
+
+`buildClientModules({ root, outDir })` compiles every module below `root` (dot files, `node_modules` and `.d.ts` files skipped) into `outDir`,
+which must not lie inside `root`, and returns the paths it wrote. Files already in `outDir` that no source produces are left there.

package/docs/framework/guides/forms-and-sessions.md

@@ -0,0 +1,231 @@
+# Forms, sessions and a database
+
+This page shows the parts a small multi-user app needs, in the order an app uses them: a database, passwords, a cookie session, HTML forms with server-side validation, and a JSON API that shares the same rules.
+It is the shape of a "Notes" app built from these docs alone (sign up, log in, create, edit, delete and search notes, a typed test client for the API).
+
+## A database with `node:sqlite`
+
+Node.js 22.19 and later include SQLite, so there is nothing to install. `DatabaseSync` is synchronous, which suits a small app.
+
+```ts
+import { DatabaseSync } from 'node:sqlite'
+
+export function openDb(path = process.env.NOTES_DB ?? 'notes.db'): DatabaseSync {
+  const db = new DatabaseSync(path)
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS users (
+      id INTEGER PRIMARY KEY,
+      email TEXT NOT NULL UNIQUE,
+      password_hash TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS sessions (
+      token TEXT PRIMARY KEY,
+      user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE
+    );
+  `)
+  return db
+}
+```
+
+Take the database as an argument (`createApp(db)`) instead of opening it at import time. A test then passes `openDb(':memory:')`, and importing the app module does not create a file.
+
+## Passwords with `node:crypto`
+
+Never store a password. Store a salted `scrypt` hash and compare in constant time.
+
+```ts
+import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto'
+import { promisify } from 'node:util'
+
+const scryptAsync = promisify(scrypt) as (password: string, salt: Buffer, length: number) => Promise<Buffer>
+
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(16)
+  const key = await scryptAsync(password, salt, 64)
+  return `${salt.toString('hex')}:${key.toString('hex')}`
+}
+
+export async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const [salt, key] = stored.split(':')
+  if (!salt || !key) return false
+  const expected = Buffer.from(key, 'hex')
+  return timingSafeEqual(await scryptAsync(password, Buffer.from(salt, 'hex'), expected.length), expected)
+}
+```
+
+## A cookie session
+
+The simplest session is a random token in an `httpOnly` cookie and a `sessions` row that maps it to a user. Log out deletes the row, so a stolen cookie stops working.
+`getCookie`, `setCookie` and `deleteCookie` are in [the Cookie helper](../helpers/cookie.md).
+
+```ts
+import { Acryl } from 'acrylblends'
+import { createMiddleware } from 'acrylblends/factory'
+import { deleteCookie, getCookie, setCookie } from 'acrylblends/cookie'
+import { randomBytes } from 'node:crypto'
+import type { DatabaseSync } from 'node:sqlite'
+
+type Env = { Variables: { user: { id: number; email: string } } }
+
+export function createApp(db: DatabaseSync) {
+  const userFor = (token: string | undefined) =>
+    token
+      ? (db
+          .prepare('SELECT users.id AS id, users.email AS email FROM sessions JOIN users ON users.id = sessions.user_id WHERE token = ?')
+          .get(token) as { id: number; email: string } | undefined)
+      : undefined
+
+  const requireUser = createMiddleware<Env>(async (c, next) => {
+    const user = userFor(getCookie(c, 'sid'))
+    if (!user) return c.redirect('/login')
+    c.set('user', user)
+    await next()
+  })
+
+  const app = new Acryl<Env>()
+  app.use('/notes', requireUser)
+  app.use('/notes/*', requireUser)
+  app.get('/notes', (c) => c.text(`Hello ${c.get('user').email}`))
+
+  app.post('/login-example', (c) => {
+    const token = randomBytes(32).toString('hex')
+    db.prepare('INSERT INTO sessions (token, user_id) VALUES (?, ?)').run(token, 1)
+    setCookie(c, 'sid', token, { path: '/', httpOnly: true, sameSite: 'Lax', maxAge: 60 * 60 * 24 * 30 })
+    return c.redirect('/notes', 303)
+  })
+
+  app.post('/logout', (c) => {
+    const token = getCookie(c, 'sid')
+    if (token) db.prepare('DELETE FROM sessions WHERE token = ?').run(token)
+    deleteCookie(c, 'sid', { path: '/' })
+    return c.redirect('/login', 303)
+  })
+  return app
+}
+```
+
+A middleware registered with `use('/notes', ...)` does not cover `/notes/…`: register both `'/notes'` and `'/notes/*'`.
+After a form POST redirect with status **303** so the browser follows with a GET.
+
+## Forms and server-side validation
+
+`await c.req.parseBody()` reads an HTML form (`application/x-www-form-urlencoded` or multipart). Each value is a `string` or a `File`, so convert with `String(...)` or check `typeof`.
+Keep the rules in one function that both the form routes and the JSON API call, and answer an invalid form with **status 400 and the same page**, with the messages and the typed values filled in:
+
+```ts
+export interface NoteInput {
+  title: string
+  body: string
+}
+
+export function checkNote(value: unknown): { value: NoteInput } | { issues: { message: string; path: string[] }[] } {
+  const input = (value ?? {}) as Record<string, unknown>
+  const title = typeof input.title === 'string' ? input.title.trim() : ''
+  const body = typeof input.body === 'string' ? input.body : ''
+  const issues: { message: string; path: string[] }[] = []
+  if (title === '') issues.push({ message: 'Give the note a title.', path: ['title'] })
+  if (body.length > 2000) issues.push({ message: 'The note is at most 2000 characters.', path: ['body'] })
+  return issues.length > 0 ? { issues } : { value: { title, body } }
+}
+```
+
+```tsx
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.post('/notes', async (c) => {
+  const form = await c.req.parseBody()
+  const checked = checkNote(form)
+  if ('issues' in checked) {
+    const messages = checked.issues.map((issue) => issue.message)
+    return c.html(
+      <form method="post" action="/notes">
+        <ul role="alert">
+          {messages.map((message) => (
+            <li>{message}</li>
+          ))}
+        </ul>
+        <input name="title" value={String(form.title ?? '')} />
+        <textarea name="body">{String(form.body ?? '')}</textarea>
+        <button type="submit">Save</button>
+      </form>,
+      400,
+    )
+  }
+  return c.redirect('/notes', 303)
+})
+```
+
+Escaping is automatic in JSX: `{String(form.title)}` is safe to put in a page. Use `dangerouslySetInnerHTML` only for text you wrote yourself, such as a `<style>` or `<script>` block.
+
+## A JSON API that shares the rules
+
+Wrap `checkNote` as a Standard Schema (an object with a `~standard.validate` function) and give it to `schemaValidator`. A failure answers 400 with `{ error, issues: [{ message, path }] }`.
+Build the API app by **chaining** the routes on `new Acryl()`, because the typed client and `testClient` only know chained routes:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { schemaValidator, type StandardSchema } from 'acrylblends/schema-validator'
+
+const NoteSchema: StandardSchema<NoteInput> = {
+  '~standard': { validate: (value) => checkNote(value) },
+}
+
+export const api = new Acryl()
+  .get('/', (c) => c.json({ notes: [] as NoteInput[] }, 200))
+  .post('/', schemaValidator('json', NoteSchema), (c) => c.json({ note: c.req.valid('json') }, 201))
+  .get('/:id', (c) => (c.req.param('id') === '1' ? c.json({ note: { title: 't', body: '' } }, 200) : c.json({ error: 'No such note.' }, 404)))
+```
+
+Mount it below the pages with `app.route('/api/notes', api)`.
+
+## Testing every route
+
+Call the app with `app.request`. A form POST needs a body and the cookie of a signed-in user, which a test reads from the sign-up response's `set-cookie` header:
+
+```ts
+const response = await app.request('/signup', {
+  method: 'POST',
+  body: new URLSearchParams({ email: 'a@example.com', password: 'correct horse' }),
+})
+const cookie = (response.headers.get('set-cookie') ?? '').split(';')[0] ?? ''
+await app.request('/notes', { headers: { cookie } })
+```
+
+For the typed API use `testClient` ([Testing helper](../helpers/testing.md)); the cookie goes in the second argument of each call:
+
+```ts
+import { testClient } from 'acrylblends/testing'
+
+const client = testClient(api)
+const created = await client.index.$post({ json: { title: 'First', body: 'hello' } }, { headers: { cookie } })
+const { note } = await created.json()
+const one = await client[':id'].$get({ param: { id: '1' } }, { headers: { cookie } })
+```
+
+A route mounted at `'/'` is `client.index` and `'/:id'` is `client[':id']`.
+
+## A part of the page that reacts in the browser
+
+A live character counter or an instant filter needs a little JavaScript in the page. The simplest way, with no build step, is a `<script>` in the server-rendered page:
+
+```tsx
+const counter = `
+  const area = document.getElementById('body')
+  const out = document.getElementById('count')
+  const show = () => { out.textContent = area.value.length + ' / ' + area.maxLength }
+  area.addEventListener('input', show)
+  show()
+`
+
+export const Field = () => (
+  <>
+    <textarea id="body" name="body" maxlength={2000} />
+    <small id="count" aria-live="polite" />
+    <script dangerouslySetInnerHTML={{ __html: counter }} />
+  </>
+)
+```
+
+[Client Components](jsx-dom.md) (`acrylblends/jsx/dom`) are for pages that need components and state in the browser; on Node, [Client components without a bundler](client-modules.md) serves them to the browser with one script tag, or bundle them with Vite or esbuild.

package/docs/framework/guides/jsx-dom.md

@@ -2,7 +2,9 @@
 
 `acrylblends/jsx` supports not only server side but also client side. This means that it is possible to create an interactive UI that runs in the browser. We call it Client Components or `acrylblends/jsx/dom`.
 
-It is fast and very small. The counter program in `acrylblends/jsx/dom` is only 2.8KB with Brotli compression, but 47.8KB for React.
+It is small and imports nothing. Measured with Node's `zlib.brotliCompressSync` at the highest quality: the whole runtime as
+[`clientModules`](client-modules.md) serves it (`jsx-dom.js`, not minified) is 11,209 bytes with Brotli compression, and the counter
+below, bundled and minified with tsdown so only the parts it uses are kept, is 5,804 bytes.
 
 This section introduces Client Components-specific features.
 
@@ -105,11 +107,11 @@ export default function App() {
       </button>
       <div>
         {!showLargeImage ? (
-          <img src=' />
+          <img src="/photo.jpg" alt="" />
         ) : (
           <div
             class={css`
-              background: url(');
+              background: url('/photo.jpg');
               background-size: contain;
               background-repeat: no-repeat;
               background-position: center;
@@ -170,12 +172,12 @@ export default function App() {
       </button>
       <div>
         {!showLargeImage ? (
-          <img src=' />
+          <img src="/photo.jpg" alt="" />
         ) : (
           <div
             class={css`
               ${transitionNameClass}
-              background: url(');
+              background: url('/photo.jpg');
               background-size: contain;
               background-repeat: no-repeat;
               background-position: center;
@@ -240,12 +242,12 @@ export default function App() {
       </button>
       <div>
         {!showLargeImage ? (
-          <img src=' />
+          <img src="/photo.jpg" alt="" />
         ) : (
           <div
             class={css`
               ${transitionNameClass}
-              background: url(');
+              background: url('/photo.jpg');
               background-size: contain;
               background-repeat: no-repeat;
               background-position: center;
@@ -272,6 +274,9 @@ export default function App() {
 
 ## The `acrylblends/jsx/dom` runtime
 
+On Node you can skip the bundler: [Client components without a bundler](client-modules.md) serves `.tsx` client modules to the browser with
+this runtime and one script tag, in development and in production.
+
 There is a small JSX Runtime for Client Components. Using this will result in smaller bundled results than using `acrylblends/jsx`. Specify `acrylblends/jsx/dom` in `tsconfig.json`. For Deno, modify the deno.json.
 
 ```json

package/docs/framework/guides/validation.md

@@ -144,6 +144,93 @@ app.post(
 )
 ```
 
+## Validating an HTML form
+
+A browser posts a `<form>` as `application/x-www-form-urlencoded`, or as `multipart/form-data` when it has `enctype="multipart/form-data"` (needed
+for file inputs). `validator('form', ...)` parses both. Each field arrives as a `string`, a file input as a `File`, and a name that appears more
+than once (several checkboxes, or a name ending in `[]`) as an array, so the value has the type `Record<string, string | File | (string | File)[]>`.
+
+This page shows a form and re-renders it with a message when a field is wrong:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { html } from 'acrylblends/html'
+import { validator } from 'acrylblends/validator'
+
+const page = (error?: string) => html`<!doctype html>
+  <form method="post" action="/notes" enctype="multipart/form-data">
+    <input name="title" required>
+    <textarea name="body"></textarea>
+    <input type="file" name="attachment">
+    <button>Save</button>
+    ${error === undefined ? '' : html`<p role="alert">${error}</p>`}
+  </form>`
+
+const app = new Acryl()
+  .get('/notes/new', (c) => c.html(page()))
+  .post(
+    '/notes',
+    validator('form', (form, c) => {
+      const { title, body, attachment } = form
+      if (typeof title !== 'string' || title.trim() === '') return c.html(page('Title is required'), 400)
+      if (body !== undefined && typeof body !== 'string') return c.html(page('Body must be text'), 400)
+      if (attachment !== undefined && !(attachment instanceof File)) return c.html(page('Attachment must be one file'), 400)
+      return {
+        title: title.trim(),
+        body: body ?? '',
+        // A file input left empty still sends a part: a File with no name and no bytes.
+        attachment: attachment !== undefined && attachment.size > 0 ? attachment : undefined,
+      }
+    }),
+    (c) => {
+      const { title, attachment } = c.req.valid('form') // { title: string, body: string, attachment: File | undefined }
+      return c.text(`Saved ${title}${attachment === undefined ? '' : ` with ${attachment.name}`}`, 201)
+    }
+  )
+```
+
+The messages are escaped by `html`, so a field value shown back in the page cannot inject markup.
+
+### With a schema
+
+`schemaValidator('form', schema)` takes the same value. It answers a failure with 400 and JSON issues, which suits a form your own script submits
+with `fetch()`:
+
+```ts
+import * as z from 'zod'
+import { schemaValidator } from 'acrylblends/schema-validator'
+
+const NoteForm = z.object({
+  title: z.string().trim().min(1, 'Title is required'),
+  body: z.string().default(''),
+  attachment: z.instanceof(File).optional(),
+})
+
+app.post('/api/notes', schemaValidator('form', NoteForm), (c) => {
+  const { title } = c.req.valid('form') // typed by the schema's output
+  return c.json({ title }, 201)
+})
+```
+
+For a plain HTML form, call the schema inside `validator('form', ...)` to re-render the page with the first message instead:
+
+```ts
+validator('form', (form, c) => {
+  const result = NoteForm.safeParse(form)
+  return result.success ? result.data : c.html(page(result.error.issues[0]?.message), 400)
+})
+```
+
+To test a form route, send a `FormData`: `app.request` sets the `multipart/form-data` content type with its boundary itself.
+
+```ts
+const form = new FormData()
+form.set('title', 'Groceries')
+form.set('attachment', new File(['milk'], 'list.txt', { type: 'text/plain' }))
+const res = await app.request('/notes', { method: 'POST', body: form })
+// res.status === 201, await res.text() === 'Saved Groceries with list.txt'
+```
+
 ## Multiple validators
 
 You can also include multiple validators to validate different parts of request:
@@ -213,7 +300,7 @@ const route = app.post(
   validator('form', (value, c) => {
     const parsed = schema.safeParse(value)
     if (!parsed.success) {
-      return c.text('Invalid!', 401)
+      return c.text('Invalid!', 400)
     }
     return parsed.data
   }),

package/docs/framework/helpers/cookie.md

@@ -36,7 +36,7 @@ app.get('/cookie', (c) => {
 **NOTE**: Setting and retrieving signed cookies returns a Promise due to the async nature of the WebCrypto API, which is used to create HMAC SHA-256 signatures.
 
 ```ts
-app.get('/signed-cookie', (c) => {
+app.get('/signed-cookie', async (c) => {
   const secret = process.env.COOKIE_SECRET! // a long random string, kept out of the source
 
   await setSignedCookie(c, 'cookie_name0', 'cookie_value', secret)