acrylblends 1.0.0-rc.1 → 1.0.0

package/README.md

@@ -4,13 +4,14 @@
 
 <h1 align="center">acrylblends</h1>
 
-<p align="center"><strong>Acryl, a small web framework on Web Standards, for Node.js.</strong><br>
-One <code>Request</code> in, one <code>Response</code> out: routing, middleware, validation, a typed client and a Node.js server, with no dependencies.</p>
+<p align="center"><strong>Acryl: a small web framework on Web Standards, and whole apps built from Cordis plugins.</strong><br>
+One <code>Request</code> in, one <code>Response</code> out - routing, middleware, validation, a typed client and a Node.js server, with no
+dependencies - and a composition of plugins that runs in a browser or a desktop window.</p>
 
 <p align="center">
-  <a href="https://github.com/acryldev/acryl/blob/main/docs/framework/README.md">Documentation</a> ·
-  <a href="https://github.com/acryldev/acryl/blob/main/docs/framework/getting-started/basic.md">Getting started</a> ·
-  <a href="https://github.com/acryldev/acryl/blob/main/docs/framework/api/index.md">API</a> ·
+  <a href="https://github.com/acrylblends/acrylblends/blob/main/docs/framework/README.md">Documentation</a> ·
+  <a href="https://github.com/acrylblends/acrylblends/blob/main/docs/framework/getting-started/basic.md">Getting started</a> ·
+  <a href="https://github.com/acrylblends/acrylblends/blob/main/docs/framework/api/index.md">API</a> ·
   <a href="https://acrylblends.github.io">acrylblends.github.io</a> ·
   <a href="https://acryl.dev">acryl.dev</a> ·
   <a href="https://github.com/acrylblends/acrylblends">GitHub</a>
