acrylblends 0.7.3 → 0.7.5

package/docs/framework/getting-started/lambda-edge.md

@@ -0,0 +1,41 @@
+# Lambda@Edge
+
+An Acryl app can answer CloudFront requests from Lambda@Edge. `handle(app)` from `acrylblends/lambda-edge` turns the app into the edge function: it builds a `Request` from the CloudFront event, calls `app.fetch`, and returns a CloudFront response. A viewer-request or origin-request function that answers by itself (a redirect, an HTML page, a JSON answer) is the typical use.
+
+> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a CloudFront viewer-request event. It has not been deployed to AWS by the ACRYL team.
+
+```ts
+import { Acryl } from 'acrylblends'
+import { handle } from 'acrylblends/lambda-edge'
+
+const app = new Acryl()
+
+app.get('/', (c) => c.text('Hello from the edge'))
+
+export const handler = handle(app)
+```
+
+Lambda@Edge has its own limits: the function must be created in `us-east-1`, has no environment variables, and its size and time limits are lower than Lambda's; check them in the AWS documentation when you choose between this adapter and [AWS Lambda](aws-lambda.md).
+
+## The CloudFront event
+
+The CloudFront request, response and config are in the bindings:
+
+```ts
+import { Acryl } from 'acrylblends'
+import type { Callback, CloudFrontEdgeEvent } from 'acrylblends/lambda-edge'
+
+type Bindings = {
+  callback: Callback
+  event: CloudFrontEdgeEvent
+}
+
+const app = new Acryl<{ Bindings: Bindings }>()
+
+app.get('/country', (c) => {
+  const request = c.env.event.Records[0].cf.request
+  return c.json({ uri: request.uri, clientIp: request.clientIp })
+})
+```
+
+The client's address is available through the [ConnInfo helper](../helpers/conninfo.md).

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

