acrylblends 0.7.1 → 0.7.3

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

@@ -0,0 +1,209 @@
+# 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.
+
+## A form and its state in an island
+
+An island that owns an input keeps the text in state and writes it back to the element, so typing and clearing the box both work:
+
+```tsx
+import { render, useState } from 'acrylblends/jsx/dom'
+
+const Ask = () => {
+  const [text, setText] = useState('')
+  const [sent, setSent] = useState<string[]>([])
+  const submit = (event: Event) => {
+    event.preventDefault()
+    if (text.trim() === '') return
+    setSent([...sent, text.trim()])
+    setText('')
+  }
+  return (
+    <form onSubmit={submit}>
+      <textarea value={text} onInput={(e) => setText((e.target as HTMLTextAreaElement).value)} />
+      <button type="submit">Send</button>
+      <ul>
+        {sent.map((message) => (
+          <li>{message}</li>
+        ))}
+      </ul>
+    </form>
+  )
+}
+
+render(<Ask />, document.getElementById('ask')!)
+```
+
+For a request that streams its answer and a Stop button (an `AbortController` kept in a `useRef`), see [Streaming an answer from a model](../helpers/streaming.md#streaming-an-answer-from-a-model).
+
+## 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

@@ -228,4 +228,4 @@ export const Field = () => (
 )
 ```
 
-[Client Components](jsx-dom.md) (`acrylblends/jsx/dom`) are for pages that need components and state in the browser; they have to be bundled for the browser first (with Vite or esbuild).
+[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.
 
@@ -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:

package/docs/framework/helpers/streaming.md

@@ -81,6 +81,125 @@ app.get('/sse', async (c) => {
 })
 ```
 
+## Cancelling work when the client leaves
+
+A reader that closes the tab, loses the network or presses a Stop button should not leave your server working for nobody (a request to a paid model, a database scan). There are two signals, and they are not the same:
+
+- **`c.req.raw.signal`** is the request's `AbortSignal`. It aborts when the client goes away. Pass it to anything that takes a `signal`, such as `fetch`, and the work stops with the client. This is the one to use for cancelling work.
+- **`stream.onAbort(callback)`** and **`stream.aborted`** belong to the response stream. They report that the *reader of the response* was cancelled. Measured: when you call `app.request()` with a `signal` and abort it, `c.req.raw.signal` aborts and `stream.aborted` stays `false`; when the reader of the response body is cancelled, `stream.onAbort` fires and `c.req.raw.signal` does not. On a real connection the request signal is what fired when a browser aborted its `fetch`. Use `c.req.raw.signal` for the work, and `stream.onAbort` for cleanup of the stream itself.
+
+An abort event that has already fired does not fire again, so check `signal.aborted` before you wait for it:
+
+```ts
+const waitForAbort = (signal: AbortSignal) =>
+  signal.aborted
+    ? Promise.resolve()
+    : new Promise<void>((resolve) => signal.addEventListener('abort', () => resolve(), { once: true }))
+```
+
+Keep what you have when the client leaves by saving it in a `finally` block: the stream callback runs to the end whether or not the client is still there.
+
+## Streaming an answer from a model
+
+A chat answer that arrives token by token is a `streamSSE` response that reads a streaming upstream. This server route calls an OpenAI-compatible chat completions API (`stream: true`), forwards each piece as an event, and cancels the upstream request when the client leaves. The key comes from the environment and is never written anywhere.
+
+```ts
+import { Acryl } from 'acrylblends'
+import { streamSSE } from 'acrylblends/streaming'
+
+/** The pieces of an OpenAI-compatible streaming answer: each `data:` line holds a JSON chunk, and `[DONE]` ends it. */
+async function* modelPieces(messages: { role: string; content: string }[], signal: AbortSignal): AsyncGenerator<string> {
+  const key = process.env.DEEPSEEK_API_KEY
+  if (!key) throw new Error('DEEPSEEK_API_KEY is not set')
+  const base = process.env.DEEPSEEK_BASE_URL ?? 'https://api.deepseek.com'
+  const response = await fetch(`${base}/chat/completions`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+    body: JSON.stringify({ model: process.env.DEEPSEEK_MODEL ?? 'deepseek-chat', messages, stream: true }),
+    signal,
+  })
+  if (!response.ok || !response.body) throw new Error(`the model service answered ${response.status}`)
+  const decoder = new TextDecoder()
+  let buffer = ''
+  for await (const chunk of response.body) {
+    buffer += decoder.decode(chunk, { stream: true })
+    const lines = buffer.split('\n')
+    buffer = lines.pop() ?? ''
+    for (const line of lines) {
+      if (!line.startsWith('data:')) continue
+      const data = line.slice(5).trim()
+      if (data === '[DONE]') return
+      const piece = (JSON.parse(data) as { choices?: { delta?: { content?: string } }[] }).choices?.[0]?.delta?.content
+      if (piece) yield piece
+    }
+  }
+}
+
+const app = new Acryl()
+
+app.post('/api/chat', async (c) => {
+  const { message } = await c.req.json<{ message: string }>()
+  const signal = c.req.raw.signal // aborts when the client goes away
+  return streamSSE(c, async (stream) => {
+    let answer = ''
+    try {
+      for await (const piece of modelPieces([{ role: 'user', content: message }], signal)) {
+        answer += piece
+        // JSON-encode the piece: a piece may contain a newline, which would end an SSE `data:` line.
+        await stream.writeSSE({ event: 'token', data: JSON.stringify(piece) })
+      }
+      await stream.writeSSE({ event: 'done', data: '{}' })
+    } catch (error) {
+      if (!signal.aborted) await stream.writeSSE({ event: 'error', data: JSON.stringify('The model could not answer.') })
+    } finally {
+      console.log(`kept ${answer.length} characters`) // save what arrived, also when the client pressed Stop
+    }
+  })
+})
+```
+
+## Reading a POST event stream in the browser
+
+`EventSource` can only send a GET request. For a POST (a chat message), read the response body yourself; this function calls `on` for each event as it arrives:
+
+```ts
+async function readEvents(body: ReadableStream<Uint8Array>, on: (event: string, data: string) => void): Promise<void> {
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) return
+    buffer += decoder.decode(value, { stream: true })
+    const blocks = buffer.split('\n\n')
+    buffer = blocks.pop() ?? ''
+    for (const block of blocks) {
+      let event = 'message'
+      const data: string[] = []
+      for (const line of block.split('\n')) {
+        if (line.startsWith('event:')) event = line.slice(6).trim()
+        else if (line.startsWith('data:')) data.push(line.slice(5).trimStart())
+      }
+      on(event, data.join('\n'))
+    }
+  }
+}
+
+const controller = new AbortController() // controller.abort() is the Stop button
+const response = await fetch('/api/chat', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ message: 'Hello' }),
+  signal: controller.signal,
+})
+let answer = ''
+await readEvents(response.body!, (event, data) => {
+  if (event === 'token') answer += JSON.parse(data) as string
+})
+```
+
+A complete chat component built on this is in the `chat` template of `create-acrylblends` (`npm create acrylblends@latest my-chat -- --template chat`).
+
 ## Error Handling
 
 The third argument of the streaming helper is an error handler.

package/docs/framework/helpers/testing.md

@@ -99,3 +99,20 @@ describe('Search Endpoint', () => {
   })
 })
 ```
+
+### Default request options
+
+`testClient(app, env?, executionCtx?, options?)` takes the client's request options as its fourth argument, so headers every request of a test
+needs, such as a session cookie, are set once. Headers given to a single call are merged over them.
+
+```ts
+import { Acryl } from 'acrylblends'
+import { getCookie } from 'acrylblends/cookie'
+import { testClient } from 'acrylblends/testing'
+
+const app = new Acryl().get('/me', (c) => c.json({ session: getCookie(c, 'session') ?? null }))
+
+const client = testClient(app, undefined, undefined, { headers: { cookie: 'session=abc' } })
+await (await client.me.$get()).json() // { session: 'abc' }
+await (await client.me.$get(undefined, { headers: { cookie: 'session=xyz' } })).json() // { session: 'xyz' }
+```

package/docs/framework/upstream.json

@@ -2,8 +2,8 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "docs/framework",
-    "commit": "524406d2033cdc5ca5e01207f9ce29543bbf221b"
+    "commit": "e79bf3de59c700667ae617f5d367cc1fd2f8e037"
   },
-  "files": 89,
-  "digest": "sha256:fe2da945c3286e316a0412b2d3cfccc4dbf8d1c082e283b77606b45e27b778aa"
+  "files": 91,
+  "digest": "sha256:ea881fe758d9d9add8a8d3837f1dddc6938c3e021cb4ea5f1ce5cfb31af7ef2c"
 }