acrylblends 0.7.3 → 0.7.4

package/docs/framework/README.md

@@ -35,12 +35,12 @@ The starter asks which template you want (`nodejs`, `bun` (experimental), or `ac
 
 ## Runtimes
 
-Verified: Node.js. Bun is experimental. The other runtimes the framework could target are listed on [Other runtimes](getting-started/other-runtimes.md) as not yet verified.
+Verified: Node.js. Bun is experimental (its adapter is checked on Bun). Adapters for AWS Lambda, Lambda@Edge, Cloudflare Workers and Pages, Vercel, Netlify and Service Workers are part of the package, with a guide each on [Other runtimes](getting-started/other-runtimes.md); they are tested with the platforms' own events and have not been deployed by the ACRYL team.
 
 ## Not yet available
 
-Some parts of the documented API surface are not part of the package yet, and their pages say so at the top: the adapters of the runtimes other than Node.js.
-They are enabled as they are ported.
+Some parts of the documented API surface are not part of the package yet, and their pages say so: the Vite plugin for static site generation, a registry of third-party middleware, and benchmark results.
+They are enabled as they are built.
 
 ## Where to read next
 
@@ -49,6 +49,7 @@ They are enabled as they are ported.
 | Run something in five minutes | [Getting started](getting-started/basic.md) |
 | Run the app as a desktop app | [Desktop](getting-started/desktop.md) |
 | Run it on a server | [Deploy](getting-started/deploy.md) |
+| Run it on a hosting platform | [Other runtimes](getting-started/other-runtimes.md): [AWS Lambda](getting-started/aws-lambda.md), [Cloudflare Workers](getting-started/cloudflare-workers.md), [Vercel](getting-started/vercel.md), [Netlify](getting-started/netlify.md) |
 | Look up a call | [API](api/index.md), [Routing](api/routing.md), [Context](api/context.md), [Request](api/request.md), [API summary](api/summary.md) |
 | Understand the design | [Concepts](concepts/motivation.md) |
 | Copy a pattern | [Guides](guides/best-practices.md), [Validation](guides/validation.md), [Testing](guides/testing.md), [Forms, sessions and a database](guides/forms-and-sessions.md), [Client components without a bundler](guides/client-modules.md) |

package/docs/framework/UPSTREAM.md

@@ -1,3 +1,3 @@
 # Generated copy
 
-This folder is a copy of `docs/framework` of acryldev/acryl at commit `e79bf3de59c700667ae617f5d367cc1fd2f8e037`, made by `scripts/sync-framework.mjs`. Do not edit it here: change the text in ACRYL and sync again. `pnpm run verify:framework` fails when a page differs from the recorded digest.
+This folder is a copy of `docs/framework` of acryldev/acryl at commit `eada6fb06a5cafb6c2c92a97effeba567dbd44ba`, made by `scripts/sync-framework.mjs`. Do not edit it here: change the text in ACRYL and sync again. `pnpm run verify:framework` fails when a page differs from the recorded digest.

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

@@ -0,0 +1,115 @@
+# AWS Lambda
+
+An Acryl app runs on AWS Lambda behind API Gateway (REST API and HTTP API), an Application Load Balancer, a Lambda Function URL or VPC Lattice. `handle(app)` from `acrylblends/aws-lambda` turns the app into the Lambda handler: it builds a `Request` from the event, calls `app.fetch`, and returns the result in the shape the event source expects.
+
+> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with API Gateway v1 and v2 and ALB events. It has not been deployed to an AWS account by the ACRYL team: try your first deploy with a test stage.
+
+## Install and write the handler
+
+```sh
+npm install acrylblends
+```
+
+```ts
+import { Acryl } from 'acrylblends'
+import { handle } from 'acrylblends/aws-lambda'
+
+const app = new Acryl()
+
+app.get('/', (c) => c.text('Hello from Lambda'))
+app.get('/json', (c) => c.json({ message: 'Hello JSON' }))
+
+export const handler = handle(app)
+```
+
+Bundle the file to one JavaScript file for the `nodejs22.x` (or newer) runtime with your tool of choice (esbuild is common), upload it, and set the handler to `index.handler` (the file name, a dot, the export).
+
+## The event and the Lambda context
+
+Both are in the bindings of the request:
+
+```ts
+import { Acryl } from 'acrylblends'
+import type { LambdaContext, LambdaEvent } from 'acrylblends/aws-lambda'
+
+type Bindings = {
+  event: LambdaEvent
+  lambdaContext: LambdaContext
+}
+
+const app = new Acryl<{ Bindings: Bindings }>()
+
+app.get('/info', (c) => {
+  return c.json({
+    isBase64Encoded: c.env.event.isBase64Encoded,
+    awsRequestId: c.env.lambdaContext.awsRequestId,
+  })
+})
+```
+
+`c.env.requestContext` holds the request context of the event (API Gateway, ALB or Lattice). The client's address is available through the [ConnInfo helper](../helpers/conninfo.md): `getConnInfo(c).remote.address`.
+
+## Binary responses
+
+A response is returned base64 encoded when its content type is binary (images, audio, video, PDF, archives and other non-text types) or it has a content encoding such as `gzip`. To decide differently, pass `isContentTypeBinary`:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { defaultIsContentTypeBinary, handle } from 'acrylblends/aws-lambda'
+
+const app = new Acryl()
+
+export const handler = handle(app, {
+  isContentTypeBinary: (contentType) =>
+    defaultIsContentTypeBinary(contentType) || contentType.startsWith('application/vnd.api+octet'),
+})
+```
+
+## Response streaming
+
+On a Function URL with `RESPONSE_STREAM` invoke mode, use `streamHandle` instead of `handle`: the body is written to the response stream as the app produces it, so [streaming helpers](../helpers/streaming.md) (SSE, `stream`, `streamText`) reach the client as they are written. It needs the `awslambda` global, which only the Lambda runtime provides.
+
+```ts
+import { Acryl } from 'acrylblends'
+import { streamHandle } from 'acrylblends/aws-lambda'
+
+const app = new Acryl()
+
+export const handler = streamHandle(app)
+```
+
+## Try it without AWS
+
+A handler is a function from an event to a result, so it can be called locally with a sample event:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { handle } from 'acrylblends/aws-lambda'
+
+const app = new Acryl().get('/', (c) => c.text('Hello from Lambda'))
+
+const result = await handle(app)({
+  version: '2.0',
+  routeKey: '$default',
+  rawPath: '/',
+  rawQueryString: '',
+  headers: { host: 'example.execute-api.eu-west-1.amazonaws.com' },
+  requestContext: {
+    accountId: '1',
+    apiId: 'example',
+    authentication: null,
+    authorizer: {},
+    domainName: 'example.execute-api.eu-west-1.amazonaws.com',
+    domainPrefix: 'example',
+    http: { method: 'GET', path: '/', protocol: 'HTTP/1.1', sourceIp: '203.0.113.9', userAgent: 'test' },
+    requestId: 'r',
+    routeKey: '$default',
+    stage: '$default',
+    time: '25/Oct/2026:12:00:00 +0000',
+    timeEpoch: 0,
+  },
+  body: null,
+  isBase64Encoded: false,
+})
+console.log(result.statusCode, result.body) // 200 Hello from Lambda
+```

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

@@ -1,6 +1,6 @@
 # Bun
 
-> **Experimental.** Bun is not a verified runtime yet: the Acryl application code is the same, but the `bun` template and this guide are not covered by the release checks. Node.js is the verified runtime.
+> **Experimental.** Bun is not a verified runtime yet: the Acryl application code is the same, and the Bun adapter (`acrylblends/bun`) is checked on Bun in the framework's release check (a static file, the client address, a WebSocket echo), but the `bun` template and this guide are not covered by the release checks. Node.js is the verified runtime.
 
 
 [Bun](https://bun.com) is another JavaScript runtime. It's not Node.js. Bun includes a transcompiler, so we can write the code in TypeScript or plain JavaScript.
@@ -94,8 +94,6 @@ export default {
 
 To serve static files, use `serveStatic` from `acrylblends/bun`.
 
-> **Not yet available.** The Bun adapter, `acrylblends/bun`, is not part of acrylblends yet. The code below shows the planned usage.
-
 ```ts
 import { serveStatic } from 'acrylblends/bun'
 

package/docs/framework/getting-started/cloudflare-pages.md

@@ -0,0 +1,53 @@
+# Cloudflare Pages
+
+Cloudflare Pages Functions run code next to a static site. `handle(app)` from `acrylblends/cloudflare-pages` turns an Acryl app into a Pages Function, and `handleMiddleware` turns a middleware into a Pages middleware.
+
+> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a Pages event context. It has not been deployed to Cloudflare by the ACRYL team. Cloudflare recommends Workers with static assets for new projects (see [Cloudflare Workers](cloudflare-workers.md)).
+
+## A catch-all function
+
+Put the file in `functions/[[route]].ts` so it answers every path that is not a static file:
+
+```ts
+import { Acryl } from 'acrylblends'
+import { handle } from 'acrylblends/cloudflare-pages'
+
+const app = new Acryl().basePath('/api')
+
+app.get('/hello', (c) => c.json({ message: 'Hello from Pages Functions' }))
+
+export const onRequest = handle(app)
+```
+
+`basePath('/api')` is for a function at `functions/api/[[route]].ts`.
+
+## The event context and the bindings
+
+The Pages event context (`env`, `params`, `data`, `waitUntil`, `next`) is `c.env.eventContext`; the environment bindings are `c.env` as in Workers:
+
+```ts
+import { Acryl } from 'acrylblends'
+import type { EventContext } from 'acrylblends/cloudflare-pages'
+
+type Bindings = { MY_KV: unknown; eventContext: EventContext }
+
+const app = new Acryl<{ Bindings: Bindings }>()
+
+app.get('/params', (c) => c.json(c.env.eventContext.params))
+```
+
+## Middleware
+
+```ts
+import { handleMiddleware } from 'acrylblends/cloudflare-pages'
+
+// functions/_middleware.ts
+export const onRequest = handleMiddleware(async (c, next) => {
+  await next()
+  c.res.headers.set('x-checked', 'yes')
+})
+```
+
+## Static files
+
+In [advanced mode](https://developers.cloudflare.com/pages/platform/functions/advanced-mode/) (a `_worker.js` that answers every request), `serveStatic()` from `acrylblends/cloudflare-pages` answers a request from the Pages `ASSETS` binding and falls through to the app's not-found handler when there is no such file. The client's address is available through the [ConnInfo helper](../helpers/conninfo.md).

package/docs/framework/getting-started/cloudflare-workers.md

@@ -0,0 +1,67 @@
+# Cloudflare Workers
+
+A Cloudflare Worker is a module that exports a `fetch` handler, which is what an Acryl app has: `export default app` is a Worker. The adapter `acrylblends/cloudflare-workers` adds the pieces that need Cloudflare: the client's address, WebSockets, and (deprecated) serving static files from Workers KV.
+
+> **Status.** The adapter is the upstream adapter ported with its test suite, and a Worker with these routes (`export default app`, bindings from `vars`, `getConnInfo`, `waitUntil`) has been run in `workerd` with `wrangler dev --local`, which needs no Cloudflare account. The ACRYL team has not deployed to Cloudflare itself: run `wrangler dev` first.
+
+## A Worker
+
+```ts
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/', (c) => c.text('Hello Cloudflare Workers!'))
+
+export default app
+```
+
+With Wrangler: a `wrangler.jsonc` naming the entry file and a compatibility date (`"main": "src/index.ts"`, `"compatibility_date": "2026-01-01"`), then `npx wrangler dev` to run it locally and `npx wrangler deploy` to publish it.
+
+## Bindings and the execution context
+
+Environment variables, secrets, KV namespaces, D1 databases and R2 buckets arrive as `c.env`; the `ExecutionContext` is `c.executionCtx`:
+
+```ts
+import { Acryl } from 'acrylblends'
+
+type Bindings = {
+  MY_SECRET: string
+}
+
+const app = new Acryl<{ Bindings: Bindings }>()
+
+app.get('/', (c) => {
+  c.executionCtx.waitUntil(Promise.resolve()) // work that may finish after the response
+  return c.text(c.env.MY_SECRET ? 'configured' : 'missing')
+})
+
+export default app
+```
+
+## The client's address
+
+```ts
+import { Acryl } from 'acrylblends'
+import { getConnInfo } from 'acrylblends/cloudflare-workers'
+
+const app = new Acryl()
+
+app.get('/ip', (c) => c.text(getConnInfo(c).remote.address ?? 'unknown'))
+
+export default app
+```
+
+It reads the `cf-connecting-ip` header that Cloudflare sets. See the [ConnInfo helper](../helpers/conninfo.md).
+
+## WebSockets
+
+`upgradeWebSocket` from `acrylblends/cloudflare-workers` accepts the upgrade with Cloudflare's `WebSocketPair`. Cloudflare does not give an `onOpen` event. See the [WebSocket helper](../helpers/websocket.md).
+
+## Static files
+
+Prefer Cloudflare's static assets (the `assets` setting of Wrangler), which serve files before your code runs. `serveStatic` from `acrylblends/cloudflare-workers`, which reads files from Workers KV (`__STATIC_CONTENT`), is deprecated by Cloudflare's move to static assets and is kept for existing Workers Sites projects. Cloudflare Pages is the other option: see [Cloudflare Pages](cloudflare-pages.md).
+
+## Service Worker syntax
+
+A Worker written in the old non-module syntax (`addEventListener('fetch', ...)`) uses `fire` from `acrylblends/service-worker`: see [Service Worker](service-worker.md).

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,31 @@
+# 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 no-check
+import { Acryl } from 'acrylblends'
+import { handle } from 'acrylblends/service-worker'
+
+const app = new Acryl()
+
+app.get('/offline', (c) => c.text('Served by the Service Worker'))
+
+addEventListener('fetch', handle(app, { fetch: globalThis.fetch }))
+```
+
+`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 (`node:sqlite`), 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, 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/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/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": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
   },
-  "files": 91,
-  "digest": "sha256:ea881fe758d9d9add8a8d3837f1dddc6938c3e021cb4ea5f1ce5cfb31af7ef2c"
+  "files": 98,
+  "digest": "sha256:396f882ac7b612455edc59961c52472fadc5f95ea1a778208e7edd860e4e6727"
 }