@@ -0,0 +1,25 @@
+# Netlify
+
+Netlify Functions (version 2) and Edge Functions take a `Request` and a context and return a `Response`. `handle(app)` from `acrylblends/netlify` is that function; the Netlify context is available to the app as `c.env.context`.
+
+> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a `Request`. It has not been deployed to Netlify by the ACRYL team.
+
+## A function
+
+`netlify/functions/api.ts`:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { handle } from 'acrylblends/netlify'
+import type { Context } from '@netlify/functions'
+
+type Bindings = { context: Context }
+
+const app = new Acryl<{ Bindings: Bindings }>().basePath('/.netlify/functions/api')
+
+app.get('/hello', (c) => c.json({ hello: 'world', site: c.env.context.site.id }))
+
+export default handle(app)
+```
+
+Run it locally with `netlify dev` and publish with `netlify deploy`. The client's address comes from `getConnInfo` of `acrylblends/netlify` (the Netlify context's `ip`); see the [ConnInfo helper](../helpers/conninfo.md).

package/docs/framework/getting-started/other-runtimes.md

@@ -1,23 +1,34 @@
 # Other runtimes
 
-Acryl is built on Web Standards, so the same application code is expected to run wherever a `fetch`-style handler can run. Only Node.js ([guide](nodejs.md)) is verified so far. Bun is experimental ([guide](bun.md)).
+Acryl is built on Web Standards, so the same application code is expected to run wherever a `fetch`-style handler can run. Node.js ([guide](nodejs.md)) is the runtime the framework is verified on. Bun is experimental ([guide](bun.md)).
 
-The following runtimes and platforms are **not yet verified**. There are no getting-started pages for them yet, and their adapters (for example `acrylblends/cloudflare-workers`
-or `acrylblends/aws-lambda`) are not part of acrylblends yet:
+## Hosting platforms with an adapter
+
+These platforms have an adapter in acrylblends, ported from the upstream adapters with their tests. Each is called with the platform's own events in the framework's release check; the ACRYL team has not deployed to these platforms, so try a first deploy on a test project.
+
+| Platform | Guide | Import |
+| --- | --- | --- |
+| AWS Lambda (API Gateway, ALB, Function URLs, VPC Lattice) | [AWS Lambda](aws-lambda.md) | `acrylblends/aws-lambda` |
+| Lambda@Edge (CloudFront) | [Lambda@Edge](lambda-edge.md) | `acrylblends/lambda-edge` |
+| Cloudflare Workers | [Cloudflare Workers](cloudflare-workers.md) | `acrylblends/cloudflare-workers` |
+| Cloudflare Pages | [Cloudflare Pages](cloudflare-pages.md) | `acrylblends/cloudflare-pages` |
+| Vercel | [Vercel](vercel.md) | `acrylblends/vercel` |
+| Netlify | [Netlify](netlify.md) | `acrylblends/netlify` |
+| Service Worker | [Service Worker](service-worker.md) | `acrylblends/service-worker` |
+| Bun | [Bun](bun.md) | `acrylblends/bun` |
+
+## Not yet verified
+
+The following runtimes and platforms have no adapter and no getting-started page yet:
 
 - Deno, and Deno Deploy
-- Cloudflare Workers, and Cloudflare Pages
 - Fastly Compute
-- AWS Lambda, and Lambda@Edge
-- Vercel
-- Netlify
 - Next.js
 - Supabase Functions
 - Google Cloud Run
 - Azure Functions
 - Alibaba Cloud Function Compute
 - CloudBase
-- Service Worker
 - WebAssembly (WASI)
 
-A page is added here, with a getting-started guide, when a platform has been verified with a test that runs on it.
+A page is added here, with a getting-started guide, when a platform has an adapter and a test that calls it.

package/docs/framework/getting-started/service-worker.md

@@ -0,0 +1,33 @@
+# Service Worker
+
+An Acryl app can answer `fetch` events in a Service Worker, and in any environment that uses the Service Worker syntax, such as a Cloudflare Worker written without ES modules. `fire(app)` from `acrylblends/service-worker` registers the app on the `fetch` event, and `handle(app)` returns the listener, if you want to register it yourself.
+
+> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a fetch event. It has not been run inside a browser's Service Worker by the ACRYL team.
+
+```ts
+import { Acryl } from 'acrylblends'
+import { fire } from 'acrylblends/service-worker'
+
+const app = new Acryl()
+
+app.get('/', (c) => c.text('Hello from a Service Worker'))
+
+fire(app)
+```
+
+A request the app does not answer (`404`) can be passed on to the network by giving `fetch` as an option, so a Service Worker can serve some routes and leave the others to the origin:
+
+```ts lib=webworker
+import { Acryl } from 'acrylblends'
+import { handle } from 'acrylblends/service-worker'
+
+declare const self: ServiceWorkerGlobalScope
+
+const app = new Acryl()
+
+app.get('/offline', (c) => c.text('Served by the Service Worker'))
+
+self.addEventListener('fetch', handle(app, { fetch: globalThis.fetch }))
+```
+
+The example is type-checked with the TypeScript `WebWorker` library: declare `self` as a `ServiceWorkerGlobalScope` as above. `app.fire()` (a method of the app) is deprecated in favour of `fire()` from this module.

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

@@ -0,0 +1,28 @@
+# Vercel
+
+Vercel runs a function that takes a `Request` and returns a `Response`, which is what `app.fetch` is. `handle(app)` from `acrylblends/vercel` is that function.
+
+> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a `Request`. It has not been deployed to Vercel by the ACRYL team.
+
+## A function
+
+Create `api/index.ts`:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { handle } from 'acrylblends/vercel'
+
+const app = new Acryl().basePath('/api')
+
+app.get('/', (c) => c.text('Hello from Vercel'))
+app.get('/hello', (c) => c.json({ hello: 'world' }))
+
+export const GET = handle(app)
+export const POST = handle(app)
+```
+
+Export one handler per HTTP method the app answers. Run it locally with `vercel dev`, and publish with `vercel deploy`.
+
+## The client's address
+
+The client's address comes from `getConnInfo` of `acrylblends/vercel`, which reads the `x-real-ip` header Vercel sets; see the [ConnInfo helper](../helpers/conninfo.md).

package/docs/framework/guides/create-acrylblends.md

@@ -8,6 +8,8 @@
 | Template | What you get |
 | --- | --- |
 | `nodejs` | an Acryl application served with `serve()` from `acrylblends/node-server`; run with Node.js 22.19 or newer |