@@ -30,8 +31,12 @@ export default app
 ## Contents
 
 - [Requirements](#requirements)
-- [Quick start](#quick-start)
-- [Start from a template](#start-from-a-template)
+- [Start an app in five minutes](#start-an-app-in-five-minutes)
+- [Run it in a browser or in a desktop window](#run-it-in-a-browser-or-in-a-desktop-window)
+- [Start from the registry](#start-from-the-registry)
+- [Publish your app, or your own starter](#publish-your-app-or-your-own-starter)
+- [Keep the framework current](#keep-the-framework-current)
+- [Use it as a library](#use-it-as-a-library)
 - [A first API](#a-first-api)
 - [Middleware](#middleware)
 - [Validation](#validation)
@@ -39,7 +44,7 @@ export default app
 - [Testing](#testing)
 - [Serving on Node.js](#serving-on-nodejs)
 - [What is in the package](#what-is-in-the-package)
-- [Upgrading from 0.4](#upgrading-from-04)
+- [Upgrading from an older version](#upgrading-from-an-older-version)
 - [The acrylblends command](#the-acrylblends-command)
 - [Links](#links)
 - [License](#license)
@@ -50,9 +55,93 @@ export default app
 - **Bun** runs the same app (`export default app`) and is experimental.
 - `acrylblends` has no dependencies. Its types need only Node's types (`@types/node`), not the DOM library.
 
-## Quick start
+## Start an app in five minutes
 
-Create a folder and install the package:
+```sh
+npm create acrylblends@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+The starter asks which template you want; naming one skips the question (`npm create acrylblends@latest my-app notes`).
+
+| Template | What you get |
+| --- | --- |
+| `blank` | the router, the Node server and one route: the smallest app |
+| `nodejs` | a page rendered with JSX and a client component, without a bundler |
+| `notes` | a multi-user notes app on the `db` port: sign-up, sessions, migrations, search, a typed client |
+| `chat` | an answer streamed over server-sent events from an OpenAI-compatible API, history in SQLite |
+| `todo` | a to-do list on the router and live state |
+| `agent` | the blank app with an agent that writes and installs plugins into the running app |
+
+Every template is a Cordis app: `blend.yaml` lists its plugins, `plugins/` holds them as code you own, and the starter also writes
+`docs/framework` (the pages this README links to), `AGENTS.md`, `CLAUDE.md`, one skill for a coding agent, and its own tests. `npm run dev`
+serves it and prints the URL, `npm test` runs the tests, `npm run check` type-checks.
+
+Adding a capability is one command: `npx acrylblends add <plugin>` copies a library plugin and what it needs into `plugins/`, prints the row to
+add to `blend.yaml`, and records what it copied so `acrylblends upgrade` can move it forward later. `npx acrylblends plugins` lists the library.
+
+## Run it in a browser or in a desktop window
+
+The same app runs both ways; the routes, the plugins and the data are the ones you already wrote.
+
+- **Browser**: what you get. `npm run dev` (or `npm start`) serves it on a loopback port and prints the URL.
+- **Desktop**: add the shell and run it as a window on the app's own server.
+
+```sh
+npx acrylblends init my-app --desktop            # create an app with the shell (--template picks the template)
+# or, in an app you already have:
+npx acrylblends add desktop
+npm install                                      # the shell needs electron
+npm run desktop                                  # an Electron window on the app's own server
+```
+
+Every Electron call lives in `plugins/desktop`, so the app's own code never imports it. See
+[Desktop](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/getting-started/desktop.md).
+
+## Start from the registry
+
+The registry is a set of starting points people published, browsable at [acrylblends.github.io/blends](https://acrylblends.github.io/blends)
+and readable by any tool as plain JSON at <https://acrylblends.github.io/registry/index.json>. ACRYL's CLI pulls one by id, or from any git
+repository:
+
+```sh
+npm install -g acryl
+acryl new my-app --from acryl.gtd               # a starter from the registry
+acryl new my-app --from github:you/starter      # a repository with an acryl.template.json
+```
+
+Without `--from`, `acryl new` writes the blank app; `--blueprint` picks another built-in Blueprint. A team's own registry is the same layout in
+its own repository: `--registry <git URL or folder>` reads starters from there instead of the public one.
+
+## Publish your app, or your own starter
+
+**Your app** belongs to you and lives in your repository: `npm run save` commits it and pushes to its remote. It refuses a file that looks like
+a secret, and refuses to push a private app to a public remote.
+
+Before an app goes on a server: with `NODE_ENV=production` the door, the agent panel and the PTY driver start nothing, but the `agent` template
+still mounts its own agent, builder and extensions rows. Start from one of the other five templates, or remove those rows from its `blend.yaml`
+- see [What runs in production](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/guides/production.md).
+
+**A starter** other people can pull is a pull request to the registry repository: add `registry/blends/<id>/` with a `blend.yaml` (`kind: Blueprint`,
+an id you own, the license, `visibility`, a category and a one-line description), the plugins it adds under `plugins/`, and a `README.md`. CI
+validates every entry and fails when `index.json` is stale, so what the site lists is what passed. The layout, and how to keep a starter private
+without a registry at all, is in
+[the registry README](https://github.com/acrylblends/acrylblends.github.io/tree/main/registry).
+
+## Keep the framework current
+
+An app carries its framework plugins as source, so a new release moves them in place and leaves your own code alone:
+
+```sh
+npx acrylblends upgrade --dry-run   # the plan: what would be replaced
+npx acrylblends upgrade             # an edited file stops it with the diff, unless --force
+```
+
+## Use it as a library
+
+An Acryl app is also a plain function from `Request` to `Response`, which needs no scaffold. Create a folder and install the package:
 
 ```sh
 mkdir my-app && cd my-app
@@ -90,21 +179,9 @@ Run it and open http://localhost:3000:
 node server.ts
 ```
 
-For Bun, `bun run index.ts` serves the same `export default app`.
-
-## Start from a template
-
-`create-acrylblends` creates a ready project with `dev`, `test` and `start` scripts:
-
-```sh
-npm create acrylblends@latest my-app
-cd my-app
-npm install
-npm run dev
-```
-
-The templates are the same through `npm create acrylblends` and `acrylblends init`: `blank`, `nodejs`, `notes`, `chat`, `todo` and `agent` (a Cordis app with an agent that can extend it while it runs; `acryl-app` is its old name). See the
-[create-acrylblends guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/create-acrylblends.md).
+For Bun, `bun run index.ts` serves the same `export default app`. The same app mounts inside a Cordis plugin with
+`ctx.router.route(prefix, app)`, which is how a generated app is put together: see
+[Acryl in a Cordis app](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/cordis/acryl-in-a-cordis-app.md).
 
 ## A first API
 
@@ -138,10 +215,10 @@ app.onError((error, c) => error instanceof HTTPException ? error.getResponse() :
 export default app
 ```
 
-Read more: [Routing](https://github.com/acryldev/acryl/blob/main/docs/framework/api/routing.md),
-[Context](https://github.com/acryldev/acryl/blob/main/docs/framework/api/context.md),
-[Request](https://github.com/acryldev/acryl/blob/main/docs/framework/api/request.md),
-[Exceptions](https://github.com/acryldev/acryl/blob/main/docs/framework/api/exception.md).
+Read more: [Routing](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/api/routing.md),
+[Context](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/api/context.md),
+[Request](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/api/request.md),
+[Exceptions](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/api/exception.md).
 
 ## Middleware
 
@@ -165,8 +242,8 @@ app.use('/admin/*', bearerAuth({ token: process.env.ADMIN_TOKEN ?? '' }))
 Built in: `basic-auth`, `bearer-auth`, `body-limit`, `combine`, `compress`, `context-storage`, `cors`, `csrf`, `etag`, `ip-restriction`,
 `jwk`, `jwt`, `language`, `logger`, `method-not-allowed`, `method-override`, `powered-by`, `pretty-json`, `request-id`, `secure-headers`,
 `serve-static`, `timeout`, `timing`, `trailing-slash`, plus ACRYL's `loopback-only`. Each one is documented under
-[Middleware](https://github.com/acryldev/acryl/tree/main/docs/framework/middleware/builtin). To write your own, see the
-[middleware guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/middleware.md).
+[Middleware](https://github.com/acrylblends/acrylblends/tree/main/docs/framework/middleware/builtin). To write your own, see the
+[middleware guide](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/guides/middleware.md).
 
 ## Validation
 
@@ -191,7 +268,7 @@ app.post(
 ```
 
 `acrylblends/schema-validator` drives the same validator with any [Standard Schema](https://standardschema.dev) library (Zod, Valibot,
-ArkType and others). See the [validation guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/validation.md).
+ArkType and others). See the [validation guide](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/guides/validation.md).
 
 ## Typed client
 
@@ -216,7 +293,7 @@ const answer = await client.api.hello.$get()
 console.log((await answer.json()).message)
 ```
 
-See [RPC](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/rpc.md).
+See [RPC](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/guides/rpc.md).
 
 ## Testing
 
@@ -235,7 +312,7 @@ test('GET / says hello', async () => {
 ```
 
 Run it with `node --test`. `acrylblends/testing` adds `testClient`, the typed client over `app.request()`. See the
-[testing guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/testing.md).
+[testing guide](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/guides/testing.md).
 
 ## Serving on Node.js
 
@@ -256,7 +333,7 @@ const server = serve({ fetch: app.fetch, port: 3000, hostname: '127.0.0.1' })
 process.on('SIGTERM', () => { server.close() })
 ```
 
-See [Node.js](https://github.com/acryldev/acryl/blob/main/docs/framework/getting-started/nodejs.md).
+See [Node.js](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/getting-started/nodejs.md).
 
 ## What is in the package
 
@@ -266,20 +343,20 @@ See [Node.js](https://github.com/acryldev/acryl/blob/main/docs/framework/getting
 | `acrylblends/<middleware>` | each built-in middleware, for example `acrylblends/cors` |
 | `acrylblends/validator`, `acrylblends/schema-validator` | request validation |
 | `acrylblends/client`, `acrylblends/testing` | the typed client and its in-process test version |
-| `acrylblends/accepts`, `adapter`, `cookie`, `factory`, `html`, `route`, `streaming`, `ws`, `conninfo` | helpers ([helpers docs](https://github.com/acryldev/acryl/tree/main/docs/framework/helpers)) |
+| `acrylblends/accepts`, `adapter`, `cookie`, `factory`, `html`, `route`, `streaming`, `ws`, `conninfo` | helpers ([helpers docs](https://github.com/acrylblends/acrylblends/tree/main/docs/framework/helpers)) |
 | `acrylblends/http-exception` | `HTTPException` |
-| `acrylblends/router/*` | the routers: `reg-exp-router`, `smart-router`, `trie-router`, `pattern-router`, `linear-router` ([routers](https://github.com/acryldev/acryl/blob/main/docs/framework/concepts/routers.md)) |
-| `acrylblends/tiny`, `acrylblends/quick` | the presets: `Acryl` with another router (`PatternRouter`; `LinearRouter` and `TrieRouter`) ([presets](https://github.com/acryldev/acryl/blob/main/docs/framework/api/presets.md)) |
+| `acrylblends/router/*` | the routers: `reg-exp-router`, `smart-router`, `trie-router`, `pattern-router`, `linear-router` ([routers](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/concepts/routers.md)) |
+| `acrylblends/tiny`, `acrylblends/quick` | the presets: `Acryl` with another router (`PatternRouter`; `LinearRouter` and `TrieRouter`) ([presets](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/api/presets.md)) |
 | `acrylblends/cache`, `acrylblends/mount` | the cache middleware and mounting another framework's fetch handler |
-| `acrylblends/ssg` | static site generation: `toSSG` writes every route as a file ([SSG helper](https://github.com/acryldev/acryl/blob/main/docs/framework/helpers/ssg.md)) |
+| `acrylblends/ssg` | static site generation: `toSSG` writes every route as a file ([SSG helper](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/helpers/ssg.md)) |
 | `acrylblends/proxy`, `acrylblends/dev` | the proxy helper and the dev helpers (`showRoutes`, `inspectRoutes`, `getRouterName`) |
-| `acrylblends/jsx` | JSX on the server: `jsxImportSource: 'acrylblends/jsx'`, `.tsx` files run on Node with `node --import acrylblends/node-server/register`, with `jsx/streaming`, and `acrylblends/jsx-renderer` for a layout behind `c.render` ([JSX guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/jsx.md)) |
-| `acrylblends/jsx/dom` | JSX in the browser: hooks and `render` (needs the DOM library) ([client components](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/jsx-dom.md)); on Node, `clientModules` serves them to the browser without a bundler ([guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/client-modules.md)) |
+| `acrylblends/jsx` | JSX on the server: `jsxImportSource: 'acrylblends/jsx'`, `.tsx` files run on Node with `node --import acrylblends/node-server/register`, with `jsx/streaming`, and `acrylblends/jsx-renderer` for a layout behind `c.render` ([JSX guide](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/guides/jsx.md)) |
+| `acrylblends/jsx/dom` | JSX in the browser: hooks and `render` (needs the DOM library) ([client components](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/guides/jsx-dom.md)); on Node, `clientModules` serves them to the browser without a bundler ([guide](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/guides/client-modules.md)) |
 | `acrylblends/drivers` | the driver contract of the agent panel (`ChatDriver`, `TerminalDriver`, `Drivers`), for plugins that add an agent to the panel |
-| `acrylblends/css` | CSS in JSX: `css`, `cx`, `keyframes`, `Style` ([CSS helper](https://github.com/acryldev/acryl/blob/main/docs/framework/helpers/css.md)) |
+| `acrylblends/css` | CSS in JSX: `css`, `cx`, `keyframes`, `Style` ([CSS helper](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/helpers/css.md)) |
 | `acrylblends/node-server` | `serve`, `createAdaptorServer`, `getRequestListener`; with `node-server/serve-static`, `node-server/conninfo`, and `node-server/register` (compiles `.tsx` with the app's `typescript`); `clientModules` and `buildClientModules` (client components without a bundler) |
 
-Every subpath in the table is listed in the package's `exports` and is covered by semver from 1.0, except the ones marked experimental: `acrylblends/bun` and the door (`door/*`, `cordis/door`), which are development tools. The ported core's utilities (`utils/*`) and the base-class chunk are internal and not exported. Node.js is the runtime the package is verified on; the upstream's adapters for AWS Lambda, Lambda@Edge, Cloudflare, Vercel, Netlify and Service Workers are not part of the package ([Other runtimes](https://github.com/acryldev/acryl/blob/main/docs/framework/getting-started/other-runtimes.md)).
+Every subpath in the table is listed in the package's `exports` and is covered by semver from 1.0, except the ones marked experimental: `acrylblends/bun` and the door (`door/*`, `cordis/door`), which are development tools. The ported core's utilities (`utils/*`) and the base-class chunk are internal and not exported. Node.js is the runtime the package is verified on; the upstream's adapters for AWS Lambda, Lambda@Edge, Cloudflare, Vercel, Netlify and Service Workers are not part of the package ([Other runtimes](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/getting-started/other-runtimes.md)).
 
 To extend the context's typed variables, augment the root module:
 
@@ -291,11 +368,14 @@ declare module 'acrylblends' {
 }
 ```
 
-## Upgrading from 0.4
+## Upgrading from an older version
+
+An app made with any 0.9.1 or later release moves with `acrylblends upgrade` (above); its edited files are never replaced silently.
 
-From 0.5 the package's root is the framework. `App` and `AppRequest`, the 0.4 names, were kept as deprecated aliases of `Acryl` and
-`AcrylRequest` and are removed in 1.0. The scaffolding API that was the root in 0.4 is now `acrylblends/cli`. See
-[Migration from 0.4](https://github.com/acryldev/acryl/blob/main/docs/framework/cordis/migration-from-0-4.md).
+Code that imports the old names moves by hand: `App` and `AppRequest`, the 0.4 aliases of `Acryl` and `AcrylRequest`, are removed in 1.0, and
+the scaffolding API that was the package root in 0.4 is now `acrylblends/cli`. See
+[Migration to 1.0](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/cordis/migration-to-1-0.md) and
+[Migration from 0.4](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/cordis/migration-from-0-4.md).
 
 ## The acrylblends command
 
@@ -309,18 +389,18 @@ cd my-app && npm install && npm run dev
 ```
 
 See the [ACRYLBLENDS documentation](https://github.com/acrylblends/acrylblends/blob/main/docs/README.md) and
-[Acryl in a Cordis app](https://github.com/acryldev/acryl/blob/main/docs/framework/cordis/acryl-in-a-cordis-app.md).
+[Acryl in a Cordis app](https://github.com/acrylblends/acrylblends/blob/main/docs/framework/cordis/acryl-in-a-cordis-app.md).
 
 ## Links
 
 | | |
 | --- | --- |
-| Framework documentation | https://github.com/acryldev/acryl/blob/main/docs/framework/README.md |
+| Framework documentation | https://github.com/acrylblends/acrylblends/blob/main/docs/framework/README.md |
 | ACRYLBLENDS website | https://acrylblends.github.io |
 | ACRYL website | https://acryl.dev |
 | This package's source and issues | https://github.com/acrylblends/acrylblends ([issues](https://github.com/acrylblends/acrylblends/issues)) |
 | The framework's source | https://github.com/acryldev/acryl (`plugins/acryl-router`, `plugins/acryl-node-server`) |
-| For coding agents | https://github.com/acryldev/acryl/blob/main/docs/framework/agents/index.md |
+| For coding agents | https://github.com/acrylblends/acrylblends/blob/main/docs/framework/agents/index.md |
 | npm | https://www.npmjs.com/package/acrylblends |
 
 ## License

package/docs/framework/api/acryl.md

@@ -64,25 +64,13 @@ app.onError((err, c) => {
 
 ## fire()
 
-> **Warning.** **`app.fire()` is deprecated**, and the Service Worker adapter (`acrylblends/service-worker`) is not part of the package in 1.0. Use `app.fetch` in a `fetch` event handler of your own.
-
-`app.fire()` automatically adds a global `fetch` event listener.
-
-This can be useful for environments that adhere to the [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API), such as [non-ES module Cloudflare Workers](https://developers.cloudflare.com/workers/reference/migrate-to-module-workers/).
-
-`app.fire()` executes the following for you:
-
-```ts
-addEventListener('fetch', (event: FetchEventLike): void => {
-  event.respondWith(this.dispatch(...))
-})
-```
+> **Warning.** **`app.fire()` is deprecated**, and the Service Worker adapter is not part of the package in 1.0. It adds a global `fetch` event listener, which only a Service Worker-style host reads; use `app.fetch` in an entry point of your own instead.
 
 ## fetch()
 
 `app.fetch` will be the entry point of your application.
 
-For Cloudflare Workers, you can use the following:
+As the `fetch` method of an object a host calls:
 
 ```ts twoslash
 import { Acryl } from 'acrylblends'
@@ -230,7 +218,7 @@ const app = new Acryl({ router: new RegExpRouter() })
 
 ## Generics
 
-You can pass Generics to specify the types of Cloudflare Workers Bindings and variables used in `c.set`/`c.get`.
+You can pass Generics to specify the type of the environment the host passes and the variables used in `c.set`/`c.get`.
 
 ```ts twoslash
 import { Acryl } from 'acrylblends'

package/docs/framework/api/context.md

@@ -362,81 +362,32 @@ app.get('/pages/my-hobbies', (c) => {
 
 ## executionCtx
 
-You can access Cloudflare Workers' specific [ExecutionContext](https://developers.cloudflare.com/workers/runtime-apis/context/).
+A host that embeds the app can pass an execution context: `waitUntil(promise)` keeps work alive after the response has been sent, and `passThroughOnException()` lets the host take over when the handler throws. The Node server passes none, so read it only in an app whose host provides one.
 
 ```ts twoslash
 import { Acryl } from 'acrylblends'
-const app = new Acryl<{
-  Bindings: {
-    KV: any
-  }
-}>()
-declare const key: string
-declare const data: string
-// ---cut---
-// ExecutionContext object
-app.get('/foo', async (c) => {
-  c.executionCtx.waitUntil(c.env.KV.put(key, data))
-  // ...
-})
-```
-
-The `ExecutionContext` also has an [`exports`](https://developers.cloudflare.com/workers/runtime-apis/context/#exports) field. To get autocomplete with Wrangler's generated types, you can use module augmentation:
-
-```ts
-import 'acrylblends'
-
-declare module 'acrylblends' {
-  interface ExecutionContext {
-    readonly exports: Cloudflare.Exports
-  }
-}
-```
-
-## event
-
-You can access Cloudflare Workers' specific `FetchEvent`. This was used in "Service Worker" syntax. But, it is not recommended now.
-
-```ts twoslash
-import { Acryl } from 'acrylblends'
-declare const key: string
-declare const data: string
-type KVNamespace = any
+const app = new Acryl()
+declare const sendReceipt: Promise<void>
 // ---cut---
-// Type definition to make type inference
-type Bindings = {
-  MY_KV: KVNamespace
-}
-
-const app = new Acryl<{ Bindings: Bindings }>()
-
-// FetchEvent object (only set when using Service Worker syntax)
-app.get('/foo', async (c) => {
-  c.event.waitUntil(c.env.MY_KV.put(key, data))
-  // ...
+// Work that must finish after the response, when the host provides a context
+app.get('/orders/:id', async (c) => {
+  c.executionCtx.waitUntil(sendReceipt)
+  return c.json({ ok: true })
 })
 ```
 
 ## env
 
-In Cloudflare Workers Environment variables, secrets, KV namespaces, D1 database, R2 bucket etc. that are bound to a worker are known as bindings.
-Regardless of type, bindings are always available as global variables and can be accessed via the context `c.env.BINDING_KEY`.
+`c.env` is the environment the host hands the app. The Node server passes `process.env`, so `c.env.MY_KEY` is the variable `MY_KEY`. A host that passes something else gives the app a type parameter, and then `c.env` is that shape.
 
 ```ts twoslash
 import { Acryl } from 'acrylblends'
-type KVNamespace = any
 // ---cut---
-// Type definition to make type inference
-type Bindings = {
-  MY_KV: KVNamespace
-}
+const app = new Acryl<{ Bindings: { REGION: string } }>()
 
-const app = new Acryl<{ Bindings: Bindings }>()
-
-// Environment object for Cloudflare Workers
-app.get('/', async (c) => {
-  c.env.MY_KV.get('my-key')
-  // ...
+app.get('/', (c) => {
+  const region = c.env.REGION
+  return c.text(region)
 })
 ```
 

package/docs/framework/api/presets.md

@@ -57,6 +57,6 @@ this.router = new PatternRouter()
 
 | Preset       | Suitable platforms                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `acrylblends`       | This is highly recommended for most use cases. Although the registration phase may be slower than `acrylblends/quick`, it exhibits high performance once booted. It's ideal for long-life servers built with **Deno**, **Bun**, or **Node.js**. It is also suitable for **Fastly Compute**, as route registration occurs during the app build phase on that platform. For environments such as **Cloudflare Workers**, **Deno Deploy**, where v8 isolates are utilized, this preset is suitable as well because the isolations persist for a certain amount of time after booting. |
+| `acrylblends`       | This is highly recommended for most use cases. Although the registration phase may be slower than `acrylblends/quick`, it exhibits high performance once booted. It's ideal for a long-life server on **Node.js** (the verified runtime) or **Bun** (experimental). |
 | `acrylblends/quick` | This preset is designed for environments where the application is initialized for every request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `acrylblends/tiny`  | This is the smallest router package and it's suitable for environments where resources are limited.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

package/docs/framework/api/request.md

@@ -364,9 +364,9 @@ app.get('/about/me', async (c) => {
 The raw [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object.
 
 ```ts
-// For Cloudflare Workers
-app.post('/', async (c) => {
-  const metadata = c.req.raw.cf?.hostMetadata?
+// Hand the raw Request to an API that takes one, such as a Web-standard parser
+app.post('/upload', async (c) => {
+  const bytes = await c.req.raw.arrayBuffer()
   // ...
 })
 ```

package/docs/framework/concepts/web-standard.md

@@ -4,8 +4,8 @@ Acryl uses only **Web Standards** like Fetch.
 They were originally used in the `fetch` function and consist of basic objects that handle HTTP requests and responses.
 In addition to `Requests` and `Responses`, there are `URL`, `URLSearchParam`, `Headers` and others.
 
-Cloudflare Workers, Deno, and Bun also are built upon Web Standards.
-For example, a server that returns "Hello World" could be written as below. This could run on Cloudflare Workers and Bun.
+Bun is built on Web Standards the same way.
+For example, a server that returns "Hello World" can be written as below, and it runs on Node.js and Bun.
 
 ```ts twoslash
 export default {

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

@@ -277,7 +277,7 @@ export default function App() {
 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.
+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`.
 
 ```json
 {

package/docs/framework/guides/rpc.md

@@ -584,21 +584,13 @@ const route = app.put(
 
 ## Custom `fetch` method
 
-You can set the custom `fetch` method.
-
-In the following example script for Cloudflare Worker, the Service Bindings' `fetch` method is used instead of the default `fetch`.
-
-```toml
-# wrangler.toml
-services = [
-  { binding = "AUTH", service = "auth-service" },
-]
-```
+You can set the custom `fetch` method: anything with the `fetch` signature works in place of the global one, such as a client that adds a header or a test double.
 
 ```ts
 // src/client.ts
 const client = hc<CreateProfileType>('http://localhost', {
-  fetch: c.env.AUTH.fetch.bind(c.env.AUTH),
+  fetch: (input, init) =>
+    fetch(input, { ...init, headers: { ...init?.headers, authorization: `Bearer ${token}` } }),
 })
 ```
 

package/docs/framework/helpers/adapter.md

@@ -1,6 +1,6 @@
 # Adapter Helper
 
-The Adapter Helper provides a seamless way to interact with various platforms through a unified interface.
+The Adapter Helper reads an app's environment the same way on every runtime it runs on.
 
 ## Import
 
@@ -11,50 +11,25 @@ import { env, getRuntimeKey } from 'acrylblends/adapter'
 
 ## `env()`
 
-The `env()` function facilitates retrieving environment variables across different runtimes, extending beyond just Cloudflare Workers' Bindings. The value that can be retrieved with `env(c)` may be different for each runtime.
+The `env()` function returns the environment the host gives the app. On Node.js, the verified runtime, that is `process.env`; on Bun it is `Bun.env` (and `process.env`), and the two entries a `.env` file adds are there as well. A host that passes its own environment to `app.fetch(request, env)` gets that instead.
 
 ```ts
 import { env } from 'acrylblends/adapter'
 
 app.get('/env', (c) => {
-  // NAME is process.env.NAME on Node.js or Bun
-  // NAME is the value written in `wrangler.toml` on Cloudflare
+  // NAME is process.env.NAME on Node.js and Bun
   const { NAME } = env<{ NAME: string }>(c)
   return c.text(NAME)
 })
 ```
 
-Supported Runtimes, Serverless Platforms and Cloud Services:
-
-- Cloudflare Workers
-  - `wrangler.toml`
-  - `wrangler.jsonc`
-- Deno
-  - [`Deno.env`](https://docs.deno.com/runtime/manual/basics/env_variables)
-  - `.env` file
-- Bun
-  - [`Bun.env`](https://bun.com/guides/runtime/set-env)
-  - `process.env`
-- Node.js
-  - `process.env`
-- Vercel
-  - [Environment Variables on Vercel](https://vercel.com/docs/projects/environment-variables)
-- AWS Lambda
-  - [Environment Variables on AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/samples-blank.html#samples-blank-architecture)
-- Lambda@Edge\
-  Environment Variables on Lambda are [not supported](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html) by Lambda@Edge, you need to use [Lambda@Edge event](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/lambda-event-structure.html) as an alternative.
-- Fastly Compute\
-  On Fastly Compute, you can use the ConfigStore to manage user-defined data.
-- Netlify\
-  On Netlify, you can use the [Netlify Contexts](https://docs.netlify.com/site-deploys/overview/#deploy-contexts) to manage user-defined data.
-
 ### Specify the runtime
 
-You can specify the runtime to get environment variables by passing the runtime key as the second argument.
+`env()` reads the runtime itself. Pass the runtime key as the second argument when a host embeds the app and detects it differently, or in a test that fixes the key:
 
 ```ts
 app.get('/env', (c) => {
-  const { NAME } = env<{ NAME: string }>(c, 'workerd')
+  const { NAME } = env<{ NAME: string }>(c, 'node')
   return c.text(NAME)
 })
 ```
@@ -65,23 +40,18 @@ The `getRuntimeKey()` function returns the identifier of the current runtime.
 
 ```ts
 app.get('/', (c) => {
-  if (getRuntimeKey() === 'workerd') {
-    return c.text('You are on Cloudflare')
-  } else if (getRuntimeKey() === 'bun') {
+  if (getRuntimeKey() === 'bun') {
     return c.text('You are on Bun')
   }
-  ...
+  return c.text(`You are on ${getRuntimeKey()}`)
 })
 ```
 
-### Available Runtimes Keys
+### Available runtime keys
 
-Here are the available runtimes keys, unavailable runtime key runtimes may be supported and labeled as `other`, with some being inspired by [WinterCG's Runtime Keys](https://runtime-keys.proposal.wintercg.org/):
+The keys follow [WinterCG's Runtime Keys proposal](https://runtime-keys.proposal.wintercg.org/):
 
-- `workerd` - Cloudflare Workers
-- `deno`
-- `bun`
-- `node`
-- `edge-light` - Vercel Edge Functions
-- `fastly` - Fastly Compute
-- `other` - Other unknown runtimes keys
+- `node` - Node.js, the verified runtime
+- `bun` - Bun, experimental
+- `deno`, `workerd`, `edge-light`, `fastly` - keys the helper still recognizes for a host that embeds an app in that runtime; 1.0 ships no adapter for them (see [Other runtimes](../getting-started/other-runtimes.md))
+- `other` - a runtime the helper does not recognize

package/docs/framework/helpers/streaming.md

@@ -47,7 +47,7 @@ app.get('/streamText', (c) => {
 
 **Warning.**
 
-If you are developing an application for Cloudflare Workers, streaming may not work well on Wrangler. If so, add `Identity` for `Content-Encoding` header.
+A proxy or a host that compresses the response body can hold a stream back until it ends. If a stream arrives only when it is complete, send `Content-Encoding: Identity` for that route.
 
 ```ts
 app.get('/streamText', (c) => {

package/docs/framework/middleware/builtin/basic-auth.md

@@ -1,7 +1,7 @@
 # Basic Auth Middleware
 
 This middleware can apply Basic authentication to a specified path.
-Implementing Basic authentication with Cloudflare Workers or other platforms is more complicated than it seems, but with this middleware, it's a breeze.
+Implementing Basic authentication by hand is more complicated than it seems, but with this middleware, it's a breeze.
 
 For more information about how the Basic auth scheme works under the hood, see the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme).
 

package/docs/framework/middleware/builtin/cache.md

@@ -2,11 +2,7 @@
 
 The Cache middleware uses the Web Standards' [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache).
 
-The Cache middleware currently supports Cloudflare Workers projects using custom domains and Deno projects using [Deno 1.26+](https://github.com/denoland/deno/releases/tag/v1.26.0). Also available with Deno Deploy.
-
-Cloudflare Workers respects the `Cache-Control` header and return cached responses. For details, refer to [Cache on Cloudflare Docs](https://developers.cloudflare.com/workers/runtime-apis/cache/). Deno does not respect headers, so if you need to update the cache, you will need to implement your own mechanism.
-
-See [Usage](#usage) below for instructions on each platform.
+It needs a Cache API on the host: the middleware reads `globalThis.caches`. Node.js, the verified runtime, does not provide one, so on Node the middleware is not enabled and says so in one line; a host that embeds an app in a runtime with a Cache API (or provides `globalThis.caches` itself) gets it. `Cache-Control` handling and the QUERY-request cache below are implemented by the middleware, not by the platform.
 
 ## Import
 
@@ -17,28 +13,12 @@ import { cache } from 'acrylblends/cache'
 
 ## Usage
 
-**Cloudflare Workers**
-
-```ts
-app.get(
-  '*',
-  cache({
-    cacheName: 'my-app',
-    cacheControl: 'max-age=3600',
-  })
-)
-```
-
-**Deno**
-
 ```ts
-// Must use `wait: true` for the Deno runtime
 app.get(
   '*',
   cache({
     cacheName: 'my-app',
     cacheControl: 'max-age=3600',
-    wait: true,
   })
 )
 ```
@@ -59,7 +39,7 @@ The name of the cache. Can be used to store multiple caches with different ident
 
 ### *(optional)* wait: `boolean`
 
-A boolean indicating if Acryl should wait for the Promise of the `cache.put` function to resolve before continuing with the request. _Required to be true for the Deno environment_. The default is `false`.
+A boolean indicating if Acryl should wait for the Promise of the `cache.put` function to resolve before continuing with the request. The default is `false`. A runtime whose Cache API only completes a write after the response has finished needs `true`, or the write is dropped.
 
 ### *(optional)* cacheControl: `string`
 

package/docs/framework/middleware/builtin/compress.md

@@ -2,7 +2,7 @@
 
 This middleware compresses the response body, according to `Accept-Encoding` request header.
 
-> **Note.** On Cloudflare Workers and Deno Deploy, the response body will be compressed automatically, so there is no need to use this middleware.
+> **Note.** Node.js and Bun do not compress a response on their own, so this middleware is what compresses it. A host that already compresses at its edge does not need it.
 
 ## Import
 

package/docs/framework/middleware/builtin/context-storage.md

@@ -2,9 +2,7 @@
 
 The Context Storage Middleware stores the Acryl `Context` in the `AsyncLocalStorage`, to make it globally accessible.
 
-> **Note.** This middleware uses `AsyncLocalStorage`. The runtime should support it.
->
-> **Cloudflare Workers**: To enable `AsyncLocalStorage`, add the [`nodejs_compat` or `nodejs_als` flag](https://developers.cloudflare.com/workers/configuration/compatibility-dates/#nodejs-compatibility-flag) to your `wrangler.toml` file.
+> **Note.** This middleware uses `AsyncLocalStorage`. Node.js, the verified runtime, provides it; a host that embeds an app in a runtime without it cannot use this middleware.
 
 ## Import
 
@@ -47,22 +45,20 @@ app.get('/', (c) => {
 })
 ```
 
-On Cloudflare Workers, you can access the bindings outside the handler.
+Anything a handler puts on the context can be read further down the call stack, without passing `c` through every function:
 
 ```ts
-type Env = {
-  Bindings: {
-    KV: KVNamespace
-  }
-}
-
-const app = new Acryl<Env>()
+const app = new Acryl()
 
 app.use(contextStorage())
+app.use(async (c, next) => {
+  c.set('user', 'ada')
+  await next()
+})
 
-const setKV = (value: string) => {
-  return getContext<Env>().env.KV.put('key', value)
-}
+app.get('/', (c) => c.text(`Hello ${getUser()}`))
+
+const getUser = () => getContext().get('user')
 ```
 
 ## tryGetContext

package/docs/framework/middleware/builtin/cors.md

@@ -1,7 +1,6 @@
 # CORS Middleware
 
-There are many use cases of Cloudflare Workers as Web APIs and calling them from external front-end application.
-For them we have to implement CORS, let's do this with middleware as well.
+A web API is often called from a page served by another origin. For that we have to implement CORS, and this middleware does it.
 
 ## Import
 

package/docs/framework/middleware/builtin/jsx-renderer.md

@@ -224,7 +224,7 @@ app.get('/page/info', (c) => {
 
 **Warning.**
 
-You can't use `useRequestContext()` with the Deno's `precompile` JSX option. Use the `react-jsx`:
+You can't use `useRequestContext()` with a JSX option that precompiles the templates ahead of the build. Use `react-jsx`:
 
 ```json
    "compilerOptions": {

package/docs/framework/middleware/builtin/logger.md

@@ -32,7 +32,7 @@ By using the Logger Middleware, you can easily monitor the flow of requests and
 You can also extend the middleware further by providing your own `PrintFunc` function for tailored logging behavior.
 
 > **Tip.**
-> To disable _status code coloring_, you can set a `NO_COLOR` environment variable. This is a common way to disable ANSI color escape codes in logging libraries, and is described at <https://no-color.org/>. Note that Cloudflare Workers do not have a `process.env` object, so will default to plaintext log output.
+> To disable _status code coloring_, you can set a `NO_COLOR` environment variable. This is a common way to disable ANSI color escape codes in logging libraries, and is described at <https://no-color.org/>.
 
 ## PrintFunc
 

package/docs/framework/middleware/builtin/mount.md

@@ -29,7 +29,7 @@ app.all('/itty-router/*', mount(ittyRouter.handle))
 
 By default, the mounted application receives a new `Request` with the matched path prefix removed from its URL. A request to `/itty-router/hello` reaches itty-router as `/hello`.
 
-The mounted application is called as `handler(request, c.env, c.executionCtx)`, the same arguments as a Cloudflare Workers `fetch` handler. Use `optionHandler` to pass different arguments.
+The mounted application is called as `handler(request, c.env, c.executionCtx)`, the three arguments a `fetch`-style handler takes. Use `optionHandler` to pass different arguments.
 
 ## Options
 

package/docs/framework/middleware/builtin/request-id.md

@@ -72,23 +72,16 @@ The header name used for the request ID. The default is `X-Request-Id`.
 
 The request ID generation function. By default, it uses `crypto.randomUUID()`.
 
-## Platform specific Request IDs
-
-Some platform (such as AWS Lambda) already generate their own Request IDs per request.
-Without any additional configuration, this middleware is unaware of these specific Request IDs
-and generates a new Request ID. This can lead to confusion when looking at your application logs.
-
-To unify these IDs, use the `generator` function to capture the platform specific Request ID and to use it in this middleware.
-
-### Platform specific links
-
-- AWS Lambda
-  - [AWS documentation: Context object](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-context.html)
-  - Acryl: Access AWS Lambda Object
-- Cloudflare
-  - [Cloudflare Ray ID
-    ](https://developers.cloudflare.com/fundamentals/reference/cloudflare-ray-id/)
-- Deno
-  - [Request ID on the Deno Blog](https://deno.com/blog/zero-config-debugging-deno-opentelemetry#:~:text=s%20automatically%20have-,unique%20request%20IDs,-associated%20with%20them)
-- Fastly
-  - [Fastly documentation: req.xid](https://www.fastly.com/documentation/reference/vcl/variables/client-request/req-xid/)
+## An ID that came from earlier in the chain
+
+A proxy, a load balancer or the host that starts the app may already put a request id on the request.
+Without configuration this middleware is unaware of it and generates a new one, which makes the two logs hard to line up.
+Use the `generator` function to read the incoming one and fall back to a fresh id:
+
+```ts
+app.use(
+  requestId({
+    generator: (c) => c.req.header('X-Request-Id') ?? crypto.randomUUID(),
+  })
+)
+```

package/docs/framework/middleware/builtin/timing.md

@@ -3,8 +3,7 @@
 The [Server-Timing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing) Middleware provides
 performance metrics in the response headers.
 
-> **Note.** On Cloudflare Workers, the timer metrics may not be accurate,
-> since [timers only show the time of last I/O](https://developers.cloudflare.com/workers/learning/security-model/#step-1-disallow-timers-and-multi-threading).
+> **Note.** The metrics come from timers around the handler, so they measure wall-clock time on the host the app runs on.
 
 ## Import
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",