+| `notes` | a full-stack starter: accounts (scrypt, cookie session), notes in SQLite through the [`db` port](data.md) with numbered migrations, validated forms, search, a JSON API with a typed test client, csrf, a test for every route, a client-component counter |
+| `chat` | an AI chat starter: the answer streams token by token from an OpenAI-compatible API (DeepSeek by default, key only from `DEEPSEEK_API_KEY`), a client component with a Stop button that also stops the request to the model, history in SQLite through the [`db` port](data.md), tests with a mock model |
 | `bun` (experimental) | an Acryl application with `export default app`, run with `bun` |
 | `acryl-app` | a Cordis app built from plugins, with an agent that can extend it while it runs (the same app `npx acrylblends init --template agent` creates) |
 
@@ -47,14 +49,50 @@ bun create acrylblends@latest my-app --template nodejs
 | Argument | Description | Example |
 | :-- | :-- | :-- |
 | `[directory]` | The folder to create. It must not exist or must be empty. Asked for when it is missing. | `my-app` |
-| `--template <template>` | One of `nodejs`, `bun` (experimental), `acryl-app`. Skips the template question. | `--template bun` |
-| `--install` | Install the dependencies with the package manager after creating the project. | `--install` |
+| `[source]` | A template from outside the package: `github:owner/repo[#ref]`, `@scope/name[@version]` or a packed `.tgz` file. See [Templates from a repository or a package](#templates-from-a-repository-or-a-package). | `github:acme/starter` |
+| `--template <template>` | One of `nodejs`, `notes`, `chat`, `bun` (experimental), `acryl-app`. Skips the template question. | `--template bun` |
+| `--install` | Install the dependencies with the package manager after creating the project. For a template from a source, the install scripts it will run are listed first. | `--install` |
 | `--pm <packageManager>` | The package manager for `--install`: `npm`, `pnpm`, `yarn` or `bun`. Defaults to the one that started the initializer. | `--pm pnpm` |
 | `--yes`, `-y` | Ask nothing: use `nodejs` unless `--template` is given, and the directory `acryl-app`. | `-y` |
 | `--help` | Print the arguments. | `--help` |
 
 The templates are inside the package, so creating a project needs no network except for `--install`.
 
+## Templates from a repository or a package
+
+A second argument after the directory makes the app from someone else's template:
+
+```sh
+npm create acrylblends@latest my-app github:acme/starter          # a GitHub repository (the default branch)
+npm create acrylblends@latest my-app github:acme/starter#v1.2      # a tag, branch or commit
+npm create acrylblends@latest my-app @acme/starter                 # an npm package
+npm create acrylblends@latest my-app ./acme-starter-1.0.0.tgz      # a packed template on disk
+```
+
+A template is a folder (a repository, or an npm package) with an `acryl.template.json` at its top:
+
+```json
+{
+  "name": "starter",
+  "description": "What the app is",
+  "plugins": ["desktop"]
+}
+```
+
+`name` and `description` are required and shown when the app is created. `plugins` is optional: library plugins the template needs, which the command lists with the `acrylblends add` line that adds them. A source without the file is refused with a message.
+
+What the command does, in order:
+
+1. **Fetches without running anything.** A GitHub source is downloaded as a tarball (never cloned, so no git hook can run). An npm source is fetched with `npm pack --ignore-scripts`. The archive is unpacked into a scratch folder; one with a path that leaves its folder, a symbolic link, more than 5,000 files or more than 50 MB is refused.
+2. **Reads `acryl.template.json`** and refuses the source if it is missing or malformed.
+3. **Fills the template in.** `__APP_NAME__`, `__PACKAGE__`, `__CLASS__` and `__RANGE__` in text files are replaced as in the built-in templates, `package.json` gets the app's name, a dependency on `acrylblends` is set to the release this command carries, a `gitignore` file becomes `.gitignore` (npm does not publish a `.gitignore`), `docs/framework/` is added, and so are `AGENTS.md` and `CLAUDE.md` when the template has none of its own.
+4. **Looks for secrets.** The result is checked with the secret scan the save step of Blend apps uses; a template that holds a key or a password is refused, and the file and line are named (never the value).
+5. **Creates the folder** only if all of that passed.
+
+Nothing of the template is installed or run. If its `package.json` defines `preinstall`, `install`, `postinstall` or `prepare`, the command says so and prints them: `npm install` would run them. Read them first. With `--install` the command prints the list of what will be installed and which scripts will run, then runs the install.
+
+To publish your own: put `acryl.template.json` in the repository or package, name the files with the placeholders above, keep a file named `gitignore` instead of `.gitignore`, and keep secrets out.
+
 ## Example flows
 
 ### Interactive

package/docs/framework/guides/data.md

@@ -0,0 +1,202 @@
+# Data: the `db` port, migrations and choosing a store
+
+An app that keeps records (users, notes, orders) keeps them in a SQL database, and reaches it through one small interface, `db`. Handlers and
+stores take a `Db` as an argument and never import a driver, so the file or server behind it can change without touching them. SQLite is the
+provider today; a Postgres provider (Postgres or Supabase through `DATABASE_URL`) is planned and serves the same interface.
+
+## Choosing
+
+| The app | Use | State |
+| --- | --- | --- |
+| Normal web or desktop app, users, lists, orders | `db` with SQLite (the `notes` and `chat` templates) | available |
+| Hosted, many users | `db` with Postgres or Supabase | planned |
+| Tiny, one person, a few screens | `kv`, named JSON documents with no SQL | planned |
+| Agents or long tasks that must survive a restart | `durable`, in the same database as `db` | planned |
+
+Start with `db`. It is the only one of the four you can use today, and SQL is what people and coding agents already know.
+
+## Open the database
+
+`openDb` from `acrylblends/db/sqlite` opens one SQLite file, applies your migrations, and returns the database next to the function that closes it:
+
+```ts
+import { openDb } from 'acrylblends/db/sqlite'
+
+const { db, close } = await openDb({ path: 'data/app.sqlite', migrations: 'migrations' })
+```
+
+- `path` is the file, created with its folder when it does not exist. `':memory:'` opens a database that lives and dies with the process, which
+  is what tests use.
+- `migrations` is a folder of numbered SQL files, relative to the working directory (see below).
+- `db` is the port: `exec`, `run`, `get`, `all` and `transaction`, every one returning a promise. It has no `close`, so no part of the app can
+  close the database another part is using. `close` is the opener's: call it once, when the process stops.
+
+Pass `db` to the code that needs it. Nothing opens the database at import time, so importing a module never creates a file:
+
+```ts
+import type { Db } from 'acrylblends/db'
+
+export function notesStore(db: Db) {
+  return {
+    async titles(userId: number): Promise<string[]> {
+      const rows = await db.all<{ title: string }>(
+        'SELECT title FROM notes WHERE user_id = ? ORDER BY updated_at DESC',
+        userId,
+      )
+      return rows.map((row) => row.title)
+    },
+  }
+}
+```
+
+## Migrations
+
+The shape of the database lives in `migrations/`, one numbered file per change:
+
+```
+migrations/
+  001-notes.sql
+  002-tags.sql
+```
+
+```sql
+-- migrations/002-tags.sql
+CREATE TABLE tags (
+  note_id INTEGER NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  PRIMARY KEY (note_id, name)
+);
+```
+
+- Files are named `NNN-name.sql` and numbered from 1 with no gaps. A gap, a repeated number or a file named otherwise stops the app at start
+  with a message that names it.
+- On start, `openDb` applies the files that have not run yet, in order, **in one transaction**: a failing file leaves the database as it was.
+- The version is recorded in the `_migrations` table. Do not touch that table.
+- **Never edit a file that has been applied.** A database that already ran `001` does not run it again, so an edit changes only new databases.
+  To change a table, add the next file (`ALTER TABLE notes ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0`).
+- A database whose version is newer than your files (an older build started on newer data) is refused. The app does not start.
+- A migration is plain SQL. Put the data change next to the shape change in the same file when they belong together.
+
+To add a feature that needs a column or a table, the work is always the same three steps: write the next migration, change the store that
+reads and writes it, and change the handlers and views that use the store.
+
+## Reading and writing
+
+```ts
+// One row, or undefined.
+const note = await db.get<Note>('SELECT * FROM notes WHERE id = ? AND user_id = ?', id, userId)
+
+// Many rows.
+const notes = await db.all<Note>('SELECT * FROM notes WHERE user_id = ? ORDER BY id', userId)
+
+// A write: how many rows it changed.
+const { changes } = await db.run('DELETE FROM notes WHERE id = ? AND user_id = ?', id, userId)
+if (changes === 0) return c.notFound()
+
+// A write that gives back the row it made.
+const created = await db.get<Note>(
+  'INSERT INTO notes (user_id, title, body, updated_at) VALUES (?, ?, ?, ?) RETURNING *',
+  userId, title, body, new Date().toISOString(),
+)
+```
+
+- Values go in as **bindings** after the SQL (`?`, in order), never inside the SQL text. This is what keeps a title like `'); DROP TABLE notes;--`
+  a title. A binding is `null`, a number, a bigint, a string or a `Uint8Array`; turn a boolean into `0` or `1` and a date into
+  `toISOString()` yourself.
+- `exec(sql)` runs SQL text with no bindings, and may hold several statements. Use it for setup, not for user input.
+- `db.get` has no `lastInsertRowid`. To get the new row or its id, end the insert with `RETURNING *` or `RETURNING id`.
+- `changes` is what makes "update only if nothing changed meanwhile" possible: `UPDATE ... WHERE id = ? AND version = ?` and check `changes`.
+
+## Transactions
+
+Changes that must happen together go in `transaction`. Everything inside goes through the handle the callback receives:
+
+```ts
+await db.transaction(async (tx) => {
+  const { changes } = await tx.run('UPDATE accounts SET balance = balance - ? WHERE id = ? AND balance >= ?', amount, from, amount)
+  if (changes === 0) throw new Error('not enough money')
+  await tx.run('UPDATE accounts SET balance = balance + ? WHERE id = ?', amount, to)
+})
+```
+
+- If the callback throws, the transaction is rolled back and `transaction` rejects with that same error.
+- Other calls, and other transactions, wait until the transaction finishes. So **never call `db` itself inside the callback**, only `tx`: that
+  call would wait for a transaction that waits for it, and never return.
+- The handle stops working when the callback settles. Do not keep it.
+
+## Writing SQL that moves to Postgres
+
+The Postgres provider is not released yet, and it will serve the same interface. SQL that stays inside this list runs on both:
+
+- Placeholders are `?` on every provider.
+- Use `RETURNING` to get a new row, not a driver-specific "last id".
+- Keep dates as ISO 8601 text (`new Date().toISOString()`), and booleans as `0` and `1`.
+- Keep identifiers lower case and unquoted.
+- `INTEGER PRIMARY KEY` makes an automatically numbered key in SQLite. The identity column of another database is spelled differently, so keep key
+  definitions in migration files, where a different provider's version of the file can differ.
+- SQLite lets a column hold a value of another type than it declares; most other databases do not. Store what you declare.
+
+## In tests
+
+A test opens its own database in memory, with the same migrations as production, and closes it:
+
+```ts
+import { afterEach, beforeEach, expect, test } from 'vitest'
+import { openDb } from 'acrylblends/db/sqlite'
+import { notesStore } from './db.ts'
+
+let close: () => Promise<void>
+let store: ReturnType<typeof notesStore>
+
+beforeEach(async () => {
+  const opened = await openDb({ path: ':memory:', migrations: 'migrations' })
+  close = opened.close
+  store = notesStore(opened.db)
+})
+afterEach(() => close())
+
+test('a new store has no notes', async () => {
+  expect(await store.titles(1)).toEqual([])
+})
+```
+
+## In production
+
+Open the database once at start, serve, and close it when the process is told to stop, after the server has stopped taking requests:
+
+```ts
+import { serve } from 'acrylblends/node-server'
+import { openDb } from 'acrylblends/db/sqlite'
+import { createApp } from './app.ts'
+
+const { db, close } = await openDb({ path: process.env.DATABASE_FILE ?? 'data/app.sqlite', migrations: 'migrations' })
+const server = serve({ fetch: createApp(db).fetch, port: Number(process.env.PORT ?? 3000) })
+
+process.once('SIGTERM', async () => {
+  server.close()
+  await close()
+})
+```
+
+`close` waits for the calls and the transaction that are running, flushes the write-ahead log into the main file, and releases the file, so a
+copy of `data/app.sqlite` made afterwards is complete. Keep the file on a disk that outlives a deploy; on a host with only an ephemeral disk the
+data goes with the machine.
+
+## In a Cordis app
+
+An ACRYL app gets the same interface as a service. The `acryl-db-sqlite` plugin row opens the file (by default `data.sqlite` in the app home),
+applies the `migrations` folder, and provides `db`; a plugin declares `inject: ['db']` and imports the types only:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from 'acryl-db'
+
+export const name = 'notes'
+export const inject = ['db']
+
+export function apply(ctx: Context) {
+  void ctx.db.run('INSERT INTO notes (title) VALUES (?)', 'first')
+}
+```
+
+The plugin never imports a driver, so replacing the SQLite row by another provider is a change to the configuration.

package/docs/framework/guides/faq.md

@@ -12,8 +12,8 @@ A `json` validation target reads the body only when the request has a JSON `Cont
 
 ## Which runtimes are verified?
 
-Node.js. Bun is experimental. The others are listed, as not yet verified, on [Other runtimes](../getting-started/other-runtimes.md).
+Node.js. Bun is experimental. The hosting platforms with an adapter (AWS Lambda, Lambda@Edge, Cloudflare Workers and Pages, Vercel, Netlify, Service Worker) and the ones without are listed on [Other runtimes](../getting-started/other-runtimes.md).
 
 ## Where are the parts marked "not yet available"?
 
-Their pages are part of the documentation so that the structure is complete; each starts with a note saying so. They are enabled as they are ported.
+Their pages are part of the documentation so that the structure is complete; each starts with a note saying so. They are enabled as they are built.

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

@@ -3,31 +3,34 @@
 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.
+## A database with the `db` port
+
+`openDb` from `acrylblends/db/sqlite` opens a SQLite file (Node.js 22.19 and later include SQLite, so there is nothing to install), applies the SQL files in `migrations/`, and returns `{ db, close }`.
+Every call on `db` returns a promise, so `await` it. The [data guide](data.md) has the whole story: migrations, transactions, tests and shutdown.
+
+```sql
+-- migrations/001-notes.sql
+CREATE TABLE users (
+  id INTEGER PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE,
+  password_hash TEXT NOT NULL
+);
+
+CREATE TABLE sessions (
+  token TEXT PRIMARY KEY,
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE
+);
+```
 
 ```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
+import { openDb } from 'acrylblends/db/sqlite'
+
+export function openNotesDb(path = process.env.NOTES_DB ?? 'data/notes.sqlite') {
+  return openDb({ path, migrations: 'migrations' })
 }
 ```
 
-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.
+Take the database as an argument (`createApp(db)`) instead of opening it at import time. A test then opens `openNotesDb(':memory:')`, and importing the app module does not create a file.
 
 ## Passwords with `node:crypto`
 
@@ -63,20 +66,21 @@ 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'
+import type { Db } from 'acrylblends/db'
 
 type Env = { Variables: { user: { id: number; email: string } } }
 
-export function createApp(db: DatabaseSync) {
+export function createApp(db: Db) {
   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)
+      ? db.get<{ id: number; email: string }>(
+          'SELECT users.id AS id, users.email AS email FROM sessions JOIN users ON users.id = sessions.user_id WHERE token = ?',
+          token
+        )
       : undefined
 
   const requireUser = createMiddleware<Env>(async (c, next) => {
-    const user = userFor(getCookie(c, 'sid'))
+    const user = await userFor(getCookie(c, 'sid'))
     if (!user) return c.redirect('/login')
     c.set('user', user)
     await next()
@@ -87,16 +91,16 @@ export function createApp(db: DatabaseSync) {
   app.use('/notes/*', requireUser)
   app.get('/notes', (c) => c.text(`Hello ${c.get('user').email}`))
 
-  app.post('/login-example', (c) => {
+  app.post('/login-example', async (c) => {
     const token = randomBytes(32).toString('hex')
-    db.prepare('INSERT INTO sessions (token, user_id) VALUES (?, ?)').run(token, 1)
+    await db.run('INSERT INTO sessions (token, user_id) VALUES (?, ?)', 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) => {
+  app.post('/logout', async (c) => {
     const token = getCookie(c, 'sid')
-    if (token) db.prepare('DELETE FROM sessions WHERE token = ?').run(token)
+    if (token) await db.run('DELETE FROM sessions WHERE token = ?', token)
     deleteCookie(c, 'sid', { path: '/' })
     return c.redirect('/login', 303)
   })

package/docs/framework/helpers/conninfo.md

@@ -4,7 +4,7 @@ The ConnInfo Helper helps you to get the connection information. For example, yo
 
 ## Import
 
-Only the Node.js adapter, `acrylblends/node-server`, is available today. The adapters for the other platforms (Cloudflare Workers, Bun, Vercel, AWS Lambda, Netlify and Lambda@Edge) are **not yet available**; their imports are shown for completeness and are not checked by the docs tests.
+Each adapter has its own `getConnInfo`: `acrylblends/node-server`, `acrylblends/cloudflare-workers`, `acrylblends/vercel`, `acrylblends/aws-lambda`, `acrylblends/netlify`, `acrylblends/lambda-edge` and `acrylblends/bun`. The Bun example is not type-checked by the docs tests, which run without Bun's types.
 
 **Cloudflare Workers**
 

package/docs/framework/helpers/ssg.md

@@ -98,7 +98,7 @@ export interface FileSystemModule {
 
 ### Using the adapter for Bun
 
-On Bun, a `toSSG` function is provided by `acrylblends/bun` (not yet available).
+On Bun, a `toSSG` function is provided by `acrylblends/bun`; it writes the files with `Bun.write`.
 
 ### Options
 

package/docs/framework/helpers/streaming.md

@@ -170,7 +170,8 @@ async function readEvents(body: ReadableStream<Uint8Array>, on: (event: string,
   for (;;) {
     const { done, value } = await reader.read()
     if (done) return
-    buffer += decoder.decode(value, { stream: true })
+    // Line endings may be CRLF; a \r at the end of a chunk is completed by the next chunk, so normalise the whole buffer.
+    buffer = (buffer + decoder.decode(value, { stream: true })).replaceAll('\r\n', '\n')
     const blocks = buffer.split('\n\n')
     buffer = blocks.pop() ?? ''
     for (const block of blocks) {
@@ -178,7 +179,7 @@ async function readEvents(body: ReadableStream<Uint8Array>, on: (event: string,
       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())
+        else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')) // the SSE spec strips one leading space only
       }
       on(event, data.join('\n'))
     }

package/docs/framework/helpers/websocket.md

@@ -1,11 +1,11 @@
 # WebSocket Helper
 
 WebSocket Helper is a helper for server-side WebSockets in Acryl applications.
-The Node.js adapter is available; the others are not yet available.
+The Node.js, Cloudflare Workers and Bun adapters are available.
 
 ## Import
 
-Only the Node.js adapter, `acrylblends/node-server`, is available today. The adapters for the other platforms (Cloudflare Workers, Bun, Vercel, AWS Lambda, Netlify and Lambda@Edge) are **not yet available**; their imports are shown for completeness and are not checked by the docs tests.
+The Node.js adapter (`acrylblends/node-server`), the Cloudflare Workers adapter (`acrylblends/cloudflare-workers`) and the Bun adapter (`acrylblends/bun`) provide `upgradeWebSocket`. The other platforms have no WebSocket support in their adapters. The Bun adapter is checked on Bun in the framework's release check; its examples below are not type-checked by the docs tests, which run without Bun's types.
 
 **Cloudflare Workers**
 

package/docs/framework/middleware/builtin/ip-restriction.md

@@ -31,7 +31,7 @@ app.use(
 app.get('/', (c) => c.text('Acryl!'))
 ```
 
-Pass the `getConninfo` from the [ConnInfo helper](../../helpers/conninfo.md) appropriate for your environment as the first argument of `ipRestriction`. For a runtime whose adapter is not yet available there is no `getConnInfo` to pass yet.
+Pass the `getConninfo` from the [ConnInfo helper](../../helpers/conninfo.md) appropriate for your environment as the first argument of `ipRestriction`. Every adapter has one (`acrylblends/bun`, `acrylblends/aws-lambda`, `acrylblends/node-server` and the others).
 
 ## Rules
 

package/docs/framework/upstream.json

@@ -2,8 +2,8 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "docs/framework",
-    "commit": "e79bf3de59c700667ae617f5d367cc1fd2f8e037"
+    "commit": "4721bb00960fa4e157e6070c330cf87c148739fc"
   },
-  "files": 91,
-  "digest": "sha256:ea881fe758d9d9add8a8d3837f1dddc6938c3e021cb4ea5f1ce5cfb31af7ef2c"
+  "files": 99,
+  "digest": "sha256:ce484a4cf2bc9781d188fe468e98c498052d50155bb72f84c0a1ad384b1a5e85"
 }